Skip to main content
doc0blade47/compdocumentation home
Sign in

API Architecture

Last updated Oct 11, 2026
Relevant source files

The following files were used as context for generating this wiki page:

The API architecture is built upon the NestJS framework, providing a structured and modular approach to developing server-side applications. It serves as the central backend for various functionalities, integrating numerous domain-specific modules, handling requests, and providing a robust and scalable foundation.

The core of the API is defined by its entry point (main.ts), which initializes the NestJS application, configures global middleware, security settings, and API documentation. The AppModule acts as the root module, orchestrating the integration of various feature modules, configuration settings, and global guards to manage the application's overall behavior.

Application Entry Point and Bootstrap Process

The main.ts file is the primary entry point for the API application. It is responsible for bootstrapping the NestJS application, applying global configurations, setting up middleware, and starting the HTTP server. Before the NestJS application starts, environment variables are loaded to ensure proper configuration.

The bootstrap function performs several critical steps:

  1. Application Creation: Initializes the NestJS application using AppModule.
  2. CORS Configuration: Enables Cross-Origin Resource Sharing for all origins, with credentials and exposed headers.
  3. Security Headers: Applies helmet middleware to set various HTTP security headers, including Content Security Policy (CSP).
  4. Body Parsing: Configures express.json and express.urlencoded to handle request body parsing, with a generous limit of 150MB to accommodate large payloads like base64-encoded attachments.
  5. Global Pipes: Registers a ValidationPipe globally to enforce data validation, whitelisting, and automatic transformation of incoming data.
  6. API Versioning: Enables URI-based API versioning, defaulting to version 1.
  7. Swagger/OpenAPI Documentation: Generates and serves interactive API documentation at /api/docs. In development environments, it also writes the OpenAPI specification to a JSON file.
  8. Server Start: Listens for incoming HTTP requests on a configured port (defaulting to 3333).
  9. Graceful Shutdown: Implements handlers for SIGTERM and SIGINT signals to ensure the application closes gracefully.

Sources: apps/api/src/main.ts:1-93

Core Module Structure

The AppModule (app.module.ts) serves as the root module of the NestJS application. It aggregates all other feature modules, global configurations, and providers, defining the overall structure and dependencies of the API.

Key Components of AppModule

  • imports: This array lists all the modules that AppModule depends on. It includes:
    • ConfigModule: For loading and managing application configurations.
    • ThrottlerModule: Implements rate limiting to protect against abuse.
    • A comprehensive list of feature modules, each encapsulating specific domain logic (e.g., AuthModule, OrganizationModule, DevicesModule, TasksModule, SOAModule, CloudSecurityModule, etc.).
  • controllers: Declares AppController, which handles basic routes like the root redirect to API documentation.
  • providers: Registers services and other injectable components, including AppService and a global ThrottlerGuard for rate limiting.

Sources: apps/api/src/app.module.ts:1-85

Configuration Management

The ConfigModule is configured globally within AppModule to load environment-specific configurations. It uses awsConfig and betterAuthConfig to provide structured configuration objects throughout the application. The .env file is loaded manually in main.ts before NestJS initializes, ensuring that environment variables are available for configuration loading.

Configuration Loading

The ConfigModule is configured with isGlobal: true, making the configuration available across all modules without needing to re-import it. The load property specifies configuration factories (awsConfig, betterAuthConfig) that provide typed configuration objects.

Sources: apps/api/src/app.module.ts:10-21, apps/api/src/main.ts:1

Request Handling Flow

When a request arrives at the API, it passes through a series of middleware, guards, pipes, and controllers before reaching the business logic in services.

Sources: apps/api/src/main.ts:1-93, apps/api/src/app.module.ts:22-30, apps/api/src/app.controller.ts:1-12, apps/api/src/app.service.ts:1-7

Global Middleware and Guards

The API employs several global mechanisms to ensure security, performance, and data integrity:

  • CORS: Enabled for all origins (origin: true) to allow client applications to interact with the API.
  • Helmet: Configured to add various HTTP security headers, including a Content Security Policy (CSP) that restricts sources for scripts, styles, images, and connections.
  • Body Parsers: express.json and express.urlencoded are used to parse incoming request bodies, with a 150mb limit to support large data transfers.
  • ThrottlerGuard: A global guard provided by ThrottlerModule that limits requests to 100 per minute per IP address, preventing abuse and ensuring service availability.

Sources: apps/api/src/main.ts:18-47, apps/api/src/app.module.ts:22-30

Validation Pipe

A global ValidationPipe is applied to all incoming requests. This pipe automatically validates incoming data against defined DTOs (Data Transfer Objects), ensuring that requests conform to expected schemas.

ValidationPipe Configuration

The ValidationPipe is configured with:

  • whitelist: true: Removes properties that are not defined in the DTO.
  • forbidNonWhitelisted: true: Throws an error if non-whitelisted properties are present.
  • transform: true: Automatically transforms incoming payload objects to DTO instances.
  • transformOptions: { enableImplicitConversion: true }: Enables implicit type conversion for primitive types.

Sources: apps/api/src/main.ts:50-59

API Versioning

The API supports URI-based versioning, allowing different versions of endpoints to coexist. The default version is 1.

app.enableVersioning({
  type: VersioningType.URI,
  defaultVersion: '1',
});

This means endpoints can be accessed like /v1/resource or /v1/another-resource. Sources: apps/api/src/main.ts:61-64

API Documentation

The API automatically generates and serves interactive documentation using Swagger (OpenAPI). This documentation is accessible at /api/docs.

Documentation Features

  • Title and Description: Provides a clear overview of the API.
  • Version: Specifies the API version (1.0).
  • Servers: Lists available API servers, including local development and production environments.
  • Authentication: Supports API key authentication (X-API-Key header).
  • Persistence: Swagger UI is configured to persist authorization tokens between page refreshes.
  • Development Output: In non-production environments, the OpenAPI specification is written to packages/docs/openapi.json for external tooling or reference.

Sources: apps/api/src/main.ts:68-93

Root Endpoint Redirect

The root path (/) of the API is configured to automatically redirect clients to the Swagger documentation page (/api/docs). This redirect is excluded from the generated Swagger documentation itself.

@Controller({ version: VERSION_NEUTRAL })
export class AppController {
  constructor(private readonly appService: AppService) {}
 
  @Get()
  @Redirect('/api/docs', 302)
  @ApiExcludeEndpoint()
  redirectToSwagger(): void {
    // This method redirects to Swagger documentation
  }
}

Sources: apps/api/src/app.controller.ts:1-12

Was this page helpful?