DevDen/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

DevDen is a self-hosted AI chat platform that enables organizations to provide AI-powered Q&A based on their own knowledge bases. Users interact through a clean chat interface while administrators manage knowledge bases, AI providers, and user access through a terminal-style dashboard.

Current Status: MVP with AI integration and Microsoft Entra ID authentication. Backend FastAPI server with Claude and OpenAI support. Frontend streams responses in real-time.

Architecture

Technology Stack:

• Frontend: Vanilla JavaScript (prototype), potential migration to Svelte
• Backend: FastAPI (Python)
• Database: PostgreSQL (users, conversations, settings)
• Cache: Redis (sessions)
• Vector DB: Qdrant or ChromaDB (semantic search)
• Auth: Microsoft Entra ID
• AI Providers: Claude, OpenAI, Gemini, OpenRouter, Ollama (local)

Two-Interface Design:

• Clean chat interface for end users (warm, accessible design)
• Terminal-style dashboard for administrators

Current Files

Frontend:

• index.html - Main chat interface with login, welcome, and chat screens
• script.js - Chat interaction logic with SSE streaming and auth handling
• style.css - Catppuccin Mocha theme with pixel aesthetic

Backend:

• backend/app/main.py - FastAPI application entry point
• backend/app/config.py - Environment configuration (AI providers, Entra ID, JWT)
• backend/app/api/chat.py - Chat endpoints (POST /api/chat, POST /api/chat/stream) - protected
• backend/app/api/auth.py - Auth endpoints (login, callback, me, logout, status)
• backend/app/middleware/auth.py - JWT validation middleware
• backend/app/services/provider_manager.py - Provider abstraction and fallback
• backend/app/services/provider_claude.py - Claude implementation
• backend/app/services/provider_openai.py - OpenAI implementation
• backend/app/models/schemas.py - Pydantic request/response models

Infrastructure:

• docker-compose.yml - Multi-service orchestration
• backend/Dockerfile.backend - Backend container
• .env.example - Environment template

Development Phases (from project.md)

1. Core Chat - Basic chat with single AI provider
2. Knowledge Base - Document indexing and semantic search
3. Authentication - Microsoft Entra ID integration
4. Admin Dashboard - Management interface
5. Multi-Provider - Multiple AI provider support
6. Git Integration - Auto-sync from repositories
7. Polish - Production readiness

Commands

Start the application:

docker compose up -d --build

View logs:

docker compose logs -f backend
docker compose logs -f frontend

Stop the application:

docker compose down

Test backend API:

# Health check
curl http://localhost:8000/health

# Check auth status
curl http://localhost:8000/api/auth/status

# List available providers
curl http://localhost:8000/api/chat/providers

# Test chat (requires JWT token from auth flow)
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"message": "Hello!"}'

Design Decisions

• Knowledge bases connect via Git repositories (auto-sync) or Docker volumes (local files)
• Source transparency: answers show which documents were referenced
• User quotas configurable per-user (questions per day/month)
• API keys encrypted at rest
• All data stays on-premises (self-hosted)