# vritti-ai-platforms/api-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/vritti-ai-platforms/api-sdk
- Repository: https://github.com/vritti-ai-platforms/api-sdk

## Overview

1. This repository is not a standalone application; it is a NestJS SDK package. Its purpose is to be imported into other services and provide shared infrastructure for multi-tenant routing, auth, logging, cache, and a few domain helpers. The public surface is consolidated through `src/index.ts` and feature `index.ts` files.

2. The architecture is organized around Nest modules. The main composition points are `AuthConfigModule`, `DatabaseModule`, `LoggerModule`, `CacheModule`, `RequestModule`, `EmailModule`, `DataTableModule`, and `RootModule`. Each module encapsulates a boundary that consumer apps can enable independently.

3. The central runtime concern is tenant-aware request processing. In gateway/HTTP mode, tenant identity is extracted from the request by interceptors, stored in `TenantContextService`, and then used to resolve database access. In microservice mode, tenant context is injected from message payloads instead of being looked up from the primary database.

4. Database access is split into two planes: a primary/platform database and per-tenant databases. `PrimaryDatabaseService` handles tenant registry lookups and platform-level data, while `TenantDatabaseService` returns the tenant-specific client. `PrimaryBaseRepository` and `TenantBaseRepository` provide reusable CRUD/query behavior on top of those services.

5. Tenant resolution is a first-class concern in the request pipeline. `TenantContextInterceptor` and `MessageTenantContextInterceptor` establish context; `@Tenant()` exposes it to controllers; `TenantContextService` holds it for the request lifecycle. This is the key data flow that ties HTTP/message input to downstream DB access and logging.

6. Authentication is handled as a global policy layer, not as per-controller boilerplate. `VrittiAuthGuard` enforces JWT/session rules, while decorators such as `@Public()`, `@Onboarding()`, `@Reset()`, `@SkipCsrf()`, and token/cookie decorators define route-level exceptions and token handling behavior. This makes auth a cross-cutting boundary around all endpoints.

7. Logging is its own subsystem with request correlation and tenant awareness. `LoggerModule`, `LoggerService`, `HttpLoggerInterceptor`, and `CorrelationIdMiddleware` combine to capture HTTP traffic, attach correlation IDs, and enrich logs with tenant/user context. The module supports a default Nest logger or Winston-style logging, which affects deployment/runtime behavior.

8. Caching is abstracted behind a provider interface. `CacheModule` and `CacheService` expose cache operations without binding consumers to a specific backend, while `RedisProvider` is the concrete implementation in the tree. This gives the SDK a pluggable cache boundary for connection pooling or ephemeral state.

9. The `data-table` area is a feature module with its own persistence and API layer. It contains schema definitions, repositories, services, controllers, DTOs, and docs for table views and saved table state. The split between `views` and `state` suggests one part manages named/shareable views and the other stores user-specific table UI state.

10. There is a small set of general-purpose application endpoints in `RootModule`, including `AppController` and `CsrfController`. These are likely health/bootstrap and CSRF-related endpoints that sit above the rest of the SDK’s infrastructure modules.

11. Error handling is standardized across the package. The `exceptions` folder provides HTTP-specific exception classes, and `HttpExceptionFilter` centralizes translation into a common error response shape. That makes failures consistent regardless of which module emitted them.

12. The SDK also includes thin utility and request-scoping helpers: `RequestModule`, `RequestService`, `phone.utils.ts`, `time.utils.ts`, and shared DTO/type definitions under `src/database/dto` and `src/types`. These support the main modules without introducing new runtime boundaries.

13. From a packaging perspective, the repo is built as a TypeScript library with `tsup`, checked with `tsc`, and linted/formatted with Biome. That matters architecturally because the output is a consumable SDK, not a deployed service, and the module boundaries are designed for import/export rather than internal app wiring.

14. The biggest external dependencies that shape the architecture are NestJS, Prisma client types, Fastify compatibility, JWT, Redis, and PostgreSQL. The SDK’s core value is coordinating those dependencies behind tenant-aware, request-scoped abstractions that consumer applications can adopt with minimal setup.

Main entry points: [`src/index.ts`](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/index.ts) (SDK entry), [`src/database/services/tenant-context.service.ts`](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/services/tenant-context.service.ts) (Tenant context), [`src/logger/logger.module.ts`](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/logger/logger.module.ts) (Logger module), [`src/data-table/data-table.module.ts`](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/data-table/data-table.module.ts) (Data table)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_src_index["SDK entry<br/>barrel<br/>[index.ts]"]
end

