# thisara404/kapruka-server architecture

> Architecture diagram of the GitHub repository thisara404/kapruka-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thisara404/kapruka-server
- Repository: https://github.com/thisara404/kapruka-server

## Overview

1. This repository is a NestJS backend application. The top-level architecture is organized by feature modules under `src/`, with a shared database layer and a small amount of infrastructure for Docker and CI/CD. The runtime is Node.js/TypeScript, with Nest controllers, services, guards, and gateways forming the primary application boundary.

2. The main request entry points are split by transport:
   - HTTP controllers for `auth`, `chat`, `deactivation`, and likely `analytics`.
   - A WebSocket-style gateway for `voice`.
   - The root `AppController`/`AppService` are the default Nest bootstrap surface, but most behavior lives in the feature modules.

3. Authentication is a dedicated subsystem in `src/auth`. It uses a JWT strategy plus a JWT auth guard, which means protected routes are enforced at the controller boundary rather than inside business logic. There is also an `optional-jwt-auth.guard` in chat, indicating that some chat flows can operate anonymously or with degraded identity context.

4. The chat subsystem is the most complex application area. `ChatController` and `ChatService` sit behind a rate limiter and coordinate with:
   - `mcp-client.ts` and `list-mcp-tools.ts` for tool integration,
   - `model-provider.ts` for LLM/provider abstraction,
   - `system-prompt.ts` for prompt assembly,
   - `lankaguard_backend_configuration_parser.py` for parsing backend configuration.
   This suggests the chat flow is not just message storage; it orchestrates model calls, tool invocation, and runtime policy controls.

5. The voice subsystem is separate from chat and is built around `VoiceGateway`, which strongly indicates real-time, event-driven interaction over a persistent connection. The presence of `gemini-live.types.ts` and voice constants/types points to an integration with a live speech/model API, likely with streaming input/output and session state managed at the gateway layer.

6. Persistence is centralized in `src/database`. It uses TypeORM-style entity modeling and a `TypeormConfigService`, so the backend’s domain state is stored relationally. The entities show the core business objects:
   - users and deactivated users,
   - agent sessions and agent turns,
   - analytics records,
   - delivery checks,
   - orders and products views,
   - step traces.
   This implies a mix of operational, conversational, and analytics/event data in the same database boundary.

7. The database model also reveals the application’s domain shape. `agent-session`, `agent-turn`, and `step-trace` suggest an execution history for AI-driven workflows. `order`, `product-view`, and `delivery-check` indicate either commerce-related telemetry or an internal workflow that tracks downstream business events. `session-status.enum.ts` and `step-type.enum.ts` further show that session lifecycle and workflow steps are formalized in the data model.

8. `analytics` is a distinct feature module with its own service and entity. It likely consumes persisted events and turns them into higher-level reporting or metrics, rather than acting as a request-time dependency for the core chat flow. This separation suggests read-optimized aggregation layered over transactional records.

9. `deactivation` is another independent subsystem with a controller, service, and scheduler. That combination indicates both manual and automated deactivation flows, probably acting on users or sessions and using the database for state tracking. The scheduler means some cleanup or policy enforcement happens asynchronously rather than only on user-initiated requests.

10. `users` is intentionally lightweight, with a service and module but no controller in the tree. That usually means user lookup/profile logic is shared by other modules rather than exposed directly as a public API. It likely serves auth, chat, and deactivation logic as a common domain service.

11. Cross-cutting concerns are handled in the usual Nest way:
   - guards for auth and optional auth,
   - services for business logic,
   - modules for dependency boundaries,
   - gateways for real-time messaging,
   - scheduler for background work.
   This keeps transport concerns separate from domain/persistence concerns, which is important when diagramming the system.

12. Operationally, the repo is containerized and deployment-ready. `Dockerfile`, `docker-compose.yml`, and `.github/workflows/deploy-backend.yml` show a packaged backend service with CI/CD automation. The `README` is the standard Nest starter, but the file tree makes clear this is a production backend with database-backed state, auth, AI integration, and a real-time voice channel.

