How kodustech/kodus-ai works
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: src/main.ts API · code-review-pipeline.module.ts Code review · cli.ts CLI · src/main.ts Worker
Components 22
Apps
Runnable services and user-facing runtimes
- API · Main HTTP orchestration surface for browser, CLI, and webhook traffic.
apps/api/src/main.ts - Web · Frontend that reaches the API through proxy routes and service hooks.
apps/web/src/app/layout.tsx - Webhooks · Receives provider webhooks and forwards them into platform handlers and queues.
apps/webhooks/src/main.ts - Worker · Drains queued jobs and runs cron-driven background work.
apps/worker/src/main.ts - CLI · Standalone CLI for auth, repo config, hook installation, and local review flows.
apps/cli/src/cli.ts - Analytics CLI · Dedicated analytics and backfill command runner.
apps/analytics-cli/src/main.ts
Libraries
Shared domain, workflow, and infrastructure modules
- Workflow core · Generic outbox/inbox, job state, queue service, and processor routing.
libs/core/workflow/modules/workflow.module.ts - Code review · Central review engine with stages, agents, sandboxing, comments, and validation.
libs/code-review/pipeline/code-review-pipeline.module.ts - Platform · Common integration layer for GitHub, GitLab, Bitbucket, Forgejo, and Azure Repos.
libs/platform/modules/platform.module.ts - Identity · Authentication, CLI auth, profiles, permissions, and invitations.
libs/identity/modules/user.module.ts - Organization · Organizations, teams, membership, CLI keys, and onboarding state.
libs/organization/modules/organization.module.ts - Integrations · Integration records and configuration for code-management providers.
libs/integrations/modules/integrations.module.ts - Kody rules · Rule lifecycle, sync, inheritance, recommendation, and feedback loops.
libs/kodyRules/modules/kodyRules.module.ts - Cockpit · Product and productivity metrics surfaced to the UI.
libs/cockpit/modules/cockpit.module.ts - CLI review · Session capture, classification, review execution, and dashboarding for CLI flows.
libs/cli-review/cli-review.module.ts - AI engine · Prompt/context loading, prompt execution, and context-reference handling.
libs/ai-engine/modules/ai-engine.module.ts - Analytics · Token usage and interaction analytics services.
libs/analytics/modules/analytics.module.ts - Platform data · Stored pull-request and repository data used by review and analytics.
libs/platformData/platformData.module.ts - Dry run · Executes code-review-like previews and exposes status/result retrieval.
libs/dryRun/dry-run.module.ts - EE features · Enterprise-only auth, licensing, analytics warehouse, and extra policy layers.
libs/ee/license/license.module.ts
Packages
Reusable runtime and SDK packages
- kodus-common · Shared LLM builder/provider abstractions and common utility helpers.
packages/kodus-common/src/index.ts - kodus-flow · Agent runtime, context system, MCP support, memory, storage, and observability.
packages/kodus-flow/src/index.ts
Connections 34
- 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.