subgraph group_infra["Infrastructure"]
  node_auth_module["Auth module<br/>nest module"]
  node_auth_guard{{"Auth guard"}}
  node_logger_module["Logger module<br/>nest module<br/>[logger.module.ts]"]
  node_logger_service[("Logger service<br/>logging service<br/>[logger.service.ts]")]
  node_http_logger{{"HTTP logger<br/>interceptor"}}
  node_correlation_mw{{"Correlation ID<br/>middleware"}}
  node_cache_module["Cache module<br/>nest module<br/>[cache.module.ts]"]
  node_cache_service[("Cache service<br/>cache facade<br/>[cache.service.ts]")]
  node_redis_provider[("Redis provider<br/>cache provider<br/>[redis.provider.ts]")]
  node_request_module["Request module<br/>nest module<br/>[request.module.ts]"]
  node_request_service[("Request service<br/>request helper<br/>[request.service.ts]")]
  node_email_module["Email module<br/>nest module<br/>[email.module.ts]"]
end

subgraph group_data["Data Access"]
  node_db_module["Database module<br/>nest module<br/>[database.module.ts]"]
  node_tenant_ctx[("Tenant context<br/>request scope")]
  node_tenant_interceptor{{"HTTP tenant<br/>interceptor"}}
  node_message_interceptor{{"Msg tenant<br/>interceptor"}}
  node_primary_db[("Primary DB<br/>platform service")]
  node_tenant_db[("Tenant DB<br/>tenant service")]
  node_primary_repo["Primary repo<br/>base repository"]
  node_tenant_repo["Tenant repo<br/>base repository"]
end

subgraph group_features["Feature Modules"]
  node_data_table_module["Data table<br/>feature module"]
  node_views_service[("Views service<br/>feature service")]
  node_state_service[("State service<br/>feature service")]
  node_root_module["Root module<br/>app shell<br/>[root.module.ts]"]
  node_app_controller["App controller<br/>[app.controller.ts]"]
  node_csrf_controller["CSRF controller<br/>[csrf.controller.ts]"]
end

subgraph group_shared["Shared Utilities"]
  node_http_filter{{"HTTP filter<br/>exception filter"}}
  node_exceptions["Exceptions<br/>error catalog<br/>[index.ts]"]
  node_types["Types<br/>[index.ts]"]
end

node_src_index -->|"exports"| node_auth_module
node_src_index -->|"exports"| node_db_module
node_src_index -->|"exports"| node_logger_module
node_src_index -->|"exports"| node_cache_module
node_src_index -->|"exports"| node_request_module
node_src_index -->|"exports"| node_email_module
node_src_index -->|"exports"| node_data_table_module
node_src_index -->|"exports"| node_root_module
node_auth_module -->|"protects"| node_auth_guard
node_auth_module -.->|"relies on"| node_db_module
node_tenant_interceptor -->|"sets"| node_tenant_ctx
node_message_interceptor -->|"sets"| node_tenant_ctx
node_tenant_ctx -->|"resolves"| node_primary_db
node_tenant_ctx -->|"resolves"| node_tenant_db
node_primary_db -->|"backs"| node_primary_repo
node_tenant_db -->|"backs"| node_tenant_repo
node_logger_module -->|"provides"| node_logger_service
node_logger_module -->|"uses"| node_http_logger
node_logger_module -->|"uses"| node_correlation_mw
node_logger_service -->|"enriches with"| node_tenant_ctx
node_cache_module -->|"provides"| node_cache_service
node_cache_service -->|"implemented by"| node_redis_provider
node_request_module -->|"provides"| node_request_service
node_data_table_module -->|"contains"| node_views_service
node_data_table_module -->|"contains"| node_state_service
node_views_service -->|"uses"| node_tenant_repo
node_state_service -->|"uses"| node_tenant_repo
node_root_module -->|"hosts"| node_app_controller
node_root_module -->|"hosts"| node_csrf_controller
node_http_filter -->|"normalizes"| node_exceptions
node_db_module -.->|"shares errors with"| node_http_filter
node_db_module -->|"uses"| node_types
node_data_table_module -->|"uses"| node_types

