Architecture
This page provides a high-level overview of Kaji's platform architecture. It's intended for technical stakeholders who want to understand how the system is structured.
System overview
Kaji is a multi-component platform deployed on the Shakudo Kubernetes infrastructure. At a high level:
- Users interact through KajiChat, a real-time web application
- KajiChat sends prompts to KajiCore, the AI agent runtime
- KajiCore executes tasks using tools, skills, and integrations
- Platform services provide routing, event processing, and persistence
Users
│
▼
KajiChat (Web UI) ←── Real-time chat, SSE, LLM proxy
│
▼
Kaji Event Bus ←── Routes triggers, manages KajiCore lifecycle
│
▼
KajiCore (Agent Runtime) ←── LLM loop, tools, memory, skills
│
├──→ LLM Router ←── Classifies prompts, selects model tier
├──→ AI Gateway ←── Routes to OpenAI, Anthropic, Gemini, etc.
├──→ MCP Servers ←── Tool integrations (ClickUp, Notion, etc.)
├──→ FalkorDB ←── Memory graph (entities, facts, episodes)
└──→ SeaweedFS ←── File storage and session persistence
Core components
KajiChat
The user-facing web application. Built with Rust (Actix-Web) and Dioxus (WASM frontend).
| Responsibility | Detail |
|---|---|
| Chat interface | Real-time messaging with SSE (Server-Sent Events) |
| LLM proxy | Streams responses from OpenAI, Anthropic, and Gemini |
| File attachments | Upload, share, and reference files in conversations |
| Labels and filters | Organize and find conversations |
| AutoKaji management | Create, pause, and monitor scheduled automations |
| Usage guide | Built-in guide showing prompt patterns and capabilities |
KajiCore
The AI agent runtime — the brain of the platform. Each active conversation maps to one KajiCore process (1:1).
| Responsibility | Detail |
|---|---|
| Agent loop | Multi-turn LLM conversation with tool dispatch |
| Tool execution | Run bash commands, read/write/edit files, search, ask questions |
| MCP integration | JSON-RPC transport to external tool servers |
| Skill injection | Discover and load specialized instruction sets |
| Memory | FalkorDB-backed knowledge graph with entities and relationships |
| Compaction | Summarizes long conversations to preserve context |
| Persistence | SQLite with Litestream WAL replication to SeaweedFS |
| Circuit breakers | Detects loops and consecutive errors gracefully |
Kaji Event Bus
Bridges user triggers into KajiCore lifecycle management via NATS JetStream.
| Responsibility | Detail |
|---|---|
| Trigger routing | Routes @kaji mentions and prompt triggers to the right KajiCore process |
| Process lifecycle | Spawns and manages KajiCore pods on demand |
| Event normalization | Maps raw events into structured chat events |
| NATS integration | Publishes to kaji.events.* and kaji.chat.* streams |
Kaji LLM Router
A stateless proxy that classifies prompt complexity and routes to the appropriate model tier.
| Responsibility | Detail |
|---|---|
| Prompt classification | 3-tier signal detection (low / medium / high complexity) |
| Model selection | Routes to the best-fit model via virtual model names |
| Fallback | Automatic retry through the AI Gateway's priority-based backend refs |
Supporting infrastructure
| Component | Purpose |
|---|---|
| NATS JetStream | Event bus for real-time message routing between components |
| PostgreSQL | KajiChat database — chats, messages, participants, attachments, sessions |
| FalkorDB | Graph database for KajiCore's memory system |
| SeaweedFS | Object storage for file attachments, session persistence, and learned skills |
| AI Gateway (Envoy) | LLM backend routing with priority-based fallback across providers |
| Keycloak | SSO authentication for KajiChat users |
Data flow example
Here's how a typical user prompt flows through the system:
- User types a message in KajiChat web UI
- KajiChat persists the message to PostgreSQL and publishes a trigger event to NATS
- Kaji Event Bus receives the trigger and ensures a KajiCore process is running for that chat
- KajiCore receives the prompt, sends it to the LLM Router → AI Gateway → model provider
- The model responds, KajiCore may execute tools (bash, file ops, MCP calls)
- KajiCore streams results back through NATS → KajiChat → user's browser via SSE
- Memory facts and session state are persisted to FalkorDB and SeaweedFS
Deployment
Kaji runs on Shakudo's Kubernetes platform as microservices:
| Service | Namespace | Port |
|---|---|---|
| KajiChat | hyperplane-kaji | 3000 |
| Kaji Event Bus | hyperplane-kaji | — (NATS consumer) |
| KajiCore pods | hyperplane-kaji | 9091 (health/metrics) |
| Kaji LLM Router | hyperplane-pipelines | — (proxy) |