devangelcrow/inventory_backend

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.