click node_src_index "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/index.ts"
click node_auth_module "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/auth/auth-config.module.ts"
click node_auth_guard "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/auth/guards/vritti-auth.guard.ts"
click node_db_module "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/database.module.ts"
click node_tenant_ctx "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/services/tenant-context.service.ts"
click node_tenant_interceptor "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/interceptors/tenant-context.interceptor.ts"
click node_message_interceptor "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/interceptors/message-tenant-context.interceptor.ts"
click node_primary_db "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/services/primary-database.service.ts"
click node_tenant_db "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/services/tenant-database.service.ts"
click node_primary_repo "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/repositories/primary-base.repository.ts"
click node_tenant_repo "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/repositories/tenant-base.repository.ts"
click node_logger_module "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/logger/logger.module.ts"
click node_logger_service "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/logger/services/logger.service.ts"
click node_http_logger "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/logger/interceptors/http-logger.interceptor.ts"
click node_correlation_mw "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/logger/middleware/correlation-id.middleware.ts"
click node_cache_module "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/cache/cache.module.ts"
click node_cache_service "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/cache/cache.service.ts"
click node_redis_provider "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/cache/providers/redis.provider.ts"
click node_request_module "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/request/request.module.ts"
click node_request_service "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/request/services/request.service.ts"
click node_email_module "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/email/email.module.ts"
click node_data_table_module "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/data-table/data-table.module.ts"
click node_views_service "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/data-table/views/services/data-table-views.service.ts"
click node_state_service "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/data-table/state/services/data-table-state.service.ts"
click node_root_module "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/root/root.module.ts"
click node_app_controller "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/root/controllers/app.controller.ts"
click node_csrf_controller "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/root/controllers/csrf.controller.ts"
click node_http_filter "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/filters/http-exception.filter.ts"
click node_exceptions "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/exceptions/index.ts"
click node_types "https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/types/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_src_index toneBlue
class node_auth_module,node_auth_guard,node_logger_module,node_logger_service,node_http_logger,node_correlation_mw,node_cache_module,node_cache_service,node_redis_provider,node_request_module,node_request_service,node_email_module toneAmber
class node_db_module,node_tenant_ctx,node_tenant_interceptor,node_message_interceptor,node_primary_db,node_tenant_db,node_primary_repo,node_tenant_repo toneMint
class node_data_table_module,node_views_service,node_state_service,node_root_module,node_app_controller,node_csrf_controller toneRose
class node_http_filter,node_exceptions,node_types toneIndigo
```

## Components

### Public API

Package entrypoints and export surface

- [SDK entry](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/index.ts): barrel · Consolidated package exports · `src/index.ts`

### Infrastructure

Cross-cutting Nest modules and runtime services

- [Auth module](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/auth/auth-config.module.ts): nest module · JWT/session auth boundary · `src/auth/auth-config.module.ts`
- [Auth guard](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/auth/guards/vritti-auth.guard.ts): guard · Global auth policy enforcement · `src/auth/guards/vritti-auth.guard.ts`
- [Logger module](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/logger/logger.module.ts): nest module · Correlation-aware logging boundary · `src/logger/logger.module.ts`
- [Logger service](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/logger/services/logger.service.ts): logging service · Context-enriched application logging · `src/logger/services/logger.service.ts`
- [HTTP logger](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/logger/interceptors/http-logger.interceptor.ts): interceptor · Captures request/response logs · `src/logger/interceptors/http-logger.interceptor.ts`
- [Correlation ID](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/logger/middleware/correlation-id.middleware.ts): middleware · Attaches request correlation IDs · `src/logger/middleware/correlation-id.middleware.ts`
- [Cache module](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/cache/cache.module.ts): nest module · Pluggable cache boundary · `src/cache/cache.module.ts`
- [Cache service](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/cache/cache.service.ts): cache facade · Backend-agnostic cache operations · `src/cache/cache.service.ts`
- [Redis provider](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/cache/providers/redis.provider.ts): cache provider · Concrete Redis-backed cache implementation · `src/cache/providers/redis.provider.ts`
- [Request module](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/request/request.module.ts): nest module · Request-scoped helper boundary · `src/request/request.module.ts`
- [Request service](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/request/services/request.service.ts): request helper · Shared request utilities · `src/request/services/request.service.ts`
- [Email module](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/email/email.module.ts): nest module · Email integration boundary · `src/email/email.module.ts`

### Data Access

Tenant-aware database plane and query helpers

- [Database module](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/database.module.ts): nest module · Tenant-aware data access composition · `src/database/database.module.ts`
- [Tenant context](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/services/tenant-context.service.ts): request scope · Holds tenant identity for the lifecycle · `src/database/services/tenant-context.service.ts`
- [HTTP tenant](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/interceptors/tenant-context.interceptor.ts): interceptor · Extracts tenant from requests · `src/database/interceptors/tenant-context.interceptor.ts`
- [Msg tenant](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/interceptors/message-tenant-context.interceptor.ts): interceptor · Injects tenant from message payloads · `src/database/interceptors/message-tenant-context.interceptor.ts`
- [Primary DB](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/services/primary-database.service.ts): platform service · Registry and platform-level data access · `src/database/services/primary-database.service.ts`
- [Tenant DB](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/services/tenant-database.service.ts): tenant service · Resolves tenant-specific database client · `src/database/services/tenant-database.service.ts`
- [Primary repo](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/repositories/primary-base.repository.ts): base repository · Reusable CRUD on primary database · `src/database/repositories/primary-base.repository.ts`
- [Tenant repo](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/database/repositories/tenant-base.repository.ts): base repository · Reusable CRUD on tenant databases · `src/database/repositories/tenant-base.repository.ts`

### Feature Modules

Business-facing feature areas built on the infrastructure

- [Data table](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/data-table/data-table.module.ts): feature module · Views and saved state feature area · `src/data-table/data-table.module.ts`
- [Views service](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/data-table/views/services/data-table-views.service.ts): feature service · Named and shareable table views · `src/data-table/views/services/data-table-views.service.ts`
- [State service](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/data-table/state/services/data-table-state.service.ts): feature service · User-specific table UI state · `src/data-table/state/services/data-table-state.service.ts`
- [Root module](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/root/root.module.ts): app shell · Bootstrap endpoints and CSRF surface · `src/root/root.module.ts`
- [App controller](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/root/controllers/app.controller.ts): controller · General application endpoints · `src/root/controllers/app.controller.ts`
- [CSRF controller](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/root/controllers/csrf.controller.ts): controller · CSRF-related endpoints · `src/root/controllers/csrf.controller.ts`

### Shared Utilities

Common types, filters, exceptions, and helpers

- [HTTP filter](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/filters/http-exception.filter.ts): exception filter · Normalizes error responses · `src/filters/http-exception.filter.ts`
- [Exceptions](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/exceptions/index.ts): error catalog · Standard HTTP exception classes · `src/exceptions/index.ts`
- [Types](https://github.com/vritti-ai-platforms/api-sdk/blob/main/src/types/index.ts): shared types · Common DTOs and type definitions · `src/types/index.ts`

## Connections

- SDK entry → Auth module: exports · Public SDK surface re-exports auth boundary
- SDK entry → Database module: exports · Public SDK surface re-exports database boundary
- SDK entry → Logger module: exports · Public SDK surface re-exports logging boundary
- SDK entry → Cache module: exports · Public SDK surface re-exports cache boundary
- SDK entry → Request module: exports · Public SDK surface re-exports request helpers
- SDK entry → Email module: exports · Public SDK surface re-exports email boundary
- SDK entry → Data table: exports · Public SDK surface re-exports feature module
- SDK entry → Root module: exports · Public SDK surface re-exports bootstrap module
- Auth module → Auth guard: protects · Auth module applies global policy
- Auth module → Database module: relies on · Auth and tenant resolution share request/database context
- HTTP tenant → Tenant context: sets · HTTP requests populate tenant context
- Msg tenant → Tenant context: sets · Message payloads populate tenant context
- Tenant context → Primary DB: resolves · Tenant identity drives primary registry lookups
- Tenant context → Tenant DB: resolves · Tenant identity selects tenant database client
- Primary DB → Primary repo: backs · Primary database service underpins base repository
- Tenant DB → Tenant repo: backs · Tenant database service underpins tenant repository
- Logger module → Logger service: provides · Logger module exposes logging service
- Logger module → HTTP logger: uses · HTTP interceptor emits request logs
- Logger module → Correlation ID: uses · Middleware adds correlation IDs
- Logger service → Tenant context: enriches with · Logs can include tenant-aware context
- Cache module → Cache service: provides · Cache module exposes cache facade
- Cache service → Redis provider: implemented by · Redis is the concrete backend
- Request module → Request service: provides · Request module exposes request helpers
- Data table → Views service: contains · Table views are a feature sub-area
- Data table → State service: contains · Table state is a feature sub-area
- Views service → Tenant repo: uses · Views persist through tenant-scoped repositories
- State service → Tenant repo: uses · Saved state persists through tenant-scoped repositories
- Root module → App controller: hosts · Bootstrap module exposes app endpoints
- Root module → CSRF controller: hosts · Bootstrap module exposes CSRF endpoints
- HTTP filter → Exceptions: normalizes · Exception filter standardizes error output
- Database module → HTTP filter: shares errors with · Database and request failures use common response shape
- Database module → Types: uses · Database layer shares DTOs and types
- Data table → Types: uses · Feature layer reuses shared DTOs and types
