diff --git a/README.md b/README.md index 60b2b0b..7ac984a 100644 --- a/README.md +++ b/README.md @@ -1,391 +1,19 @@ -## DevDen +Project Status: Concept / Proof of Concept -**Your AI assistant, powered by your knowledge** +Important: +DevDen is a concept project / proof of concept. +It was created to explore ideas, architecture, and potential workflows, not as production-ready software. ---- +This project is: -## 🚀 Quick Start +Not intended for use in production environments -### Prerequisites -- Docker and Docker Compose installed -- API key from [Anthropic](https://console.anthropic.com/) or [OpenAI](https://platform.openai.com/api-keys) -- Microsoft Entra ID app registration (for authentication) +Not security-audited -### Setup +Not guaranteed to be stable, complete, or maintainable -1. **Clone the repository** -```bash -git clone https://github.com/yourusername/devden.git -cd devden -``` +Not provided with SLAs, support, or long-term maintenance -2. **Configure environment variables** -```bash -cp .env.example .env -# Edit .env and add your API keys and Entra ID credentials -``` +All documentation, configuration examples, and cost estimates are illustrative only and meant to explain the concept and technical direction. -3. **Set up Microsoft Entra ID** (Azure AD) - - Sign in to the [Azure Portal - App Registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps) page using an account that can manage Entra applications. - - Create a new app registration named something like “DevDen Auth” and choose “Accounts in this organizational directory only” (single tenant) unless you explicitly need multi-tenant access. - - Under **Authentication**, register the redirect URI `http://localhost:3000/auth/callback` (or your deployed URL if you are not running locally) and enable the **ID tokens (used for implicit flows)** checkbox. - - Click **Save**, then go to **API permissions** and add the **Microsoft Graph > User.Read (delegated)** permission, clicking **Grant admin consent** afterward so DevDen can read the signed-in user’s profile. - - Open **Certificates & secrets**, create a new client secret, give it a descriptive name, and copy the value immediately (it is hidden after leaving the page). - - Capture the Tenant ID, Client ID, and the client secret value and paste them into your `.env` as `ENTRA_TENANT_ID`, `ENTRA_CLIENT_ID`, and `ENTRA_CLIENT_SECRET`. If you changed the redirect URI, also update `ENTRA_REDIRECT_URI` to match what you entered in Entra ID. - - Optionally configure application roles and group claims if you want to limit access to specific users/groups, then run `docker compose down && docker compose up -d --build` to ensure the backend reloads the updated secret values. - - Test the login flow by visiting `http://localhost:3000`, clicking **Login with Microsoft**, and confirming you are redirected back with a chat session. If you see a “redirect_uri_mismatch” error, double-check the URI in both the portal and your `.env` file. - -4. **Start the services** -```bash -docker compose up -d --build -``` - -5. **Access DevDen** -- Frontend: http://localhost:3000 -- Backend API: http://localhost:8000 -- Health Check: http://localhost:8000/health - -### Environment Variables - -Required variables in `.env`: -```bash -# AI Providers (at least one required) -ANTHROPIC_API_KEY=your_key_here # For Claude -OPENAI_API_KEY=your_key_here # For OpenAI -DEFAULT_PROVIDER=claude # claude or openai - -# Microsoft Entra ID (required for authentication) -ENTRA_TENANT_ID=your-tenant-id -ENTRA_CLIENT_ID=your-client-id -ENTRA_CLIENT_SECRET=your-client-secret - -# JWT (change in production) -JWT_SECRET=generate-a-secure-random-string -``` - ---- - -## What is DevDen? - -DevDen is a self-hosted AI chat platform that lets people ask questions and get answers from AI providers like Claude, OpenAI, Gemini, and others. The key difference? As an administrator, you control what knowledge the AI has access to by connecting your own documentation, manuals, wikis, or any other information sources. - -Think of it as giving your users a smart assistant that knows exactly what's in your company documentation, support guides, or knowledge bases - without them having to search through files themselves. - ---- - -## Who is it for? - -**Companies** - Employees can ask questions about HR policies, procedures, or internal processes - -**Support Teams** - Customers get instant answers based on your product documentation - -**Organizations** - Members can query policies, regulations, or guidelines - -**Communities** - Users can get answers about rules, resources, or FAQs - ---- - -## How does it work? - -**For Users (the simple part):** - -1. User visits DevDen and logs in with their Microsoft account -2. User types a question in the chat interface -3. AI reads the question, searches your knowledge base, and provides an answer -4. User can see where the answer came from (which document or page) -5. Conversation is saved so they can refer back to it later - -That's it. No training needed, no complicated setup for end users. - -**For You (the admin):** - -1. You set up DevDen with Docker Compose on your server -2. You add your API keys for the AI providers you want to use -3. You connect your knowledge bases (either from Git repositories or local folders) -4. You configure who can access DevDen via Microsoft Entra ID -5. You monitor usage, costs, and manage everything through the admin dashboard - -DevDen automatically indexes your documentation, and when users ask questions, it finds the relevant information and gives it to the AI as context. - ---- - -## Two Different Interfaces - -**Clean Chat Interface (for regular users)** - -A simple, friendly chat interface that looks like WhatsApp or any modern messaging app. Users just type questions and get answers. No technical knowledge required. Perfect for employees, customers, or community members. - -**Terminal-Style Dashboard (for you, the admin)** - -A more technical, terminal-inspired interface where you manage everything: knowledge bases, AI providers, user access, usage statistics, and costs. This gives you full control over the platform. - ---- - -## Knowledge Base Options - -You can connect your documentation in two ways: - -**Git Repositories** - -Connect any Git repository (GitHub, GitLab, etc.) and DevDen will automatically clone and index it. Whenever you update the documentation in Git, DevDen can automatically sync and re-index the new content. - -Great for: Documentation that multiple people maintain, version-controlled content, automated workflows - -**Docker Volumes** - -Mount a local folder with your documents and DevDen will index everything inside. Any changes to files are detected and the index updates automatically. - -Great for: Local files, quick setup, direct file system access - -DevDen can index markdown files, text files, PDFs, Word documents, and more. - ---- - -## AI Provider Flexibility - -You're not locked into a single AI provider. DevDen supports: - -- **Claude** (Anthropic) - Sonnet, Opus, Haiku models -- **OpenAI** - GPT-4 and other models -- **OpenRouter** - Access to many different AI models through one API -- **Google Gemini** - Google's AI models -- **Ollama** - Run AI models locally on your own hardware (no API costs) - -You can set a default provider, allow users to choose, or even set up automatic fallbacks if one provider is having issues. - ---- - -## Authentication & Security - -**Microsoft Entra ID Integration** - -Users log in with their existing Microsoft/Azure AD accounts. No need to create separate accounts or remember new passwords. - -You control: -- Which users or groups can access DevDen -- How many questions users can ask per day -- Which knowledge bases different users can access - -**Data Privacy** - -Everything runs on your server. Conversations are stored in your database, not with the AI providers. Knowledge bases never leave your infrastructure. Only the actual questions and selected context are sent to the AI provider's API. - ---- - -## What Makes DevDen Special? - -**Context-Aware Answers** - -Instead of generic AI responses, users get answers specific to your organization because the AI has access to your documentation. - -**Source Transparency** - -Every answer shows which documents or pages were used, so users can verify information or read more if they want. - -**Full Control** - -You decide which AI providers to use, what documentation to include, who has access, and you can see all usage statistics and costs. - -**Self-Hosted** - -Your data stays on your server. No external service has access to your knowledge base or user conversations. - -**Cost Effective** - -Only pay for what you use. AI providers charge per token/request, so you only pay when users ask questions. Running DevDen itself just requires a server (or even just a computer with Docker). - ---- - -## Example Use Cases - -**HR Support Bot** - -Knowledge Base: Employee handbook, vacation policies, benefits documentation - -Questions users ask: -- "How many vacation days do I have?" -- "What's the parental leave policy?" -- "How do I submit an expense report?" - -**IT Helpdesk** - -Knowledge Base: IT documentation, troubleshooting guides, software manuals - -Questions users ask: -- "How do I reset my password?" -- "My laptop won't connect to WiFi, what should I do?" -- "Which VPN should I use for remote work?" - -**Customer Support** - -Knowledge Base: Product documentation, FAQs, return policies - -Questions customers ask: -- "How do I set up my new device?" -- "What's your return policy?" -- "Is this product compatible with X?" - -**Internal Wiki Alternative** - -Instead of employees searching through wiki pages, they just ask DevDen and get instant answers with sources. - ---- - -## Technical Overview - -**What You Need** - -- A server (VPS, cloud instance, or even a local machine) -- Docker and Docker Compose installed -- API keys for the AI providers you want to use -- Microsoft Entra ID tenant for authentication -- Your documentation/knowledge base ready - -**What DevDen Includes** - -- Web-based chat interface (frontend) -- API backend (FastAPI with Python) -- PostgreSQL database (stores users, conversations, settings) -- Redis (caching and session management) -- Vector database (Qdrant or ChromaDB - for semantic search in your docs) -- Optional: Ollama container (for local AI models) - -Everything runs in Docker containers, making it easy to deploy and manage. - ---- - -## Admin Features - -**Knowledge Base Management** - -- Add/remove knowledge bases -- Enable/disable specific knowledge bases -- See sync status and last update time -- View how many documents are indexed -- Configure auto-sync intervals - -**User Management** - -- See all active users -- View per-user usage statistics -- Set usage limits (questions per day/month) -- Control access to specific knowledge bases -- Export user data (GDPR compliance) - -**Provider Settings** - -- Configure multiple AI providers -- Set default provider and model -- Add/rotate API keys -- Monitor API usage and costs -- Set up fallback providers - -**Analytics Dashboard** - -- Total questions asked (today/week/month) -- Most active users -- Most asked topics -- Response times -- Cost tracking per provider -- Most used knowledge bases - -**System Monitoring** - -- Health status of all services -- Database connection status -- Vector database status -- API provider connectivity -- Error logs and alerts - ---- - -## Development Phases - -**Phase 1: Basic Chat** - -Get a working chat interface where users can ask questions and get answers from Claude or OpenAI. - -**Phase 2: Knowledge Base** - -Add document indexing and semantic search so the AI can use your documentation. - -**Phase 3: Authentication** - -Integrate Microsoft Entra ID so users can securely log in. - -**Phase 4: Admin Dashboard** - -Build the admin interface so you can manage everything. - -**Phase 5: Multi-Provider** - -Add support for multiple AI providers and switching between them. - -**Phase 6: Git Integration** - -Add automatic syncing from Git repositories. - -**Phase 7: Polish** - -Add all the nice-to-have features like conversation export, mobile responsiveness, advanced search, etc. - ---- - -## Why "DevDen"? - -The name combines "Dev" (short for development or device - it's a tool for building better workflows) with "Den" (a cozy, safe space - like a fox's burrow). - -The fox mascot represents intelligence, adaptability, and resourcefulness - just like the platform itself. The "den" is where knowledge lives, protected and organized, ready to be accessed when needed. - -Plus, it fits nicely with your other project names like Burrow and Bean Den, keeping that warm, cozy aesthetic. - ---- - -## Cost Estimation - -For a small organization (50 users, 1000 questions per month): - -**AI Costs:** -- Claude Sonnet: around 10-15 dollars per month -- OpenAI GPT-4: around 25-35 dollars per month -- Ollama (local): free, just electricity - -**Hosting:** -- Small VPS: 20-40 dollars per month -- Or self-host: just electricity - -**Total: Roughly 30-75 dollars per month depending on usage and provider choice** - -Much cheaper than enterprise chat platforms or support desk solutions, and you have full control. - ---- - -## Privacy & Compliance - -**Data Residency** - -All data stays on your server. Conversations, user data, and knowledge bases are stored in your database, not on external servers. - -**GDPR Compliant** - -Users can request to see their data or have it deleted. Admin tools make this easy to manage. - -**Audit Logs** - -All admin actions are logged. You can see who did what and when. - -**Encryption** - -API keys are encrypted in the database. Conversations can be encrypted at rest. HTTPS for all traffic. - ---- - -## Next Steps - -If you want to build DevDen, the next step would be to create: - -1. A detailed technical architecture document -2. Database schema design -3. API endpoint specifications -4. UI/UX wireframes and mockups -5. A development roadmap with specific tasks +Any use of this project (or parts of it) in a production environment is entirely at your own risk. \ No newline at end of file