# kodustech/kodus-ai architecture

> Architecture diagram of the GitHub repository kodustech/kodus-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kodustech/kodus-ai
- Repository: https://github.com/kodustech/kodus-ai

## Overview

1. **Repo shape: a multi-app monorepo**
   - This is not a single app; it is a platform made of several runtime processes and many shared libraries.
   - Main runnable apps are `apps/api`, `apps/web`, `apps/webhooks`, `apps/worker`, `apps/cli`, and `apps/analytics-cli`.
   - Shared business logic lives under `libs/*`, with EE/paid features isolated under `libs/ee/*`.

2. **Primary runtime boundaries**
   - `apps/api` is the main HTTP backend and orchestration surface.
   - `apps/web` is the Next.js frontend.
   - `apps/webhooks` is the inbound webhook receiver for Git providers.
   - `apps/worker` is the async job processor and cron runner.
   - `apps/cli` is a standalone command-line client that can authenticate, configure repos, install hooks, and run local reviews.

3. **Front-end to backend flow**
   - The web app does not talk directly to databases; it goes through `/app/api/proxy/*` routes and service hooks in `apps/web/src/lib/services/*`.
   - Those proxy routes forward requests to the API service and preserve auth/session context.
   - The UI is organized by product areas such as code review settings, pull requests, issues, cockpit analytics, integrations, subscription, and onboarding.

4. **Backend service composition**
   - The API app is built as a NestJS-style modular backend, with controllers, DTOs, cron jobs, and feature modules.
   - Controllers are grouped by domain: auth, organization, teams, permissions, integrations, pull requests, kody rules, issues, dry-run, webhook health, workflow queue, and CLI-specific endpoints.
   - The API is the main place where browser, CLI, and webhook traffic converge before delegating to domain libraries.

5. **Async workflow and job processing**
   - The platform uses RabbitMQ as the queue boundary for long-running or deferred work.
   - `libs/core/workflow` provides the generic workflow engine, outbox/inbox patterns, job state, queue service, and processor routing.
   - `apps/worker` drains those jobs, runs cron tasks, and enforces worker health/role behavior.
   - Several feature flows are explicitly async, especially code review execution, analytics ingestion, webhook handling, and periodic recap jobs.

6. **Code review is the central domain**
   - `libs/code-review` is the largest feature boundary and contains the review pipeline, agents, suggestion generation, file-level and PR-level analysis, sandboxing, and comment publishing.
   - The pipeline is stage-based: fetch PR files, validate prerequisites/config, resolve config, build sandbox/context, gather cross-file and documentation context, run LLM analysis, validate suggestions, and persist/post results.
   - It integrates with repositories, pull requests, AST graph building, context references, documentation search, and review feedback.

7. **Git provider integration layer**
   - `libs/platform` abstracts GitHub, GitLab, Bitbucket, Forgejo, and Azure Repos behind common code-management interfaces.
   - Provider-specific webhook handlers live in `libs/platform/infrastructure/webhooks/*`, while provider API adapters live in `libs/platform/infrastructure/adapters/services/*`.
   - `apps/webhooks` receives external events and hands them into the platform layer, which then enqueues downstream work.

8. **Identity, org, and access control**
   - `libs/identity` owns authentication, CLI auth, profiles, users, permissions, and invitation flows.
   - `libs/organization` owns organizations, teams, team members, parameters, CLI device/key concepts, and onboarding-related org state.
   - `libs/ee/sso`, `libs/ee/license`, and permission guards add enterprise auth and license gating.
   - This boundary matters because nearly every product surface is scoped by organization/team and policy checks.

9. **Configuration, rules, and review policy**
   - `libs/code-review`, `libs/kodyRules`, `libs/organization`, and `libs/integrations` together define how review behavior is configured.
   - Kody rules can be created, inherited, synced from IDEs, applied from libraries, and tied to feedback loops.
   - Centralized config support is a distinct subsystem: the CLI and web UI can read or sync repo settings and code review presets from a shared source of truth.

