Back to AI Docs
Architecture
The Codmir AI system consists of two main services that work together to provide intelligent, project-aware responses.
System Overview
┌─────────────────────────────────────────────────────────────────┐
│ Web App (Next.js) │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ useAIChat │ │ useAITask │ │ AIClient │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
└─────────┼────────────────┼────────────────┼─────────────────────┘
│ │ │
│ Internal API │ │
│ (/api/* in │ │
│ apps/web) │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ Integrated AI Runtime (apps/web API) │
│ /api/chat and layers │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Modules │ │
│ │ ┌─────────┐ ┌──────────┐ ┌───────────┐ ┌───────────┐ │ │
│ │ │ Chat │ │ Sessions │ │Completions│ │ Knowledge │ │ │
│ │ └────┬────┘ └────┬─────┘ └─────┬─────┘ └─────┬─────┘ │ │
│ └───────┼───────────┼─────────────┼─────────────┼────────┘ │
│ │ │ │ │ │
│ ┌───────┴───────────┴─────────────┴─────────────┴───────┐ │
│ │ AI Providers (OpenAI, Anthropic) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┴───────────────────────────┐ │
│ │ Upstash Vector (Knowledge Store) │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┴───────────────────────────┐ │
│ │ Tasks Dispatcher → Agent │ │
│ └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────┬───────────────────────────────┘
│
│ HTTP (internal)
▼
┌─────────────────────────────────────────────────────────────────┐
│ Agent Service (agent.codmir.com) │
│ Port 8080 │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Task Handlers │ │
│ │ ┌──────────────────┐ ┌────────────────────────────┐ │ │
│ │ │ analyze-project │ │ generate-knowledge-base │ │ │
│ │ └────────┬─────────┘ └──────────────┬─────────────┘ │ │
│ └───────────┼───────────────────────────┼─────────────────┘ │
│ │ │ │
│ ┌───────────┴───────────────────────────┴───────────────┐ │
│ │ Analysis Service │ │
│ │ • Clone/pull repos │ │
│ │ • Detect tech stack │ │
│ │ • Analyze architecture │ │
│ │ • Extract components │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────┴───────────────────────────────────────────┐ │
│ │ Knowledge Generator Service │ │
│ │ • Generate chunks │ │
│ │ • Send to AI service for embedding │ │
│ │ • Callback on completion │ │
│ └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘Services
Integrated AI API
apps/web /api/* - primary runtime path for AI interactions
- Handles chat and completion requests
- Manages conversation sessions
- Stores and queries knowledge vectors
- Dispatches tasks to Agent service
- Supports long-running streams (15+ min)
Agent Service
agent.codmir.com:8080 - NestJS service for code operations
- Clones and analyzes repositories
- Detects tech stack and architecture
- Generates knowledge chunks
- Manages ephemeral runner containers
- Executes code tasks
Upstash Vector
Serverless vector database for knowledge storage
- Stores embeddings per project
- Semantic similarity search
- Metadata filtering
- Auto-scaling and managed infrastructure
Data Flows
Chat with Project Context
- User sends message to AI service with projectId
- AI service queries Upstash Vector for relevant knowledge
- Retrieved chunks are injected into system prompt
- Request sent to AI provider (OpenAI/Anthropic)
- Response streamed back to client
Knowledge Base Generation
- Client dispatches task via AI service
- AI service forwards to Agent service
- Agent clones repo and analyzes codebase
- Generates knowledge chunks (code, docs, architecture)
- Sends chunks to AI service for embedding
- AI service generates embeddings and stores in Upstash Vector
- Callback sent to AI service with results
Environment Variables
Web App
# Canonical runtime path is internal /api/* FEATURE_REMOTE_AI_DISPATCH=false NEXT_PUBLIC_AI_SERVICE_URL=
AI Service
GEMINI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... UPSTASH_VECTOR_REST_URL=https://... UPSTASH_VECTOR_REST_TOKEN=... AGENT_SERVICE_URL=http://localhost:8080
Agent Service
# Optional legacy override only AI_SERVICE_URL= WORK_DIR=/tmp/codmir-analysis GITHUB_TOKEN=ghp_...