# devangelcrow/inventory_backend architecture

> Architecture diagram of the GitHub repository devangelcrow/inventory_backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devangelcrow/inventory_backend
- Repository: https://github.com/devangelcrow/inventory_backend

## Overview

1. This repository is a NestJS 11 backend for electronic invoicing, built in TypeScript with Prisma ORM against PostgreSQL 16. It is organized as a modular monolith, with a single HTTP application plus a separate worker entrypoint for background jobs.

2. The core architectural style is Hexagonal Architecture with DDD and CQRS. Each business module is split into domain, application, and infrastructure layers, and application writes are modeled as Commands while reads are modeled as Queries, dispatched through Nest’s CommandBus and QueryBus.

3. The main runtime entrypoints are `src/main.ts` for the REST API and `src/worker.ts` for BullMQ processing. The worker is separate from HTTP and is meant for queue consumers such as email processing or other async tasks.

4. Persistence is centered on Prisma and PostgreSQL. Domain repository interfaces live in each module’s domain layer, while Prisma-backed implementations sit in infrastructure. Database changes are managed through Prisma migrations and seeded through a set of seeders under `prisma/seeds`.

5. `auth` is the session and identity lifecycle module. It covers register/login/logout, access and refresh token handling, email verification, password reset flows, session revocation, and profile updates. It also depends on email delivery, JWT token services, refresh-token persistence, and throttling/lockout rules.

6. `identity-access-management` manages system users and their authentication-facing identity records. It exposes user CRUD and lookup flows used by auth, and acts as a bridge between user records and other identity concepts such as username, email, password state, and reset flows.

7. `profile` owns person-centric data: person, address, document, and document type. This module is notable because profile updates fan out into multiple sub-entities and are wrapped in a shared transaction boundary, so a single request can update person/address/document consistently.

8. `catalogs` provides reference data used across the rest of the system: countries, genders, marital status, geographic divisions, category status, and global status. It is heavily value-object driven and serves as a shared lookup source for profile, IAM, and other modules.

9. `security` is the authorization subsystem. It defines roles, permissions, routes, category permissions, and user-role relationships, plus the “menu” projection used by clients. It also exposes guards and custom decorators that enforce route-level permissions and user-specific access checks.

10. `storage` abstracts file persistence behind a backend registry. It can store files locally or in S3-compatible storage, selected by configuration. Upload flows validate file type and metadata, then persist file records and file content/path details separately from application data.

11. `audit` records sensitive actions as structured audit logs. It is designed as a cross-cutting module: the application can mark operations as auditable, and the infrastructure layer can intercept or record those events without coupling business handlers directly to logging concerns.

12. `shared` contains the platform-level foundation used by every module: common pagination DTOs, domain/application exceptions, base repository abstractions, transaction helpers, cache/Redis wiring, Prisma wiring, HTTP filters/interceptors/middleware, health checks, and utility mappers. This is the main boundary where reusable infrastructure lives instead of inside business modules.

13. HTTP flow is layered: controller → validation DTOs/guards/interceptors → CQRS command/query → handler → service/use case → repository implementation → Prisma/PostgreSQL. For some flows, especially profile updates and file uploads, the request also passes through transaction and multipart/file-handling infrastructure before reaching the handler.

14. The supporting infrastructure matters to the diagram: Redis is used for cache/queues, BullMQ for async processing, JWT and Passport strategies for auth, Swagger/Scalar for docs, and Docker Compose for local orchestration of the app, PostgreSQL, Redis, and SonarQube. Health and metrics endpoints are also present under `shared/infrastructure/health`.

15. Overall, the system is not a generic CRUD app: it is a domain-heavy backend with distinct bounded contexts for identity, profile, catalogs, security, storage, and audit, all coordinated through NestJS module boundaries and Prisma-backed persistence.