10. **AI and agent execution layer**
   - `libs/ai-engine`, `libs/agents`, and `packages/kodus-common` provide the LLM/tooling foundation.
   - There is a provider abstraction for model vendors, BYOK support, prompt building, tool execution, and context loading.
   - `libs/mcp-server` and `packages/kodus-flow` expose and run tool-oriented agent behavior; this is used for structured context retrieval, skill execution, and MCP-style tool access.
   - The code review pipeline and CLI memory/review flows rely on this agent/runtime layer.

11. **Data stores and persistence**
   - The repo uses both PostgreSQL and MongoDB, with TypeORM migrations for relational data and Mongoose models for document-style collections.
   - PostgreSQL appears to hold core transactional entities, workflow state, analytics schemas, and subscription/org data.
   - MongoDB is used heavily by review, pipeline, context, memory, and execution-history style models.
   - There is also a dedicated analytics warehouse in `libs/ee/analytics-warehouse` with its own schema and ingestion/backfill logic.

12. **Analytics and product telemetry**
   - `libs/analytics`, `libs/cockpit`, and `libs/ee/analytics-warehouse` form the metrics side of the product.
   - `apps/web` exposes cockpit, token usage, user logs, and PR analytics pages that read from these services.
   - This subsystem is distinct from review execution: it consumes execution/activity data and renders operational/productivity views, rather than generating review output.

13. **CLI and local developer workflow**
   - `apps/cli` is a first-class product surface, not just a thin wrapper.
   - It manages login, device/team keys, repo config, hook installation, memory capture, review commands, skill syncing, and agent-specific behavior for Claude/Codex/Cursor.
   - The CLI talks to the API, interacts with the local git repository, and can run review flows offline or in CI/CD.

14. **Operational and integration concerns**
   - The repo is heavily containerized and deployment-aware: Dockerfiles, Compose files, GitHub Actions workflows, and self-hosted/prod/QA build pipelines are part of the architecture.
   - Health, observability, logging, metrics, Sentry/BetterStack, PostHog, email, and rate limiting are baked into the shared core libraries.
   - These cross-cutting concerns matter because the platform is designed to run as multiple cooperating services with clear operational boundaries.

