How vritti-ai-platforms/api-sdk works
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: index.ts SDK entry · tenant-context.service.ts Tenant context · logger.module.ts Logger module · data-table.module.ts Data table
Components 30
Public API
Package entrypoints and export surface
- SDK entry · Consolidated package exports
src/index.ts
Infrastructure
Cross-cutting Nest modules and runtime services
- Auth module · JWT/session auth boundary
src/auth/auth-config.module.ts - Auth guard · Global auth policy enforcement
src/auth/guards/vritti-auth.guard.ts - Logger module · Correlation-aware logging boundary
src/logger/logger.module.ts - Logger service · Context-enriched application logging
src/logger/services/logger.service.ts - HTTP logger · Captures request/response logs
src/logger/interceptors/http-logger.interceptor.ts - Correlation ID · Attaches request correlation IDs
src/logger/middleware/correlation-id.middleware.ts - Cache module · Pluggable cache boundary
src/cache/cache.module.ts - Cache service · Backend-agnostic cache operations
src/cache/cache.service.ts - Redis provider · Concrete Redis-backed cache implementation
src/cache/providers/redis.provider.ts - Request module · Request-scoped helper boundary
src/request/request.module.ts - Request service · Shared request utilities
src/request/services/request.service.ts - Email module · Email integration boundary
src/email/email.module.ts
Data Access
Tenant-aware database plane and query helpers
- Database module · Tenant-aware data access composition
src/database/database.module.ts - Tenant context · Holds tenant identity for the lifecycle
src/database/services/tenant-context.service.ts - HTTP tenant · Extracts tenant from requests
src/database/interceptors/tenant-context.interceptor.ts - Msg tenant · Injects tenant from message payloads
src/database/interceptors/message-tenant-context.interceptor.ts - Primary DB · Registry and platform-level data access
src/database/services/primary-database.service.ts - Tenant DB · Resolves tenant-specific database client
src/database/services/tenant-database.service.ts - Primary repo · Reusable CRUD on primary database
src/database/repositories/primary-base.repository.ts - Tenant repo · Reusable CRUD on tenant databases
src/database/repositories/tenant-base.repository.ts
Feature Modules
Business-facing feature areas built on the infrastructure
- Data table · Views and saved state feature area
src/data-table/data-table.module.ts - Views service · Named and shareable table views
src/data-table/views/services/data-table-views.service.ts - State service · User-specific table UI state
src/data-table/state/services/data-table-state.service.ts - Root module · Bootstrap endpoints and CSRF surface
src/root/root.module.ts - App controller · General application endpoints
src/root/controllers/app.controller.ts - CSRF controller · CSRF-related endpoints
src/root/controllers/csrf.controller.ts
Shared Utilities
Common types, filters, exceptions, and helpers
- HTTP filter · Normalizes error responses
src/filters/http-exception.filter.ts - Exceptions · Standard HTTP exception classes
src/exceptions/index.ts - Types · Common DTOs and type definitions
src/types/index.ts
Connections 33
- 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