## 🦊 **DevDen** **Tagline:** *"Your AI assistant, powered by your knowledge"* --- ## 🎯 **What is DevDen?** DevDen is a self-hosted AI chat platform where users can ask questions to different AI providers (Claude, OpenAI, etc.). As an administrator, you configure the knowledge bases (e.g., company documentation, manuals, internal wikis), allowing the AI to provide accurate answers based on your specific information. **Use Cases:** - **Companies**: Employees can ask questions about business processes, HR policies, IT support - **Support Teams**: Customers get AI-powered support with access to product documentation - **Organizations**: Members get answers about regulations, procedures, FAQs - **Communities**: Community members can ask questions about guidelines, resources --- ## 👥 **Two Roles** ### **Administrator (you)** - Configures AI providers (API keys) - Manages knowledge bases (git repos, volumes) - Sets up users and access (via Entra ID) - Monitors usage and costs - Controls what information the AI uses ### **Users (end users)** - Login via Microsoft account - Ask questions in terminal-style chat - Get answers from AI + your knowledge base - See their chat history - Simple and accessible - no tech knowledge needed --- ## 💬 **User Experience (end user)** ### **Simple and Direct** ``` ╔════════════════════════════════════════════════╗ ║ 🦊 DevDen Chat [⚙️] ║ ╠════════════════════════════════════════════════╣ ║ ║ ║ You: What is the vacation policy? ║ ║ ║ ║ AI: Based on the employee handbook... ║ ║ You are entitled to 25 vacation days per ║ ║ year... ║ ║ ║ ║ 📎 Source: HR Handbook 2024, page 12 ║ ║ ║ ║ You: And how do I request it? ║ ║ ║ ║ AI: You can request vacation through... ║ ║ ║ ║ Your question: █ ║ ╚════════════════════════════════════════════════╝ ``` **Users see:** - Clean chat interface (no complicated options) - Simple question/answer flow - Where the answer comes from (transparency) - Their previous conversations - *Optional: ability to choose AI provider if you allow it* --- ## ⚙️ **Admin Dashboard** You as administrator have a separate admin interface: ### **Knowledge Base Management** ``` 📚 Knowledge Bases ✓ HR Handbook [Git: company/hr-docs] ✓ IT Support Docs [Volume: /data/it-docs] ✓ Product Catalog [Git: company/products] ○ Inactive KB [Disabled] [+ Add Knowledge Base] ``` **Per Knowledge Base:** - On/Off toggle (activate/deactivate) - Sync status (last update) - Number of indexed documents - Content preview ### **Provider Settings** ``` 🤖 AI Providers ✓ Claude Sonnet 4 [Default] API Key: ••••••••••1234 Max tokens: 4000 Cost per 1M tokens: $3.00 ✓ OpenAI GPT-4 API Key: ••••••••••5678 [Fallback provider] ○ Ollama (Local) [Disabled] ``` ### **User Management** ``` 👥 Users (via Microsoft Entra ID) Active Users: 42 - john@company.com Last active: 2 min ago - lisa@company.com Last active: 1 hour ago - ... Usage Stats: - Total questions today: 127 - Avg response time: 2.3s - Most asked topic: HR policies ``` ### **Analytics Dashboard** ``` 📊 Usage Overview Today: 127 questions This week: 892 questions This month: 3,421 questions Top Topics: 1. HR policies (34%) 2. IT support (28%) 3. Product info (22%) 4. Other (16%) Cost Overview: - This month: $45.20 - Avg per question: $0.013 ``` --- ## 🏗️ **Architecture (simplified)** ### **For end users** ``` User → Login (Microsoft) → Chat Interface → AI answer ↓ Knowledge Base ``` ### **Technical** ``` Frontend (Chat UI) ↓ Backend API ↓ ┌─────────────┬──────────────┬─────────────┐ │ AI Provider │ Knowledge DB │ User Auth │ │ (Claude/etc)│ (Vector DB) │ (Entra ID) │ └─────────────┴──────────────┴─────────────┘ ``` --- ## 📚 **Knowledge Base Setup (Admin)** ### **Option 1: Git Repository** ```yaml # Admin configures in UI or config file knowledge_base: name: "HR Documentation" type: git url: "https://github.com/company/hr-docs" branch: main auto_sync: hourly enabled: true ``` **Benefits:** - Automatic updates on git push - Version control - Multiple people can update documentation ### **Option 2: Docker Volume** ```yaml knowledge_base: name: "IT Support Docs" type: volume path: "/data/it-docs" watch: true # Auto-refresh on file changes enabled: true ``` **Benefits:** - Direct filesystem access - Easy for local files - Real-time updates ### **What gets indexed?** - Markdown files (`.md`) - Text files (`.txt`) - PDFs (text extraction) - Word documents (`.docx`) - *Optional: HTML, JSON, CSV, etc.* --- ## 🎨 **User Interface Styles** ### **Option 1: Terminal Style (for you as admin)** Terminal aesthetic, tech-savvy look, everything you saw before. ### **Option 2: Clean Chat (for end users)** More like modern chat apps (WhatsApp, iMessage): - Large, clear text - Clean message bubbles - Minimal UI chrome - Mobile-friendly - Accessible for non-tech people ``` ┌────────────────────────────────────┐ │ │ │ What is the vacation policy? ○ │ │ │ │ ○ Based on the employee │ │ handbook you are entitled │ │ to 25 vacation days... │ │ │ │ 📎 HR Handbook 2024 │ │ │ │ Type your question... [→]│ └────────────────────────────────────┘ ``` **Or both:** - Admin interface = terminal style - User interface = clean chat style --- ## 🔐 **Authentication Flow** ``` 1. User goes to devden.company.com 2. "Login with Microsoft" button 3. Redirect to Microsoft login 4. After login → back to DevDen chat 5. User can ask questions ``` **Admin can configure:** - Which Microsoft groups/users have access - Per-user quotas (max X questions per day) - Access to specific knowledge bases --- ## 💡 **Practical Examples** ### **Example 1: HR Support** **Knowledge Base:** HR handbook, vacation policy, employment terms **User question:** "How many vacation days do I get after 4 years of service?" **AI answer:** "After 4 years of service, you are entitled to 27 vacation days per year (25 base + 2 extra for seniority). 📎 Source: HR Handbook 2024, section 3.2 'Vacation Policy'" --- ### **Example 2: IT Support** **Knowledge Base:** IT documentation, troubleshooting guides, FAQ **User question:** "My laptop won't start, what should I do?" **AI answer:** "Try these steps first: 1. Hold the power button for 10 seconds 2. Connect the charger 3. Try restarting again If this doesn't work, create a ticket at servicedesk@company.com 📎 Source: IT Support Guide - Laptop Troubleshooting" --- ### **Example 3: Customer Support** **Knowledge Base:** Product documentation, FAQ, return policy **User question:** "How can I return a product?" **AI answer:** "You can return products within 30 days: 1. Log in to your account 2. Go to 'My Orders' 3. Click 'Return' on the product 4. Print the return label Returns are free within the US. 📎 Source: Return Policy 2024" --- ## 🚀 **MVP Feature Set** ### **For Users:** - [ ] Login via Microsoft - [ ] Chat interface (simple and clean) - [ ] Ask questions → get AI answers - [ ] See which sources were used - [ ] View chat history - [ ] Export conversation ### **For Admin (you):** - [ ] Add knowledge base (git/volume) - [ ] Configure AI provider - [ ] Manage user access - [ ] View usage stats - [ ] Cost tracking - [ ] Toggle KB on/off ### **Technical:** - [ ] FastAPI backend - [ ] Docker Compose setup - [ ] Vector DB for KB search - [ ] Entra ID integration - [ ] Multi-provider support (Claude, OpenAI, etc.) --- ## 📂 **Project Structure** ``` devden/ ├── docker-compose.yml ├── .env.example ├── frontend/ │ ├── src/ │ │ ├── components/ │ │ │ ├── chat/ │ │ │ │ ├── ChatInterface.svelte │ │ │ │ ├── MessageBubble.svelte │ │ │ │ └── InputBox.svelte │ │ │ └── admin/ │ │ │ ├── Dashboard.svelte │ │ │ ├── KnowledgeBaseManager.svelte │ │ │ ├── ProviderSettings.svelte │ │ │ └── UserManagement.svelte │ │ ├── stores/ │ │ └── routes/ │ └── package.json ├── backend/ │ ├── app/ │ │ ├── main.py │ │ ├── api/ │ │ │ ├── chat.py # Chat endpoints │ │ │ ├── auth.py # Entra ID auth │ │ │ ├── admin.py # Admin endpoints │ │ │ └── kb.py # KB management │ │ ├── services/ │ │ │ ├── provider_manager.py # AI provider abstraction │ │ │ ├── kb_indexer.py # Index documents │ │ │ ├── vector_search.py # Semantic search │ │ │ └── chat_service.py # Chat logic │ │ ├── models/ │ │ │ ├── user.py │ │ │ ├── conversation.py │ │ │ ├── knowledge_base.py │ │ │ └── provider.py │ │ └── core/ │ │ ├── config.py │ │ └── security.py │ └── requirements.txt ├── knowledge-bases/ # Volume mount for KBs └── docs/ ├── README.md ├── SETUP.md └── ADMIN_GUIDE.md ``` --- ## 🔧 **Configuration Example** ### **docker-compose.yml** ```yaml version: '3.8' services: devden-web: build: . ports: - "3000:3000" environment: - DATABASE_URL=postgresql://devden:password@db:5432/devden - REDIS_URL=redis://redis:6379 - VECTOR_DB_URL=http://qdrant:6333 volumes: - ./knowledge-bases:/app/knowledge-bases depends_on: - db - redis - qdrant db: image: postgres:16 environment: POSTGRES_DB: devden POSTGRES_USER: devden POSTGRES_PASSWORD: password volumes: - postgres_data:/var/lib/postgresql/data redis: image: redis:7-alpine volumes: - redis_data:/data qdrant: image: qdrant/qdrant:latest ports: - "6333:6333" volumes: - qdrant_data:/qdrant/storage ollama: image: ollama/ollama:latest volumes: - ollama_data:/root/.ollama # Optional: only if you want local models volumes: postgres_data: redis_data: qdrant_data: ollama_data: ``` ### **config.yaml** ```yaml devden: name: "Company DevDen" admin_email: "mats@company.com" ui: theme: cappuccino user_interface: clean_chat admin_interface: terminal providers: claude: enabled: true default_model: claude-sonnet-4 api_key_env: CLAUDE_API_KEY openai: enabled: true default_model: gpt-4-turbo api_key_env: OPENAI_API_KEY openrouter: enabled: true api_key_env: OPENROUTER_API_KEY gemini: enabled: true api_key_env: GEMINI_API_KEY ollama: enabled: false endpoint: http://ollama:11434 knowledge_bases: - name: hr_handbook type: git url: https://github.com/company/hr-docs branch: main auto_sync: true sync_interval: 1h enabled: true - name: it_support type: volume path: /app/knowledge-bases/it-docs watch: true file_patterns: ["*.md", "*.txt", "*.pdf"] enabled: true auth: provider: entra_id tenant_id: ${ENTRA_TENANT_ID} client_id: ${ENTRA_CLIENT_ID} client_secret: ${ENTRA_CLIENT_SECRET} redirect_uri: http://localhost:3000/auth/callback # Optional: restrict to specific groups allowed_groups: - "DevDen Users" - "IT Support Team" limits: max_questions_per_user_per_day: 100 max_tokens_per_response: 4000 conversation_retention_days: 90 ``` --- ## 🎯 **Development Roadmap** ### **Phase 1: Core Chat (Week 1-2)** **Goal:** Basic working chat with one AI provider - [ ] Docker Compose setup - [ ] FastAPI backend skeleton - [ ] Simple chat UI (web interface) - [ ] PostgreSQL database setup - [ ] Claude API integration - [ ] Basic conversation storage - [ ] WebSocket for streaming responses **Deliverable:** Users can ask questions and get answers from Claude --- ### **Phase 2: Knowledge Base (Week 3-4)** **Goal:** AI can use your documentation to answer questions - [ ] Vector database (Qdrant) integration - [ ] Document indexer (markdown, txt, pdf) - [ ] Volume-based KB support - [ ] Chunking & embedding service - [ ] Semantic search implementation - [ ] Context injection into prompts - [ ] Show sources in chat UI **Deliverable:** AI answers questions using your knowledge base --- ### **Phase 3: Authentication (Week 5)** **Goal:** Secure access with Microsoft Entra ID - [ ] Entra ID OAuth2 flow - [ ] User session management - [ ] JWT token handling - [ ] User database schema - [ ] Login/logout UI - [ ] Protected API routes **Deliverable:** Users must login with Microsoft to access DevDen --- ### **Phase 4: Admin Dashboard (Week 6)** **Goal:** You can manage everything via UI - [ ] Admin authentication & authorization - [ ] KB management UI (add/remove/toggle) - [ ] Provider settings UI - [ ] User management UI - [ ] Usage statistics dashboard - [ ] Cost tracking **Deliverable:** Complete admin control panel --- ### **Phase 5: Multi-Provider (Week 7)** **Goal:** Support multiple AI providers - [ ] Provider abstraction layer - [ ] OpenAI integration - [ ] OpenRouter integration - [ ] Gemini integration - [ ] Provider selection logic - [ ] Fallback mechanism **Deliverable:** Users can use different AI providers --- ### **Phase 6: Git Integration (Week 8)** **Goal:** Auto-sync knowledge bases from Git - [ ] Git clone/pull service - [ ] Webhook support for auto-sync - [ ] Branch selection - [ ] Scheduled sync jobs - [ ] Git KB UI in admin panel **Deliverable:** Knowledge bases auto-update from Git repos --- ### **Phase 7: Polish & Features (Week 9-10)** **Goal:** Production-ready platform - [ ] Conversation history UI - [ ] Export conversations (markdown, JSON) - [ ] Search in chat history - [ ] Mobile responsive design - [ ] Error handling & logging - [ ] Rate limiting - [ ] Health checks & monitoring - [ ] Documentation **Deliverable:** Production-ready DevDen --- ## 💰 **Cost Estimation** ### **AI Provider Costs (example)** Based on 1000 questions per month: ``` Scenario: Average question uses 500 input tokens + 1000 output tokens Claude Sonnet 4: - Input: 1000 × 500 = 500k tokens - Output: 1000 × 1000 = 1M tokens - Cost: ~$4.50/month OpenAI GPT-4 Turbo: - Similar usage - Cost: ~$15/month With KB context (adds ~2k tokens per question): - Claude: ~$12/month - OpenAI: ~$35/month ``` **Hosting Costs:** - VPS (4GB RAM, 2 CPU): ~$20/month - Or self-host: electricity costs only **Total: ~$35-55/month for 1000 questions** --- ## 🦊 **Visual Identity** ### **Logo Concept** A cozy fox in a den/burrow with a chat bubble, surrounded by documents/books (knowledge bases). Warm, friendly, accessible. ### **Color Themes** **Cappuccino (default for users)** ``` Background: #f5f1ed (warm cream) Text: #2d2419 (dark brown) Accent: #8b4513 (saddle brown) Bubble (user): #d4a574 (tan) Bubble (AI): #e8d5b7 (light tan) ``` **Terminal (for admin)** ``` Background: #1a1410 (deep brown) Text: #e8d5b7 (cream) Accent: #8b4513 (saddle brown) Highlight: #d4a574 (tan) ``` --- ## 🎨 **UI Mockups** ### **User Chat Interface (Clean Style)** ``` ┌─────────────────────────────────────────────┐ │ 🦊 DevDen John Doe │ ├─────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────┐ │ │ │ What is the vacation policy? │ │ │ └─────────────────────────────────────┘ │ │ 12:34 PM │ │ │ │ ┌─────────────────────────────────────┐ │ │ │ Based on the employee handbook, │ │ │ │ you are entitled to 25 vacation │ │ │ │ days per year. │ │ │ │ │ │ │ │ 📎 HR Handbook 2024, page 12 │ │ │ └─────────────────────────────────────┘ │ │ 12:34 PM │ │ │ │ ┌─────────────────────────────────────┐ │ │ │ How do I request vacation? │ │ │ └─────────────────────────────────────┘ │ │ 12:35 PM │ │ │ │ ┌─────────────────────────────────────┐ │ │ │ You can request vacation through... │ │ │ └─────────────────────────────────────┘ │ │ │ ├─────────────────────────────────────────────┤ │ Type your question... [Send]│ └─────────────────────────────────────────────┘ ``` ### **Admin Dashboard (Terminal Style)** ``` ╔═══════════════════════════════════════════════╗ ║ 🦊 DevDen Admin [Logout] ║ ╠═══════════════════════════════════════════════╣ ║ ║ ║ admin@devden:~$ dashboard ║ ║ ║ ║ ┌─ System Status ─────────────────────────┐ ║ ║ │ ✓ Backend API Running │ ║ ║ │ ✓ Database Connected │ ║ ║ │ ✓ Vector DB Healthy │ ║ ║ │ ✓ Claude API Active │ ║ ║ └─────────────────────────────────────────┘ ║ ║ ║ ║ ┌─ Usage Today ───────────────────────────┐ ║ ║ │ Questions: 127 │ ║ ║ │ Active Users: 24 │ ║ ║ │ Avg Response Time: 2.3s │ ║ ║ │ Cost: $1.45 │ ║ ║ └─────────────────────────────────────────┘ ║ ║ ║ ║ admin@devden:~$ kb list ║ ║ ║ ║ ✓ hr_handbook [Git] 1,234 docs ║ ║ ✓ it_support [Vol] 567 docs ║ ║ ○ product_catalog [Git] Disabled ║ ║ ║ ║ admin@devden:~$ █ ║ ╚═══════════════════════════════════════════════╝ ``` --- ## 🚀 **Quick Start Guide (Future)** ```bash # Clone repository git clone https://github.com/mats/devden cd devden # Configure environment cp .env.example .env # Edit .env with your: # - API keys (Claude, OpenAI, etc.) # - Entra ID credentials # - Database passwords # Configure knowledge bases cp config.example.yaml config.yaml # Edit config.yaml with your KB sources # Start with Docker Compose docker-compose up -d # Initialize database docker-compose exec devden-web python manage.py init-db # Create admin user docker-compose exec devden-web python manage.py create-admin \ --email mats@company.com # Access DevDen # Users: http://localhost:3000 # Admin: http://localhost:3000/admin # View logs docker-compose logs -f devden-web ``` --- ## 🔒 **Security Considerations** ### **Data Protection** - All API keys encrypted at rest - User conversations encrypted in database - HTTPS only in production - Secure session management - No AI provider gets user identity ### **Access Control** - Entra ID for authentication - Role-based access (user/admin) - Per-user rate limiting - Audit logs for all admin actions - IP whitelisting option ### **Privacy** - Conversations stored locally (not with AI providers) - Users can delete their history - Admin can export/delete user data (GDPR compliance) - No telemetry or tracking - Knowledge base never leaves your server ---