22 KiB
22 KiB
🦊 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
# 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
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:
- Hold the power button for 10 seconds
- Connect the charger
- 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:
- Log in to your account
- Go to 'My Orders'
- Click 'Return' on the product
- 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
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
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)
# 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