Architecture

import { Aside } from ‘@astrojs/starlight/components’;

Kodel.AI is a client-server monorepo with schema-per-tenant PostgreSQL isolation. This page covers the system components, key data flows, and the multitenancy model.

System overview

Monorepo packages

Component descriptions

Server (packages/server)

The NestJS backend is the central hub — it owns all business logic, data, and LLM access.

Responsibility	Details
REST API	JWT auth, all CRUD endpoints, SSE streaming
WebSocket hub	Manages connected agent instances
LLM proxy	Streams requests to LLM providers, logs to ClickHouse
Task engine	Workflow transitions, automation rules, AI job scheduling
Multitenancy	Schema-per-tenant isolation via SET LOCAL search_path

Web UI (packages/web)

React 19 SPA with TanStack Router. No full-page reloads — all navigation is client-side.

Feature	Technology
Routing	TanStack Router (file-based)
Styling	Tailwind CSS
State	TanStack Query (server state) + Zustand (UI state)
Real-time	SSE via EventSource

Agent (packages/agent)

A stateless worker that connects to the server over WebSocket and executes one task at a time.

Tool	What it does
read_file	Read file contents from /workspace
write_file	Create or overwrite a file
edit_file	Targeted search/replace edits
bash	Run shell commands (tests, git, npm…)
glob	Find files by pattern
grep	Search file contents with regex

The agent never calls the LLM directly. It sends `llm.request` over WebSocket, the server proxies the call and streams chunks back. This keeps the LLM API key out of the agent container.

Key data flows

Task execution

Authentication & multitenancy

Multitenancy model

Each organization gets its own PostgreSQL schema (org_{slug}). All tenant data is fully isolated at the database level.

Migrations are applied in two layers:

• Shared (migrations/shared/) — runs once, affects public schema
• Tenant (migrations/tenant/) — runs for each org schema on server startup

Technology stack

Layer	Technology
Frontend	React 19, TypeScript, TanStack Router, Tailwind CSS
Backend	NestJS, TypeScript, Drizzle ORM
Database	PostgreSQL (schema-per-tenant)
Analytics	ClickHouse (AI job events, LLM call logs)
Auth	JWT (passport-jwt), optional OIDC/SSO
Agent runtime	Bun, Docker
LLM	OpenAI, Anthropic, OpenRouter, Ollama
Package manager	pnpm workspaces