102 lines
3.5 KiB
Markdown
102 lines
3.5 KiB
Markdown
# 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:**
|
|
```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
|
|
|
|
# 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)
|