Main entry points: [`apps/api/src/main.ts`](https://github.com/kodustech/kodus-ai/blob/main/apps/api/src/main.ts) (API), [`libs/code-review/pipeline/code-review-pipeline.module.ts`](https://github.com/kodustech/kodus-ai/blob/main/libs/code-review/pipeline/code-review-pipeline.module.ts) (Code review), [`apps/cli/src/cli.ts`](https://github.com/kodustech/kodus-ai/blob/main/apps/cli/src/cli.ts) (CLI), [`apps/worker/src/main.ts`](https://github.com/kodustech/kodus-ai/blob/main/apps/worker/src/main.ts) (Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Apps"]
  node_apps_api["API<br/>Nest backend<br/>[main.ts]"]
  node_apps_web["Web<br/>Next.js UI<br/>[layout.tsx]"]
  node_apps_webhooks["Webhooks<br/>Webhook ingress<br/>[main.ts]"]
  node_apps_worker["Worker<br/>[main.ts]"]
  node_apps_cli["CLI<br/>[cli.ts]"]
  node_apps_analytics_cli["Analytics CLI<br/>Ops CLI<br/>[main.ts]"]
end

subgraph group_libs["Libraries"]
  node_libs_core_workflow{{"Workflow core<br/>Queue engine<br/>[workflow.module.ts]"}}
  node_libs_code_review{{"Code review<br/>Review pipeline"}}
  node_libs_platform{{"Platform<br/>Git provider layer<br/>[platform.module.ts]"}}
  node_libs_identity{{"Identity<br/>Auth & access<br/>[user.module.ts]"}}
  node_libs_organization{{"Organization<br/>Org model"}}
  node_libs_integrations{{"Integrations<br/>Config model"}}
  node_libs_kody_rules{{"Kody rules<br/>Policy engine"}}
  node_libs_cockpit{{"Cockpit<br/>Analytics domain<br/>[cockpit.module.ts]"}}
  node_libs_cli_review{{"CLI review"}}
  node_libs_ai_engine{{"AI engine<br/>LLM orchestration"}}
  node_libs_analytics{{"Analytics<br/>Usage metrics"}}
  node_libs_platform_data{{"Platform data<br/>PR persistence"}}
  node_libs_dry_run{{"Dry run<br/>Preview engine<br/>[dry-run.module.ts]"}}
  node_libs_ee{{"EE features<br/>Paid modules<br/>[license.module.ts]"}}
end

subgraph group_packages["Packages"]
  node_packages_common["kodus-common<br/>LLM SDK<br/>[index.ts]"]
  node_packages_flow["kodus-flow<br/>Agent runtime<br/>[index.ts]"]
end

subgraph group_infra["Infra"]
end

node_apps_web -->|"proxy API"| node_apps_api
node_apps_cli -->|"auth/config/review"| node_apps_api
node_apps_webhooks -->|"provider events"| node_libs_platform
node_apps_webhooks -->|"enqueue jobs"| node_libs_core_workflow
node_apps_api -->|"auth & access"| node_libs_identity
node_apps_api -->|"org scope"| node_libs_organization
node_apps_api -->|"integration config"| node_libs_integrations
node_apps_api -->|"rules policy"| node_libs_kody_rules
node_apps_api -->|"review orchestration"| node_libs_code_review
node_apps_api -->|"CLI reviews"| node_libs_cli_review
node_apps_api -->|"metrics"| node_libs_cockpit
node_apps_api -->|"preview review"| node_libs_dry_run
node_apps_api -->|"repo data"| node_libs_platform_data
node_apps_api -.->|"enterprise gates"| node_libs_ee
node_apps_worker -->|"drain queue"| node_libs_core_workflow
node_apps_worker -->|"async review"| node_libs_code_review
node_apps_worker -->|"ingest metrics"| node_libs_analytics
node_apps_worker -->|"recaps"| node_libs_cockpit
node_apps_cli -->|"device auth"| node_libs_identity
node_apps_cli -->|"repo setup"| node_libs_organization
node_apps_cli -->|"rule sync"| node_libs_kody_rules
node_apps_cli -->|"local agents"| node_libs_ai_engine
node_libs_code_review -->|"git ops"| node_libs_platform
node_libs_code_review -->|"LLM context"| node_libs_ai_engine
node_libs_code_review -->|"model calls"| node_packages_common
node_libs_cli_review -->|"agent runtime"| node_packages_flow
node_libs_code_review -->|"tools/runtime"| node_packages_flow
node_libs_platform -->|"webhook queue"| node_libs_core_workflow
node_libs_cockpit -->|"usage data"| node_libs_analytics
node_libs_ee -.->|"warehouse"| node_libs_cockpit
node_libs_ee -.->|"fine tuning"| node_libs_code_review
node_libs_organization -->|"policy"| node_libs_identity
node_libs_integrations -->|"provider config"| node_libs_platform
node_libs_core_workflow -->|"persist jobs"| node_libs_platform_data

click node_apps_api "https://github.com/kodustech/kodus-ai/blob/main/apps/api/src/main.ts"
click node_apps_web "https://github.com/kodustech/kodus-ai/blob/main/apps/web/src/app/layout.tsx"
click node_apps_webhooks "https://github.com/kodustech/kodus-ai/blob/main/apps/webhooks/src/main.ts"
click node_apps_worker "https://github.com/kodustech/kodus-ai/blob/main/apps/worker/src/main.ts"
click node_apps_cli "https://github.com/kodustech/kodus-ai/blob/main/apps/cli/src/cli.ts"
click node_apps_analytics_cli "https://github.com/kodustech/kodus-ai/blob/main/apps/analytics-cli/src/main.ts"
click node_libs_core_workflow "https://github.com/kodustech/kodus-ai/blob/main/libs/core/workflow/modules/workflow.module.ts"
click node_libs_code_review "https://github.com/kodustech/kodus-ai/blob/main/libs/code-review/pipeline/code-review-pipeline.module.ts"
click node_libs_platform "https://github.com/kodustech/kodus-ai/blob/main/libs/platform/modules/platform.module.ts"
click node_libs_identity "https://github.com/kodustech/kodus-ai/blob/main/libs/identity/modules/user.module.ts"
click node_libs_organization "https://github.com/kodustech/kodus-ai/blob/main/libs/organization/modules/organization.module.ts"
click node_libs_integrations "https://github.com/kodustech/kodus-ai/blob/main/libs/integrations/modules/integrations.module.ts"
click node_libs_kody_rules "https://github.com/kodustech/kodus-ai/blob/main/libs/kodyRules/modules/kodyRules.module.ts"
click node_libs_cockpit "https://github.com/kodustech/kodus-ai/blob/main/libs/cockpit/modules/cockpit.module.ts"
click node_libs_cli_review "https://github.com/kodustech/kodus-ai/blob/main/libs/cli-review/cli-review.module.ts"
click node_libs_ai_engine "https://github.com/kodustech/kodus-ai/blob/main/libs/ai-engine/modules/ai-engine.module.ts"
click node_libs_analytics "https://github.com/kodustech/kodus-ai/blob/main/libs/analytics/modules/analytics.module.ts"
click node_libs_platform_data "https://github.com/kodustech/kodus-ai/blob/main/libs/platformData/platformData.module.ts"
click node_libs_dry_run "https://github.com/kodustech/kodus-ai/blob/main/libs/dryRun/dry-run.module.ts"
click node_libs_ee "https://github.com/kodustech/kodus-ai/blob/main/libs/ee/license/license.module.ts"
click node_packages_common "https://github.com/kodustech/kodus-ai/blob/main/packages/kodus-common/src/index.ts"
click node_packages_flow "https://github.com/kodustech/kodus-ai/blob/main/packages/kodus-flow/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_apps_api,node_apps_web,node_apps_webhooks,node_apps_worker,node_apps_cli,node_apps_analytics_cli toneBlue
class node_libs_core_workflow,node_libs_code_review,node_libs_platform,node_libs_identity,node_libs_organization,node_libs_integrations,node_libs_kody_rules,node_libs_cockpit,node_libs_cli_review,node_libs_ai_engine,node_libs_analytics,node_libs_platform_data,node_libs_dry_run,node_libs_ee toneAmber
class node_packages_common,node_packages_flow toneMint
```

## Components

### Apps

Runnable services and user-facing runtimes

- [API](https://github.com/kodustech/kodus-ai/blob/main/apps/api/src/main.ts): Nest backend · Main HTTP orchestration surface for browser, CLI, and webhook traffic. · `apps/api/src/main.ts`
- [Web](https://github.com/kodustech/kodus-ai/blob/main/apps/web/src/app/layout.tsx): Next.js UI · Frontend that reaches the API through proxy routes and service hooks. · `apps/web/src/app/layout.tsx`
- [Webhooks](https://github.com/kodustech/kodus-ai/blob/main/apps/webhooks/src/main.ts): Webhook ingress · Receives provider webhooks and forwards them into platform handlers and queues. · `apps/webhooks/src/main.ts`
- [Worker](https://github.com/kodustech/kodus-ai/blob/main/apps/worker/src/main.ts): Async worker · Drains queued jobs and runs cron-driven background work. · `apps/worker/src/main.ts`
- [CLI](https://github.com/kodustech/kodus-ai/blob/main/apps/cli/src/cli.ts): Command client · Standalone CLI for auth, repo config, hook installation, and local review flows. · `apps/cli/src/cli.ts`
- [Analytics CLI](https://github.com/kodustech/kodus-ai/blob/main/apps/analytics-cli/src/main.ts): Ops CLI · Dedicated analytics and backfill command runner. · `apps/analytics-cli/src/main.ts`

### Libraries

Shared domain, workflow, and infrastructure modules

- [Workflow core](https://github.com/kodustech/kodus-ai/blob/main/libs/core/workflow/modules/workflow.module.ts): Queue engine · Generic outbox/inbox, job state, queue service, and processor routing. · `libs/core/workflow/modules/workflow.module.ts`
- [Code review](https://github.com/kodustech/kodus-ai/blob/main/libs/code-review/pipeline/code-review-pipeline.module.ts): Review pipeline · Central review engine with stages, agents, sandboxing, comments, and validation. · `libs/code-review/pipeline/code-review-pipeline.module.ts`
- [Platform](https://github.com/kodustech/kodus-ai/blob/main/libs/platform/modules/platform.module.ts): Git provider layer · Common integration layer for GitHub, GitLab, Bitbucket, Forgejo, and Azure Repos. · `libs/platform/modules/platform.module.ts`
- [Identity](https://github.com/kodustech/kodus-ai/blob/main/libs/identity/modules/user.module.ts): Auth & access · Authentication, CLI auth, profiles, permissions, and invitations. · `libs/identity/modules/user.module.ts`
- [Organization](https://github.com/kodustech/kodus-ai/blob/main/libs/organization/modules/organization.module.ts): Org model · Organizations, teams, membership, CLI keys, and onboarding state. · `libs/organization/modules/organization.module.ts`
- [Integrations](https://github.com/kodustech/kodus-ai/blob/main/libs/integrations/modules/integrations.module.ts): Config model · Integration records and configuration for code-management providers. · `libs/integrations/modules/integrations.module.ts`
- [Kody rules](https://github.com/kodustech/kodus-ai/blob/main/libs/kodyRules/modules/kodyRules.module.ts): Policy engine · Rule lifecycle, sync, inheritance, recommendation, and feedback loops. · `libs/kodyRules/modules/kodyRules.module.ts`
- [Cockpit](https://github.com/kodustech/kodus-ai/blob/main/libs/cockpit/modules/cockpit.module.ts): Analytics domain · Product and productivity metrics surfaced to the UI. · `libs/cockpit/modules/cockpit.module.ts`
- [CLI review](https://github.com/kodustech/kodus-ai/blob/main/libs/cli-review/cli-review.module.ts): CLI review domain · Session capture, classification, review execution, and dashboarding for CLI flows. · `libs/cli-review/cli-review.module.ts`
- [AI engine](https://github.com/kodustech/kodus-ai/blob/main/libs/ai-engine/modules/ai-engine.module.ts): LLM orchestration · Prompt/context loading, prompt execution, and context-reference handling. · `libs/ai-engine/modules/ai-engine.module.ts`
- [Analytics](https://github.com/kodustech/kodus-ai/blob/main/libs/analytics/modules/analytics.module.ts): Usage metrics · Token usage and interaction analytics services. · `libs/analytics/modules/analytics.module.ts`
- [Platform data](https://github.com/kodustech/kodus-ai/blob/main/libs/platformData/platformData.module.ts): PR persistence · Stored pull-request and repository data used by review and analytics. · `libs/platformData/platformData.module.ts`
- [Dry run](https://github.com/kodustech/kodus-ai/blob/main/libs/dryRun/dry-run.module.ts): Preview engine · Executes code-review-like previews and exposes status/result retrieval. · `libs/dryRun/dry-run.module.ts`
- [EE features](https://github.com/kodustech/kodus-ai/blob/main/libs/ee/license/license.module.ts): Paid modules · Enterprise-only auth, licensing, analytics warehouse, and extra policy layers. · `libs/ee/license/license.module.ts`

### Packages

Reusable runtime and SDK packages

- [kodus-common](https://github.com/kodustech/kodus-ai/blob/main/packages/kodus-common/src/index.ts): LLM SDK · Shared LLM builder/provider abstractions and common utility helpers. · `packages/kodus-common/src/index.ts`
- [kodus-flow](https://github.com/kodustech/kodus-ai/blob/main/packages/kodus-flow/src/index.ts): Agent runtime · Agent runtime, context system, MCP support, memory, storage, and observability. · `packages/kodus-flow/src/index.ts`

## Connections

- Web → API: proxy API · Browser requests go through proxy routes and service hooks to the API.
- CLI → API: auth/config/review · CLI uses API endpoints for login, repo config, rules, and review operations.
- Webhooks → Platform: provider events · Inbound webhook controllers hand events into the platform abstraction layer.
- Webhooks → Workflow core: enqueue jobs · Webhook handling pushes deferred work into workflow queues.
- API → Identity: auth & access · API controllers and guards rely on identity for login, permissions, and invitations.
- API → Organization: org scope · API uses organization, team, and CLI-key state for tenant-scoped operations.
- API → Integrations: integration config · API manages provider connections and integration configuration.
- API → Kody rules: rules policy · API exposes rule management, syncing, and recommendation flows.
- API → Code review: review orchestration · API delegates review execution and related configuration to the review domain.
- API → CLI review: CLI reviews · API exposes CLI-specific review and session endpoints.
- API → Cockpit: metrics · API serves cockpit and usage/analytics views.
- API → Dry run: preview review · API exposes dry-run execution and status retrieval.
- API → Platform data: repo data · API reads and updates persistent pull-request and repository data.
- API → EE features: enterprise gates · API applies EE auth, license, and feature gating where available.
- Worker → Workflow core: drain queue · Worker processes queued workflow jobs and deferred tasks.
- Worker → Code review: async review · Worker runs review jobs, cron tasks, and related background processing.
- Worker → Analytics: ingest metrics · Worker runs analytics ingestion and classifier cron jobs.
- Worker → Cockpit: recaps · Worker supports periodic recap and cockpit-related background jobs.
- CLI → Identity: device auth · CLI authenticates via device/login/session flows.
- CLI → Organization: repo setup · CLI reads team keys, repo settings, and onboarding state.
- CLI → Kody rules: rule sync · CLI manages Kody rules, presets, and centralized config sync.
- CLI → AI engine: local agents · CLI review and memory flows use the shared AI/runtime layer.
- Code review → Platform: git ops · Review pipeline fetches PRs, files, comments, and provider metadata through platform adapters.
- Code review → AI engine: LLM context · Review pipeline uses prompt/context loading and external reference handling.
- Code review → kodus-common: model calls · Review and agent layers depend on shared LLM builders and provider adapters.
- CLI review → kodus-flow: agent runtime · CLI session capture and review execution rely on the flow runtime.
- Code review → kodus-flow: tools/runtime · Structured agent execution and MCP-style tool behavior use the flow runtime.
- Platform → Workflow core: webhook queue · Platform webhook flows enqueue downstream background work.
- Cockpit → Analytics: usage data · Cockpit metrics are built from analytics and interaction data.
- EE features → Cockpit: warehouse · EE analytics warehouse extends product telemetry and reporting.
- EE features → Code review: fine tuning · Enterprise code-review stages and fine-tuning augment the core review flow.
- Organization → Identity: policy · Organization state drives permissions, membership, and onboarding decisions.
- Integrations → Platform: provider config · Integration records configure provider adapters and code-management access.
- Workflow core → Platform data: persist jobs · Workflow state and job history are stored alongside platform data.