Main entry points: [`src/app.module.ts`](https://github.com/devangelcrow/inventory_backend/blob/master/src/app.module.ts) (App module), [`src/modules/auth/auth.module.ts`](https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/auth/auth.module.ts) (Auth), [`src/shared/infrastructure/persistence/prisma/prisma.module.ts`](https://github.com/devangelcrow/inventory_backend/blob/master/src/shared/infrastructure/persistence/prisma/prisma.module.ts) (Prisma), [`src/modules/security/security.module.ts`](https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/security/security.module.ts) (Security)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app_module["App module<br/>nest-composition<br/>[app.module.ts]"]
  node_http_main(("HTTP main<br/>rest-entrypoint<br/>[main.ts]"))
  node_worker_module["Worker module<br/>nest-composition<br/>[worker.module.ts]"]
  node_worker_main(("Worker main<br/>queue-entrypoint<br/>[worker.ts]"))
end

subgraph group_domains["Business modules"]
  node_auth["Auth<br/>session-lifecycle<br/>[auth.module.ts]"]
  node_iam["Identity IAM<br/>user-identity"]
  node_profile["Profile<br/>[profile.module.ts]"]
  node_catalogs["Catalogs<br/>reference-data<br/>[catalogs.module.ts]"]
  node_security["Security<br/>authorization<br/>[security.module.ts]"]
  node_storage["Storage<br/>[storage.module.ts]"]
  node_audit["Audit<br/>[audit.module.ts]"]
end

subgraph group_shared["Shared foundation"]
  node_shared_core["Shared core<br/>platform-kernel"]
  node_http_api["HTTP stack<br/>web-infrastructure"]
  node_tx_support{{"Transactions<br/>unit-of-work"}}
end

subgraph group_platform["Platform"]
  node_prisma[("Prisma<br/>orm-adapter<br/>[prisma.module.ts]")]
  node_postgres[("PostgreSQL<br/>database")]
  node_redis_bullmq["Redis/BullMQ<br/>cache-queue<br/>[queues.module.ts]"]
  node_email_jwt["Email/JWT<br/>external-services"]
  node_migrations["Migrations<br/>schema-evolution<br/>[migration.sql]"]
  node_seeds["Seeders<br/>bootstrap-data<br/>[main.seeder.ts]"]
end

node_http_main -->|"boots"| node_app_module
node_worker_main -->|"boots"| node_worker_module
node_app_module -->|"imports"| node_shared_core
node_app_module -->|"loads"| node_auth
node_app_module -->|"loads"| node_iam
node_app_module -->|"loads"| node_profile
node_app_module -->|"loads"| node_catalogs
node_app_module -->|"loads"| node_security
node_app_module -->|"loads"| node_storage
node_app_module -->|"loads"| node_audit
node_worker_module -->|"consumes"| node_storage
node_worker_module -->|"consumes"| node_auth
node_auth -->|"queries"| node_iam
node_auth -->|"reads profile"| node_profile
node_auth -->|"checks access"| node_security
node_auth -->|"uses"| node_email_jwt
node_profile -->|"uses lookups"| node_catalogs
node_profile -->|"wraps writes"| node_tx_support
node_security -->|"uses status"| node_catalogs
node_security -->|"caches"| node_redis_bullmq
node_storage -->|"queues"| node_redis_bullmq
node_storage -->|"persists"| node_prisma
node_audit -->|"persists"| node_prisma
node_shared_core -->|"provides"| node_prisma
node_prisma -->|"connects to"| node_postgres
node_prisma -->|"managed by"| node_migrations
node_prisma -->|"initialized by"| node_seeds
node_auth -->|"served by"| node_http_api
node_catalogs -->|"served by"| node_http_api
node_security -->|"served by"| node_http_api
node_storage -->|"served by"| node_http_api

click node_app_module "https://github.com/devangelcrow/inventory_backend/blob/master/src/app.module.ts"
click node_http_main "https://github.com/devangelcrow/inventory_backend/blob/master/src/main.ts"
click node_worker_module "https://github.com/devangelcrow/inventory_backend/blob/master/src/worker.module.ts"
click node_worker_main "https://github.com/devangelcrow/inventory_backend/blob/master/src/worker.ts"
click node_auth "https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/auth/auth.module.ts"
click node_iam "https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/identity-access-management/identity-access-management.module.ts"
click node_profile "https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/profile/profile.module.ts"
click node_catalogs "https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/catalogs/catalogs.module.ts"
click node_security "https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/security/security.module.ts"
click node_storage "https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/storage/storage.module.ts"
click node_audit "https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/audit/audit.module.ts"
click node_shared_core "https://github.com/devangelcrow/inventory_backend/tree/master/src/shared"
click node_prisma "https://github.com/devangelcrow/inventory_backend/blob/master/src/shared/infrastructure/persistence/prisma/prisma.module.ts"
click node_redis_bullmq "https://github.com/devangelcrow/inventory_backend/blob/master/src/shared/infrastructure/queues/queues.module.ts"
click node_email_jwt "https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/auth/infrastructure/services/jwt-token-hasher.service.ts"
click node_migrations "https://github.com/devangelcrow/inventory_backend/blob/master/prisma/migrations/20260609191024/migration.sql"
click node_seeds "https://github.com/devangelcrow/inventory_backend/blob/master/prisma/seeds/main.seeder.ts"
click node_http_api "https://github.com/devangelcrow/inventory_backend/blob/master/src/shared/infrastructure/http/filters/http-exception.filter.ts"
click node_tx_support "https://github.com/devangelcrow/inventory_backend/blob/master/src/shared/infrastructure/decorators/transactional.decorator.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_app_module,node_http_main,node_worker_module,node_worker_main toneBlue
class node_auth,node_iam,node_profile,node_catalogs,node_security,node_storage,node_audit toneAmber
class node_shared_core,node_http_api,node_tx_support toneMint
class node_prisma,node_postgres,node_redis_bullmq,node_email_jwt,node_migrations,node_seeds toneRose
```

## Components

### Runtime

HTTP API and worker entrypoints

- [App module](https://github.com/devangelcrow/inventory_backend/blob/master/src/app.module.ts): nest-composition · Main HTTP composition root that wires feature modules and shared infrastructure · `src/app.module.ts`
- [HTTP main](https://github.com/devangelcrow/inventory_backend/blob/master/src/main.ts): rest-entrypoint · Bootstraps the Nest HTTP application · `src/main.ts`
- [Worker module](https://github.com/devangelcrow/inventory_backend/blob/master/src/worker.module.ts): nest-composition · Composition root for background job processing · `src/worker.module.ts`
- [Worker main](https://github.com/devangelcrow/inventory_backend/blob/master/src/worker.ts): queue-entrypoint · Bootstraps BullMQ consumers and async processing · `src/worker.ts`

### Business modules

Bounded contexts and their main flows

- [Auth](https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/auth/auth.module.ts): session-lifecycle · Register, login, refresh, logout, verification, reset, and session revocation flows · `src/modules/auth/auth.module.ts`
- [Identity IAM](https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/identity-access-management/identity-access-management.module.ts): user-identity · System users and authentication-facing identity records · `src/modules/identity-access-management/identity-access-management.module.ts`
- [Profile](https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/profile/profile.module.ts): person-profile · Person, address, document, and document type management · `src/modules/profile/profile.module.ts`
- [Catalogs](https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/catalogs/catalogs.module.ts): reference-data · Shared lookup and value-object driven reference data · `src/modules/catalogs/catalogs.module.ts`
- [Security](https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/security/security.module.ts): authorization · Roles, permissions, routes, menus, and user-role access checks · `src/modules/security/security.module.ts`
- [Storage](https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/storage/storage.module.ts): file-storage · File upload and backend selection across local and S3-compatible storage · `src/modules/storage/storage.module.ts`
- [Audit](https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/audit/audit.module.ts): audit-log · Structured audit logging for sensitive actions · `src/modules/audit/audit.module.ts`

### Shared foundation

Cross-cutting application and infrastructure primitives

- [Shared core](https://github.com/devangelcrow/inventory_backend/tree/master/src/shared): platform-kernel · Common domain, application, HTTP, cache, queue, and utility foundations · `src/shared`
- [HTTP stack](https://github.com/devangelcrow/inventory_backend/blob/master/src/shared/infrastructure/http/filters/http-exception.filter.ts): web-infrastructure · Controllers, DTOs, guards, filters, and CQRS dispatch · `src/shared/infrastructure/http/filters/http-exception.filter.ts`
- [Transactions](https://github.com/devangelcrow/inventory_backend/blob/master/src/shared/infrastructure/decorators/transactional.decorator.ts): unit-of-work · Transactional helpers and request-scoped transaction coordination · `src/shared/infrastructure/decorators/transactional.decorator.ts`

### Platform

Persistence, queues, cache, and external runtime dependencies

- [Prisma](https://github.com/devangelcrow/inventory_backend/blob/master/src/shared/infrastructure/persistence/prisma/prisma.module.ts): orm-adapter · Prisma service and relational persistence boundary · `src/shared/infrastructure/persistence/prisma/prisma.module.ts`
- **PostgreSQL**: database · Primary relational datastore
- [Redis/BullMQ](https://github.com/devangelcrow/inventory_backend/blob/master/src/shared/infrastructure/queues/queues.module.ts): cache-queue · Cache, throttling, and background job transport · `src/shared/infrastructure/queues/queues.module.ts`
- [Email/JWT](https://github.com/devangelcrow/inventory_backend/blob/master/src/modules/auth/infrastructure/services/jwt-token-hasher.service.ts): external-services · Email delivery and token strategy services used by auth · `src/modules/auth/infrastructure/services/jwt-token-hasher.service.ts`
- [Migrations](https://github.com/devangelcrow/inventory_backend/blob/master/prisma/migrations/20260609191024/migration.sql): schema-evolution · Prisma migration history for database changes · `prisma/migrations/20260609191024/migration.sql`
- [Seeders](https://github.com/devangelcrow/inventory_backend/blob/master/prisma/seeds/main.seeder.ts): bootstrap-data · Prisma seed set for reference and initial data · `prisma/seeds/main.seeder.ts`

## Connections

- HTTP main → App module: boots · HTTP bootstrap loads the main Nest application graph
- Worker main → Worker module: boots · Worker bootstrap loads queue consumers
- App module → Shared core: imports · Application composition depends on shared foundations
- App module → Auth: loads · HTTP app includes the auth bounded context
- App module → Identity IAM: loads · HTTP app includes identity management
- App module → Profile: loads · HTTP app includes profile management
- App module → Catalogs: loads · HTTP app includes reference data APIs
- App module → Security: loads · HTTP app includes authorization APIs
- App module → Storage: loads · HTTP app includes storage APIs
- App module → Audit: loads · HTTP app includes audit APIs
- Worker module → Storage: consumes · Worker can process async storage-related jobs
- Worker module → Auth: consumes · Worker handles queued auth email jobs
- Auth → Identity IAM: queries · Auth relies on user identity lookup and lifecycle operations
- Auth → Profile: reads profile · Auth updates and authenticates against profile data
- Auth → Security: checks access · Auth interacts with role and permission context
- Auth → Email/JWT: uses · Auth depends on email delivery and JWT services
- Profile → Catalogs: uses lookups · Profile validates person data against catalog values
- Profile → Transactions: wraps writes · Profile updates are coordinated in a shared transaction boundary
- Security → Catalogs: uses status · Security reuses global status and related catalog data
- Security → Redis/BullMQ: caches · Authorization checks can use cache-backed access data
- Storage → Redis/BullMQ: queues · Upload and file processing can use background queues
- Storage → Prisma: persists · Storage metadata and file records are stored through Prisma
- Audit → Prisma: persists · Audit logs are written via Prisma-backed repository implementations
- Shared core → Prisma: provides · Shared persistence wiring includes Prisma integration
- Prisma → PostgreSQL: connects to · Prisma talks to PostgreSQL as the primary database
- Prisma → Migrations: managed by · Schema changes are applied through migrations
- Prisma → Seeders: initialized by · Initial and reference data are loaded from seeders
- Auth → HTTP stack: served by · Auth flows are exposed through the HTTP stack
- Catalogs → HTTP stack: served by · Catalog CRUD and reads are exposed through HTTP
- Security → HTTP stack: served by · Authorization endpoints and guards sit in the HTTP layer
- Storage → HTTP stack: served by · File upload and storage endpoints are exposed through HTTP