thisara404/kapruka-server

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.