Skip to content

Architecture

Overview

dichit-backend is a Fastify-based TypeScript API organized around clean architecture and dependency injection.

Primary layers:

  • src/domain for entities and domain-level helpers
  • src/application for use cases, services, queue orchestration, and dependency contracts
  • src/infrastructure for framework integrations, repositories, config, auth, queues, and external providers
  • src/interfaces for HTTP bootstrap, routes, controllers, webhooks, and shutdown wiring
  • src/shared for shared schemas, constants, errors, and utilities

Application Bootstrap

The runtime starts from src/interfaces/server.ts, which:

  • initializes environment loading
  • configures Fastify and Sentry
  • calls makeApp
  • starts the HTTP server

src/interfaces/app.ts is the main composition root. It:

  • registers the Awilix container
  • loads infrastructure dependencies from src/infrastructure/di.ts
  • auto-loads Fastify plugins from src/infrastructure/plugins
  • registers platform routes
  • registers Swagger and API route trees for v1, v2, v3, and webhooks
  • starts queue processors and optionally Bull Board
  • wires graceful shutdown and dependency disposal

Dependency Injection

Awilix is used as the central composition mechanism.

  • Infrastructure implementations are created in src/infrastructure/di.ts
  • Application code depends on interfaces/contracts from src/application/interfaces
  • Route handlers and services consume dependencies through the Fastify/Awilix cradle

This keeps controllers and use cases decoupled from concrete implementations.

HTTP Layer

Routes live under src/interfaces/http/routes.

  • v1 contains older route modules
  • v2 and v3 are organized for file-system autoloading
  • dynamic route segments use [param] directory naming
  • platform routes and webhooks are registered separately

Controllers should stay thin:

  • validate input
  • delegate to application use cases
  • return response contracts

Data Access

PostgreSQL access primarily lives in src/infrastructure/db/postgres/repositories.

  • Prisma is the main ORM
  • repositories are the default boundary for reads and writes
  • UnitOfWork is used where transactions span multiple operations
  • raw SQL is acceptable inside repository/infrastructure code when it reduces round trips or simplifies efficient retrieval

Generated Prisma client code lives under src/generated/prisma/client.

Queues and Background Work

Queue processors and queue services live in src/application/queue.

  • queue processors are registered during app bootstrap
  • workers are started by default in the main app
  • Bull Board can be registered for monitoring

Background processing is preferred for heavier or asynchronous work that should not block request handling.

Configuration and Environments

Environment selection is centralized in src/infrastructure/config/env-config.ts.

Common environment files:

  • .env.local
  • .env.dev
  • .env.test
  • .env.staging
  • .env.prod

The app, tests, seeders, and deployment workflows rely on those environment-specific values.

PAYMENT_GATEWAY_MODE selects zwitch or the built-in mock payment adapter. Mock mode is accepted only for local, development, and test runtimes; staging and production fail configuration validation if it is enabled. The authenticated mock-outcome route is registered only while mock mode is active.

High-Level Request Flow

  1. Fastify receives the request
  2. shared and infrastructure plugins run
  3. route validation/schema handling executes
  4. the controller or route handler delegates into an application use case
  5. the use case coordinates repositories/services
  6. repository/infrastructure code talks to PostgreSQL, Redis, S3, Firebase, queues, or other providers
  7. the response is mapped back through the interfaces layer