# collatzconjecture/nestjs-clean-architecture architecture

> Architecture diagram of the GitHub repository collatzconjecture/nestjs-clean-architecture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/collatzconjecture/nestjs-clean-architecture
- Repository: https://github.com/collatzconjecture/nestjs-clean-architecture

## Overview

This NestJS application exposes versioned HTTP authentication and profile APIs. The main workflow is request → controller → application orchestration/CQRS → domain rules and repository contracts → MongoDB-backed repositories, with response handling on the way out. Authentication also supports JWT refresh, Google OAuth, RBAC, and registration events/saga orchestration; profile management has its own commands and services. The README documents broader architecture and operational capabilities, but sampled files do not establish all runtime wiring, so uncertain links are omitted.

Main entry points: [`src/application/services/auth.service.ts`](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/services/auth.service.ts) (Auth Orchestration), [`src/app.module.ts`](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/app.module.ts) (Root Module), [`src/application/auth/command/handler/create-auth-user.handler.ts`](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/auth/command/handler/create-auth-user.handler.ts) (Auth Commands), [`src/api/controllers/auth.controller.ts`](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/api/controllers/auth.controller.ts) (Auth Endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_auth_controller["Auth Endpoints<br/>[auth.controller.ts]"]
  node_profile_controller["Profile Endpoints"]
  node_api_module["API Module<br/>[api.module.ts]"]
end

subgraph group_application["Application Workflows"]
  node_response_service["Response Formatting"]
  node_auth_service["Auth Orchestration<br/>[auth.service.ts]"]
  node_auth_handlers["Auth Commands"]
  node_registration_saga["Registration Saga"]
  node_auth_security["Auth Strategies &amp; RBAC"]
  node_profile_service["Profile Service<br/>[profile.service.ts]"]
  node_profile_handler["Profile Command Handler"]
  node_request_middleware["Request Middleware"]
  node_response_pipeline["Response &amp; Errors"]
end

subgraph group_domain["Domain Model"]
  node_auth_domain["Auth Rules"]
  node_profile_domain["Profile Rules"]
  node_auth_entity["Auth Entity<br/>[Auth.ts]"]
  node_profile_entity["Profile Entity<br/>[Profile.ts]"]
  node_auth_contract["Auth Repository Contract"]
  node_profile_contract["Profile Repository Contract"]
end

subgraph group_infrastructure["Infrastructure"]
  node_auth_repository["Auth Repository<br/>[auth.repository.ts]"]
  node_profile_repository["Profile Repository"]
  node_auth_model["Auth Mongo Model<br/>[auth.model.ts]"]
  node_profile_model["Profile Mongo Model<br/>[profile.model.ts]"]
  node_health["Health Checks"]
  node_operations["Logging &amp; Metrics"]
  node_app_module["Root Module<br/>[app.module.ts]"]
  node_entrypoint["Nest Bootstrap<br/>[main.ts]"]
  node_db_providers["Database Provider"]
end

node_client(("API Client"))
node_database[("MongoDB")]
node_google(("Google OAuth"))

node_client -->|"sends requests"| node_auth_controller
node_client -->|"sends requests"| node_profile_controller
node_auth_controller -->|"calls"| node_auth_service
node_profile_controller -->|"calls"| node_profile_service
node_auth_controller -->|"formats results"| node_response_service
node_profile_controller -->|"formats results"| node_response_service
node_auth_service -->|"dispatches commands"| node_auth_handlers
node_auth_service -->|"reads and writes"| node_auth_contract
node_auth_service -->|"applies rules"| node_auth_domain
node_auth_service -->|"accesses profiles"| node_profile_contract
node_auth_service -->|"checks creation"| node_profile_domain
node_auth_service -->|"requests OAuth data"| node_google
node_auth_handlers -->|"creates user"| node_auth_contract
node_auth_handlers -->|"validates creation"| node_auth_domain
node_auth_handlers -.->|"publishes event"| node_registration_saga
node_profile_service -.->|"coordinates commands"| node_profile_handler
node_profile_service -.->|"uses repository"| node_profile_contract
node_auth_contract -.->|"implemented by"| node_auth_repository
node_profile_contract -.->|"implemented by"| node_profile_repository
node_auth_repository -->|"queries"| node_auth_model
node_auth_repository -.->|"persists data"| node_database
node_profile_repository -.->|"uses model"| node_profile_model
node_profile_repository -.->|"persists data"| node_database
node_entrypoint -->|"bootstraps"| node_app_module
node_app_module -->|"imports"| node_api_module
node_app_module -->|"registers globally"| node_response_pipeline
node_app_module -->|"applies to routes"| node_request_middleware
node_app_module -->|"registers controller"| node_health
node_db_providers -->|"connects"| node_database

click node_auth_controller "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/api/controllers/auth.controller.ts"
click node_profile_controller "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/api/controllers/profile.controller.ts"
click node_api_module "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/api/api.module.ts"
click node_response_service "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/services/response.service.ts"
click node_auth_service "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/services/auth.service.ts"
click node_auth_handlers "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/auth/command/handler/create-auth-user.handler.ts"
click node_registration_saga "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/auth/sagas/registration.saga.ts"
click node_auth_security "https://github.com/collatzconjecture/nestjs-clean-architecture/tree/main/src/application/auth"
click node_profile_service "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/services/profile.service.ts"
click node_profile_handler "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/profile/command/handler/create-profile.handler.ts"
click node_request_middleware "https://github.com/collatzconjecture/nestjs-clean-architecture/tree/main/src/application/middlewere"
click node_response_pipeline "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/interceptors/response.interceptor.ts"
click node_auth_domain "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/domain/services/auth-domain.service.ts"
click node_profile_domain "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/domain/services/profile-domain.service.ts"
click node_auth_entity "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/domain/entities/Auth.ts"
click node_profile_entity "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/domain/entities/Profile.ts"
click node_auth_contract "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/domain/interfaces/repositories/auth-repository.interface.ts"
click node_profile_contract "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/domain/interfaces/repositories/profile-repository.interface.ts"
click node_auth_repository "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/infrastructure/repository/auth.repository.ts"
click node_profile_repository "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/infrastructure/repository/profile.repository.ts"
click node_auth_model "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/infrastructure/models/auth.model.ts"
click node_profile_model "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/infrastructure/models/profile.model.ts"
click node_health "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/infrastructure/health/health.controller.ts"
click node_operations "https://github.com/collatzconjecture/nestjs-clean-architecture/tree/main/src/infrastructure"
click node_app_module "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/app.module.ts"
click node_entrypoint "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/main.ts"
click node_db_providers "https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/infrastructure/database/database.providers.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_auth_controller,node_profile_controller,node_api_module,node_client toneBlue
class node_response_service,node_auth_service,node_auth_handlers,node_registration_saga,node_auth_security,node_profile_service,node_profile_handler,node_request_middleware,node_response_pipeline,node_database toneAmber
class node_auth_domain,node_profile_domain,node_auth_entity,node_profile_entity,node_auth_contract,node_profile_contract toneMint
class node_auth_repository,node_profile_repository,node_auth_model,node_profile_model,node_health,node_operations,node_app_module,node_entrypoint,node_db_providers toneRose
class node_google toneIndigo
```

## Components

### HTTP API

- [Auth Endpoints](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/api/controllers/auth.controller.ts): `src/api/controllers/auth.controller.ts`
- [Profile Endpoints](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/api/controllers/profile.controller.ts): `src/api/controllers/profile.controller.ts`
- [API Module](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/api/api.module.ts): `src/api/api.module.ts`

### Application Workflows

- [Response Formatting](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/services/response.service.ts): `src/application/services/response.service.ts`
- [Auth Orchestration](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/services/auth.service.ts): `src/application/services/auth.service.ts`
- [Auth Commands](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/auth/command/handler/create-auth-user.handler.ts): `src/application/auth/command/handler/create-auth-user.handler.ts`
- [Registration Saga](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/auth/sagas/registration.saga.ts): `src/application/auth/sagas/registration.saga.ts`
- [Auth Strategies & RBAC](https://github.com/collatzconjecture/nestjs-clean-architecture/tree/main/src/application/auth): `src/application/auth`
- [Profile Service](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/services/profile.service.ts): `src/application/services/profile.service.ts`
- [Profile Command Handler](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/profile/command/handler/create-profile.handler.ts): `src/application/profile/command/handler/create-profile.handler.ts`
- [Request Middleware](https://github.com/collatzconjecture/nestjs-clean-architecture/tree/main/src/application/middlewere): `src/application/middlewere`
- [Response & Errors](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/application/interceptors/response.interceptor.ts): `src/application/interceptors/response.interceptor.ts`

### Domain Model

- [Auth Rules](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/domain/services/auth-domain.service.ts): `src/domain/services/auth-domain.service.ts`
- [Profile Rules](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/domain/services/profile-domain.service.ts): `src/domain/services/profile-domain.service.ts`
- [Auth Entity](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/domain/entities/Auth.ts): `src/domain/entities/Auth.ts`
- [Profile Entity](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/domain/entities/Profile.ts): `src/domain/entities/Profile.ts`
- [Auth Repository Contract](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/domain/interfaces/repositories/auth-repository.interface.ts): `src/domain/interfaces/repositories/auth-repository.interface.ts`
- [Profile Repository Contract](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/domain/interfaces/repositories/profile-repository.interface.ts): `src/domain/interfaces/repositories/profile-repository.interface.ts`

### Infrastructure

- [Auth Repository](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/infrastructure/repository/auth.repository.ts): `src/infrastructure/repository/auth.repository.ts`
- [Profile Repository](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/infrastructure/repository/profile.repository.ts): `src/infrastructure/repository/profile.repository.ts`
- [Auth Mongo Model](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/infrastructure/models/auth.model.ts): `src/infrastructure/models/auth.model.ts`
- [Profile Mongo Model](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/infrastructure/models/profile.model.ts): `src/infrastructure/models/profile.model.ts`
- [Health Checks](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/infrastructure/health/health.controller.ts): `src/infrastructure/health/health.controller.ts`
- [Logging & Metrics](https://github.com/collatzconjecture/nestjs-clean-architecture/tree/main/src/infrastructure): `src/infrastructure`
- [Root Module](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/app.module.ts): `src/app.module.ts`
- [Nest Bootstrap](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/main.ts): `src/main.ts`
- [Database Provider](https://github.com/collatzconjecture/nestjs-clean-architecture/blob/main/src/infrastructure/database/database.providers.ts): `src/infrastructure/database/database.providers.ts`

### Other components

- **API Client**
- **MongoDB**
- **Google OAuth**

## Connections

- API Client → Auth Endpoints: sends requests (evidence: `src/api/controllers/auth.controller.ts`)
- API Client → Profile Endpoints: sends requests (evidence: `src/api/controllers/profile.controller.ts`)
- Auth Endpoints → Auth Orchestration: calls (evidence: `src/api/controllers/auth.controller.ts`)
- Profile Endpoints → Profile Service: calls (evidence: `src/api/controllers/profile.controller.ts`)
- Auth Endpoints → Response Formatting: formats results (evidence: `src/api/controllers/auth.controller.ts`)
- Profile Endpoints → Response Formatting: formats results (evidence: `src/api/controllers/profile.controller.ts`)
- Auth Orchestration → Auth Commands: dispatches commands (evidence: `src/application/services/auth.service.ts`)
- Auth Orchestration → Auth Repository Contract: reads and writes (evidence: `src/application/services/auth.service.ts`)
- Auth Orchestration → Auth Rules: applies rules (evidence: `src/application/services/auth.service.ts`)
- Auth Orchestration → Profile Repository Contract: accesses profiles (evidence: `src/application/services/auth.service.ts`)
- Auth Orchestration → Profile Rules: checks creation (evidence: `src/application/services/auth.service.ts`)
- Auth Orchestration → Google OAuth: requests OAuth data (evidence: `src/application/services/auth.service.ts`)
- Auth Commands → Auth Repository Contract: creates user (evidence: `src/application/auth/command/handler/create-auth-user.handler.ts`)
- Auth Commands → Auth Rules: validates creation (evidence: `src/application/auth/command/handler/create-auth-user.handler.ts`)
- Auth Commands → Registration Saga: publishes event
- Profile Service → Profile Command Handler: coordinates commands
- Profile Service → Profile Repository Contract: uses repository
- Auth Repository Contract → Auth Repository: implemented by
- Profile Repository Contract → Profile Repository: implemented by
- Auth Repository → Auth Mongo Model: queries (evidence: `src/infrastructure/repository/auth.repository.ts`)
- Auth Repository → MongoDB: persists data
- Profile Repository → Profile Mongo Model: uses model
- Profile Repository → MongoDB: persists data
- Nest Bootstrap → Root Module: bootstraps (evidence: `src/main.ts`)
- Root Module → API Module: imports (evidence: `src/app.module.ts`)
- Root Module → Response & Errors: registers globally (evidence: `src/app.module.ts`)
- Root Module → Request Middleware: applies to routes (evidence: `src/app.module.ts`)
- Root Module → Health Checks: registers controller (evidence: `src/app.module.ts`)
- Database Provider → MongoDB: connects (evidence: `src/infrastructure/database/database.providers.ts`)