13. For an architecture diagram, the key flows to show are:
   - client request -> HTTP controller/gateway -> feature service -> database and/or external model/tool services,
   - authenticated routes passing through JWT guards,
   - chat invoking model/provider + MCP tools,
   - voice using a persistent gateway connection to a live model API,
   - scheduler-triggered deactivation jobs updating persisted state.
   The central boundary is the Nest backend, with TypeORM/Postgres-style persistence underneath and AI/tooling integrations outside the process boundary.

Main entry points: [`src/app.module.ts`](https://github.com/thisara404/kapruka-server/blob/main/src/app.module.ts) (App Module), [`src/database/database.module.ts`](https://github.com/thisara404/kapruka-server/blob/main/src/database/database.module.ts) (Database), [`src/auth`](https://github.com/thisara404/kapruka-server/tree/main/src/auth) (Auth), [`src/chat`](https://github.com/thisara404/kapruka-server/tree/main/src/chat) (Chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["Nest Backend"]
  node_node_main(("Bootstrap<br/>Nest entrypoint<br/>[main.ts]"))
  node_node_app_module["App Module<br/>root module<br/>[app.module.ts]"]
  node_node_app_controller["Root API<br/>default controller<br/>[app.controller.ts]"]
  node_node_app_service["Root Service<br/>default service<br/>[app.service.ts]"]
  node_node_auth["Auth"]
  node_node_auth_controller["Auth API<br/>HTTP controller<br/>[auth.controller.ts]"]
  node_node_jwt_guard["JWT Guard<br/>auth guard<br/>[jwt-auth.guard.ts]"]
  node_node_jwt_strategy["JWT Strategy<br/>passport strategy<br/>[jwt.strategy.ts]"]
  node_node_chat["Chat<br/>LLM orchestration"]
  node_node_chat_controller["Chat API<br/>HTTP controller<br/>[chat.controller.ts]"]
  node_node_chat_service["Chat Service<br/>orchestrator<br/>[chat.service.ts]"]
  node_node_optional_guard["Optional Auth"]
  node_node_tools["Tooling<br/>mcp integration<br/>[mcp-client.ts]"]
  node_node_model["Model Provider<br/>llm adapter<br/>[model-provider.ts]"]
  node_node_voice["Voice<br/>realtime gateway"]
  node_node_voice_gateway["Voice Gateway<br/>ws gateway<br/>[voice.gateway.ts]"]
  node_node_deactivation["Deactivation<br/>lifecycle module"]
  node_node_deact_scheduler["Scheduler<br/>background job"]
  node_node_analytics["Analytics<br/>metrics module"]
  node_node_users["Users<br/>shared domain service"]
end

subgraph group_group_db["Database Layer"]
  node_node_db_module[("Database<br/>typeorm module<br/>[database.module.ts]")]
  node_node_db_config["TypeORM Config<br/>db config service"]
  node_node_db_entities[("Entities<br/>domain models")]
  node_node_db_enums["Enums"]
end

subgraph group_group_runtime["Ops & Delivery"]
  node_node_docker["Container<br/>dockerfile"]
  node_node_compose["Compose<br/>service orchestration<br/>[docker-compose.yml]"]
  node_node_ci["Deploy Workflow<br/>ci/cd pipeline<br/>[deploy-backend.yml]"]
end

node_node_main -->|"boots"| node_node_app_module
node_node_app_module -->|"exposes"| node_node_app_controller
node_node_app_module -->|"provides"| node_node_app_service
node_node_app_module -->|"imports"| node_node_auth
node_node_app_module -->|"imports"| node_node_chat
node_node_app_module -->|"imports"| node_node_voice
node_node_app_module -->|"imports"| node_node_deactivation
node_node_app_module -->|"imports"| node_node_analytics
node_node_app_module -->|"imports"| node_node_users
node_node_app_module -->|"imports"| node_node_db_module
node_node_auth -->|"contains"| node_node_auth_controller
node_node_auth -->|"uses"| node_node_jwt_guard
node_node_auth -->|"uses"| node_node_jwt_strategy
node_node_chat -->|"contains"| node_node_chat_controller
node_node_chat -->|"contains"| node_node_chat_service
node_node_chat -->|"uses"| node_node_optional_guard
node_node_chat_service -->|"uses"| node_node_tools
node_node_chat_service -->|"uses"| node_node_model
node_node_chat_service -->|"persists via"| node_node_db_module
node_node_voice -->|"contains"| node_node_voice_gateway
node_node_voice_gateway -->|"persists via"| node_node_db_module
node_node_deactivation -->|"contains"| node_node_deact_scheduler
node_node_deactivation -->|"persists via"| node_node_db_module
node_node_analytics -->|"reads from"| node_node_db_module
node_node_users -->|"reads from"| node_node_db_module
node_node_db_module -->|"configured by"| node_node_db_config
node_node_db_module -->|"registers"| node_node_db_entities
node_node_db_module -->|"relies on"| node_node_db_enums
node_node_docker -->|"packages"| node_node_app_module
node_node_compose -->|"orchestrates"| node_node_docker
node_node_ci -->|"deploys"| node_node_docker

click node_node_main "https://github.com/thisara404/kapruka-server/blob/main/src/main.ts"
click node_node_app_module "https://github.com/thisara404/kapruka-server/blob/main/src/app.module.ts"
click node_node_app_controller "https://github.com/thisara404/kapruka-server/blob/main/src/app.controller.ts"
click node_node_app_service "https://github.com/thisara404/kapruka-server/blob/main/src/app.service.ts"
click node_node_auth "https://github.com/thisara404/kapruka-server/tree/main/src/auth"
click node_node_auth_controller "https://github.com/thisara404/kapruka-server/blob/main/src/auth/auth.controller.ts"
click node_node_jwt_guard "https://github.com/thisara404/kapruka-server/blob/main/src/auth/guards/jwt-auth.guard.ts"
click node_node_jwt_strategy "https://github.com/thisara404/kapruka-server/blob/main/src/auth/jwt.strategy.ts"
click node_node_chat "https://github.com/thisara404/kapruka-server/tree/main/src/chat"
click node_node_chat_controller "https://github.com/thisara404/kapruka-server/blob/main/src/chat/chat.controller.ts"
click node_node_chat_service "https://github.com/thisara404/kapruka-server/blob/main/src/chat/chat.service.ts"
click node_node_optional_guard "https://github.com/thisara404/kapruka-server/blob/main/src/chat/guards/optional-jwt-auth.guard.ts"
click node_node_tools "https://github.com/thisara404/kapruka-server/blob/main/src/chat/mcp-client.ts"
click node_node_model "https://github.com/thisara404/kapruka-server/blob/main/src/chat/model-provider.ts"
click node_node_voice "https://github.com/thisara404/kapruka-server/tree/main/src/voice"
click node_node_voice_gateway "https://github.com/thisara404/kapruka-server/blob/main/src/voice/voice.gateway.ts"
click node_node_deactivation "https://github.com/thisara404/kapruka-server/tree/main/src/deactivation"
click node_node_deact_scheduler "https://github.com/thisara404/kapruka-server/blob/main/src/deactivation/deactivation.scheduler.ts"
click node_node_analytics "https://github.com/thisara404/kapruka-server/tree/main/src/analytics"
click node_node_users "https://github.com/thisara404/kapruka-server/tree/main/src/users"
click node_node_db_module "https://github.com/thisara404/kapruka-server/blob/main/src/database/database.module.ts"
click node_node_db_config "https://github.com/thisara404/kapruka-server/blob/main/src/database/typeorm-config.service.ts"
click node_node_db_entities "https://github.com/thisara404/kapruka-server/tree/main/src/database/entities"
click node_node_db_enums "https://github.com/thisara404/kapruka-server/tree/main/src/database/enums"
click node_node_docker "https://github.com/thisara404/kapruka-server/tree/main/Dockerfile"
click node_node_compose "https://github.com/thisara404/kapruka-server/blob/main/docker-compose.yml"
click node_node_ci "https://github.com/thisara404/kapruka-server/blob/main/.github/workflows/deploy-backend.yml"

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_node_main,node_node_app_module,node_node_app_controller,node_node_app_service,node_node_auth,node_node_auth_controller,node_node_jwt_guard,node_node_jwt_strategy,node_node_chat,node_node_chat_controller,node_node_chat_service,node_node_optional_guard,node_node_tools,node_node_model,node_node_voice,node_node_voice_gateway,node_node_deactivation,node_node_deact_scheduler,node_node_analytics,node_node_users toneBlue
class node_node_db_module,node_node_db_config,node_node_db_entities,node_node_db_enums toneAmber
class node_node_docker,node_node_compose,node_node_ci toneMint
```

## Components

### Nest Backend

Core application runtime and feature modules under src/

- [Bootstrap](https://github.com/thisara404/kapruka-server/blob/main/src/main.ts): Nest entrypoint · Application startup and module wiring · `src/main.ts`
- [App Module](https://github.com/thisara404/kapruka-server/blob/main/src/app.module.ts): root module · Top-level Nest composition root · `src/app.module.ts`
- [Root API](https://github.com/thisara404/kapruka-server/blob/main/src/app.controller.ts): default controller · Base HTTP surface for the app · `src/app.controller.ts`
- [Root Service](https://github.com/thisara404/kapruka-server/blob/main/src/app.service.ts): default service · Default app-level service layer · `src/app.service.ts`
- [Auth](https://github.com/thisara404/kapruka-server/tree/main/src/auth): jwt auth module · Login and request authentication · `src/auth`
- [Auth API](https://github.com/thisara404/kapruka-server/blob/main/src/auth/auth.controller.ts): HTTP controller · Authentication endpoints · `src/auth/auth.controller.ts`
- [JWT Guard](https://github.com/thisara404/kapruka-server/blob/main/src/auth/guards/jwt-auth.guard.ts): auth guard · Protects authenticated routes · `src/auth/guards/jwt-auth.guard.ts`
- [JWT Strategy](https://github.com/thisara404/kapruka-server/blob/main/src/auth/jwt.strategy.ts): passport strategy · Validates JWT identities · `src/auth/jwt.strategy.ts`
- [Chat](https://github.com/thisara404/kapruka-server/tree/main/src/chat): LLM orchestration · HTTP chat flow coordinating tools and model calls · `src/chat`
- [Chat API](https://github.com/thisara404/kapruka-server/blob/main/src/chat/chat.controller.ts): HTTP controller · Chat request boundary · `src/chat/chat.controller.ts`
- [Chat Service](https://github.com/thisara404/kapruka-server/blob/main/src/chat/chat.service.ts): orchestrator · Coordinates prompts, tools, provider calls, and limits · `src/chat/chat.service.ts`
- [Optional Auth](https://github.com/thisara404/kapruka-server/blob/main/src/chat/guards/optional-jwt-auth.guard.ts): optional auth guard · Allows chat flows with partial or anonymous identity · `src/chat/guards/optional-jwt-auth.guard.ts`
- [Tooling](https://github.com/thisara404/kapruka-server/blob/main/src/chat/mcp-client.ts): mcp integration · Tool discovery and backend configuration parsing · `src/chat/mcp-client.ts`
- [Model Provider](https://github.com/thisara404/kapruka-server/blob/main/src/chat/model-provider.ts): llm adapter · Abstracts model/provider execution · `src/chat/model-provider.ts`
- [Voice](https://github.com/thisara404/kapruka-server/tree/main/src/voice): realtime gateway · Persistent voice interaction channel · `src/voice`
- [Voice Gateway](https://github.com/thisara404/kapruka-server/blob/main/src/voice/voice.gateway.ts): ws gateway · Real-time session and event handling · `src/voice/voice.gateway.ts`
- [Deactivation](https://github.com/thisara404/kapruka-server/tree/main/src/deactivation): lifecycle module · Manual and scheduled deactivation flows · `src/deactivation`
- [Scheduler](https://github.com/thisara404/kapruka-server/blob/main/src/deactivation/deactivation.scheduler.ts): background job · Periodic deactivation enforcement · `src/deactivation/deactivation.scheduler.ts`
- [Analytics](https://github.com/thisara404/kapruka-server/tree/main/src/analytics): metrics module · Aggregates persisted activity into reporting · `src/analytics`
- [Users](https://github.com/thisara404/kapruka-server/tree/main/src/users): shared domain service · Lightweight user lookup and coordination · `src/users`

### Database Layer

TypeORM entities, enums, and config

- [Database](https://github.com/thisara404/kapruka-server/blob/main/src/database/database.module.ts): typeorm module · Database integration and entity registration · `src/database/database.module.ts`
- [TypeORM Config](https://github.com/thisara404/kapruka-server/blob/main/src/database/typeorm-config.service.ts): db config service · Configures the database connection · `src/database/typeorm-config.service.ts`
- [Entities](https://github.com/thisara404/kapruka-server/tree/main/src/database/entities): domain models · Persistent business objects and event records · `src/database/entities`
- [Enums](https://github.com/thisara404/kapruka-server/tree/main/src/database/enums): db enums · Shared session and step state definitions · `src/database/enums`

### Ops & Delivery

Containerization and CI/CD

- [Container](https://github.com/thisara404/kapruka-server/tree/main/Dockerfile): dockerfile · Backend runtime packaging · `Dockerfile`
- [Compose](https://github.com/thisara404/kapruka-server/blob/main/docker-compose.yml): service orchestration · Local multi-service container setup · `docker-compose.yml`
- [Deploy Workflow](https://github.com/thisara404/kapruka-server/blob/main/.github/workflows/deploy-backend.yml): ci/cd pipeline · Backend deployment automation · `.github/workflows/deploy-backend.yml`

## Connections

- Bootstrap → App Module: boots · Nest starts from the root module
- App Module → Root API: exposes · Registers default HTTP surface
- App Module → Root Service: provides · Wires the root service
- App Module → Auth: imports · Includes authentication subsystem
- App Module → Chat: imports · Includes chat subsystem
- App Module → Voice: imports · Includes realtime voice subsystem
- App Module → Deactivation: imports · Includes deactivation subsystem
- App Module → Analytics: imports · Includes analytics subsystem
- App Module → Users: imports · Includes shared user service
- App Module → Database: imports · Connects app to persistence layer
- Auth → Auth API: contains · HTTP auth endpoints
- Auth → JWT Guard: uses · Protects routes with JWT auth
- Auth → JWT Strategy: uses · Validates bearer tokens
- Chat → Chat API: contains · Chat request boundary
- Chat → Chat Service: contains · Chat orchestration logic
- Chat → Optional Auth: uses · Allows optional identity context
- Chat Service → Tooling: uses · Discovers and invokes external tools
- Chat Service → Model Provider: uses · Delegates model/provider calls
- Chat Service → Database: persists via · Stores conversational state and traces
- Voice → Voice Gateway: contains · Persistent realtime connection handler
- Voice Gateway → Database: persists via · Reads/writes session state
- Deactivation → Scheduler: contains · Background enforcement job
- Deactivation → Database: persists via · Updates deactivation state
- Analytics → Database: reads from · Aggregates stored events
- Users → Database: reads from · Shares user records across modules
- Database → TypeORM Config: configured by · Uses TypeORM connection settings
- Database → Entities: registers · Loads persistent entities
- Database → Enums: relies on · Uses shared state enums
- Container → App Module: packages · Builds the Nest backend runtime
- Compose → Container: orchestrates · Local containerized execution
- Deploy Workflow → Container: deploys · CI/CD pipeline publishes the backend image