# 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 complete. 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 structure with welcome screen
- `script.js` - Chat interaction logic with SSE streaming
- `style.css` - Catppuccin Mocha theme with pixel aesthetic

**Backend:**
- `backend/app/main.py` - FastAPI application entry point
- `backend/app/config.py` - Environment configuration
- `backend/app/api/chat.py` - Chat endpoints (POST /api/chat, POST /api/chat/stream)
- `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:**
```bash
docker compose up -d --build
```

**View logs:**
```bash
docker compose logs -f backend
docker compose logs -f frontend
```

**Stop the application:**
```bash
docker compose down
```

**Test backend API:**
```bash
# Health check
curl http://localhost:8000/health

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

# Test chat (non-streaming)
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -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)