# sagarsishir51/nestjs-hexagonal-architecture-demo-project architecture

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

- Interactive diagram: https://gitdiagram.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project
- Repository: https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project

## Overview

This is a NestJS hexagonal-architecture API for authentication and user, role, and privilege management, with file upload support. The main workflow is an API request through a controller and use case, with persistence adapters backed by TypeORM; the sampled user controller and module show the controller and dependency wiring, but use-case/repository internals were not sampled. The README also documents database seeding, migrations, and Swagger. Dashed edges mark documented or likely relationships whose implementation wiring is not visible in the excerpts.

Main entry points: [`src/modules/user/user.module.ts`](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/modules/user/user.module.ts) (User module wiring), [`src/app.module.ts`](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/app.module.ts) (Nest app setup), [`src/frameworks/primary/controllers/user/user.controller.ts`](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/controllers/user/user.controller.ts) (User API), [`src/frameworks/primary/controllers/role/role.controller.ts`](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/controllers/role/role.controller.ts) (Role API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and security"]
  node_user_api["User API<br/>[user.controller.ts]"]
  node_role_api["Role API<br/>[role.controller.ts]"]
  node_priv_api["Privilege API"]
  node_auth_api["Auth API<br/>[auth.controller.ts]"]
  node_upload_api["Upload API"]
  node_security["Request security<br/>[privilege.guard.ts]"]
  node_jwt["JWT strategy<br/>[jwt.strategy.ts]"]
end

subgraph group_domain["Application and domain"]
  node_user_uc["User use case<br/>[user.usecase.ts]"]
  node_role_uc["Role use case<br/>[role.usecase.ts]"]
  node_priv_uc["Privilege use case"]
  node_auth_uc["Auth use case<br/>[auth.usecase.ts]"]
  node_user_domain["User domain<br/>[user.domain.ts]"]
  node_role_domain["Role domain<br/>[role.domain.ts]"]
  node_priv_domain["Privilege domain"]
end

subgraph group_persistence["Persistence"]
  node_user_repo["User repository<br/>[user.repository.ts]"]
  node_role_repo["Role repository<br/>[role.repository.ts]"]
  node_priv_repo["Privilege repository"]
  node_user_entity[("User entity<br/>[user.entity.ts]")]
  node_role_entity[("Role entity<br/>[role.entity.ts]")]
  node_priv_entity[("Privilege entity")]
  node_seed["Seed data"]
end

subgraph group_runtime["Runtime and integrations"]
  node_app["Nest app setup<br/>[app.module.ts]"]
  node_user_module["User module wiring<br/>[user.module.ts]"]
  node_auth_module["Auth module<br/>[auth.module.ts]"]
  node_upload_module["Upload module<br/>[upload.module.ts]"]
  node_typeorm["TypeORM configuration<br/>[typeorm.service.ts]"]
  node_upload_store["Upload storage<br/>[upload.ts]"]
end

node_client(("API client"))
node_db[("Relational database")]

node_client -->|"requests"| node_user_api
node_client -->|"requests"| node_role_api
node_client -->|"requests"| node_priv_api
node_client -->|"requests"| node_auth_api
node_client -.->|"requests"| node_upload_api
node_user_api -->|"invokes"| node_user_uc
node_role_api -->|"invokes"| node_role_uc
node_priv_api -->|"invokes"| node_priv_uc
node_auth_api -->|"invokes"| node_auth_uc
node_user_api -->|"constructs"| node_user_domain
node_role_api -->|"constructs"| node_role_domain
node_user_api -.->|"requires privilege"| node_security
node_role_api -.->|"requires privilege"| node_security
node_priv_api -.->|"requires privilege"| node_security
node_app -->|"loads"| node_user_module
node_app -->|"loads"| node_auth_module
node_app -->|"loads"| node_upload_module
node_app -->|"configures"| node_typeorm
node_app -->|"registers guard"| node_security
node_auth_module -->|"imports"| node_user_module
node_user_module -->|"registers"| node_user_api
node_user_module -->|"registers"| node_role_api
node_user_module -->|"registers"| node_priv_api
node_user_module -->|"binds"| node_user_uc
node_user_module -->|"binds"| node_role_uc
node_user_module -->|"binds"| node_priv_uc
node_user_module -->|"binds"| node_user_repo
node_user_module -->|"binds"| node_role_repo
node_user_module -->|"binds"| node_priv_repo
node_user_module -->|"registers"| node_user_entity
node_user_module -->|"registers"| node_role_entity
node_user_module -->|"registers"| node_priv_entity
node_user_repo -->|"uses"| node_user_entity
node_role_repo -->|"uses"| node_role_entity
node_priv_repo -->|"uses"| node_priv_entity
node_role_entity -->|"relates"| node_priv_entity
node_user_entity -->|"relates"| node_role_entity
node_typeorm -.->|"connects"| node_db
node_user_repo -.->|"implements port"| node_user_uc
node_role_repo -.->|"implements port"| node_role_uc
node_priv_repo -.->|"implements port"| node_priv_uc
node_auth_api -.->|"authenticates via"| node_jwt
node_upload_api -.->|"stores files"| node_upload_store
node_seed -.->|"populates"| node_db

click node_app "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/app.module.ts"
click node_user_api "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/controllers/user/user.controller.ts"
click node_role_api "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/controllers/role/role.controller.ts"
click node_priv_api "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/controllers/privilege/privilege.controller.ts"
click node_auth_api "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/controllers/auth/auth.controller.ts"
click node_upload_api "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/controllers/upload/upload.controller.ts"
click node_security "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/guards/privilege.guard.ts"
click node_jwt "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/strategies/jwt.strategy.ts"
click node_user_uc "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/core/application/usecases/user/user.usecase.ts"
click node_role_uc "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/core/application/usecases/role/role.usecase.ts"
click node_priv_uc "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/core/application/usecases/privilege/privilege.usecase.ts"
click node_auth_uc "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/core/application/usecases/auth/auth.usecase.ts"
click node_user_domain "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/core/domain/user/user.domain.ts"
click node_role_domain "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/core/domain/role/role.domain.ts"
click node_priv_domain "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/core/domain/privilege/privilege.domain.ts"
click node_user_module "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/modules/user/user.module.ts"
click node_auth_module "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/modules/auth/auth.module.ts"
click node_upload_module "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/modules/upload/upload.module.ts"
click node_user_repo "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/secondary/user/user.repository.ts"
click node_role_repo "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/secondary/role/role.repository.ts"
click node_priv_repo "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/secondary/privilege/privilege.repository.ts"
click node_user_entity "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/secondary/user/user.entity.ts"
click node_role_entity "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/secondary/role/role.entity.ts"
click node_priv_entity "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/secondary/privilege/privilege.entity.ts"
click node_typeorm "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/infrastructure/database/typeorm.service.ts"
click node_seed "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/seeders/privilege.seeder.ts"
click node_upload_store "https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/utils/upload.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_user_api,node_role_api,node_priv_api,node_auth_api,node_upload_api,node_security,node_jwt,node_client toneBlue
class node_user_uc,node_role_uc,node_priv_uc,node_auth_uc,node_user_domain,node_role_domain,node_priv_domain,node_db toneAmber
class node_user_repo,node_role_repo,node_priv_repo,node_user_entity,node_role_entity,node_priv_entity,node_seed toneMint
class node_app,node_user_module,node_auth_module,node_upload_module,node_typeorm,node_upload_store toneRose
```

## Components

### API and security

- [User API](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/controllers/user/user.controller.ts): `src/frameworks/primary/controllers/user/user.controller.ts`
- [Role API](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/controllers/role/role.controller.ts): `src/frameworks/primary/controllers/role/role.controller.ts`
- [Privilege API](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/controllers/privilege/privilege.controller.ts): `src/frameworks/primary/controllers/privilege/privilege.controller.ts`
- [Auth API](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/controllers/auth/auth.controller.ts): `src/frameworks/primary/controllers/auth/auth.controller.ts`
- [Upload API](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/controllers/upload/upload.controller.ts): `src/frameworks/primary/controllers/upload/upload.controller.ts`
- [Request security](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/guards/privilege.guard.ts): `src/frameworks/primary/guards/privilege.guard.ts`
- [JWT strategy](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/primary/strategies/jwt.strategy.ts): `src/frameworks/primary/strategies/jwt.strategy.ts`

### Application and domain

- [User use case](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/core/application/usecases/user/user.usecase.ts): `src/core/application/usecases/user/user.usecase.ts`
- [Role use case](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/core/application/usecases/role/role.usecase.ts): `src/core/application/usecases/role/role.usecase.ts`
- [Privilege use case](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/core/application/usecases/privilege/privilege.usecase.ts): `src/core/application/usecases/privilege/privilege.usecase.ts`
- [Auth use case](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/core/application/usecases/auth/auth.usecase.ts): `src/core/application/usecases/auth/auth.usecase.ts`
- [User domain](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/core/domain/user/user.domain.ts): `src/core/domain/user/user.domain.ts`
- [Role domain](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/core/domain/role/role.domain.ts): `src/core/domain/role/role.domain.ts`
- [Privilege domain](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/core/domain/privilege/privilege.domain.ts): `src/core/domain/privilege/privilege.domain.ts`

### Persistence

- [User repository](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/secondary/user/user.repository.ts): `src/frameworks/secondary/user/user.repository.ts`
- [Role repository](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/secondary/role/role.repository.ts): `src/frameworks/secondary/role/role.repository.ts`
- [Privilege repository](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/secondary/privilege/privilege.repository.ts): `src/frameworks/secondary/privilege/privilege.repository.ts`
- [User entity](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/secondary/user/user.entity.ts): `src/frameworks/secondary/user/user.entity.ts`
- [Role entity](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/secondary/role/role.entity.ts): `src/frameworks/secondary/role/role.entity.ts`
- [Privilege entity](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/frameworks/secondary/privilege/privilege.entity.ts): `src/frameworks/secondary/privilege/privilege.entity.ts`
- [Seed data](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/seeders/privilege.seeder.ts): `src/seeders/privilege.seeder.ts`

### Runtime and integrations

- [Nest app setup](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/app.module.ts): `src/app.module.ts`
- [User module wiring](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/modules/user/user.module.ts): `src/modules/user/user.module.ts`
- [Auth module](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/modules/auth/auth.module.ts): `src/modules/auth/auth.module.ts`
- [Upload module](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/modules/upload/upload.module.ts): `src/modules/upload/upload.module.ts`
- [TypeORM configuration](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/infrastructure/database/typeorm.service.ts): `src/infrastructure/database/typeorm.service.ts`
- [Upload storage](https://github.com/sagarsishir51/nestjs-hexagonal-architecture-demo-project/blob/main/src/utils/upload.ts): `src/utils/upload.ts`

### Other components

- **API client**
- **Relational database**

## Connections

- API client → User API: requests (evidence: `src/frameworks/primary/controllers/user/user.controller.ts`)
- API client → Role API: requests (evidence: `src/frameworks/primary/controllers/role/role.controller.ts`)
- API client → Privilege API: requests (evidence: `src/frameworks/primary/controllers/privilege/privilege.controller.ts`)
- API client → Auth API: requests (evidence: `src/frameworks/primary/controllers/auth/auth.controller.ts`)
- API client → Upload API: requests
- User API → User use case: invokes (evidence: `src/frameworks/primary/controllers/user/user.controller.ts`)
- Role API → Role use case: invokes (evidence: `src/frameworks/primary/controllers/role/role.controller.ts`)
- Privilege API → Privilege use case: invokes (evidence: `src/frameworks/primary/controllers/privilege/privilege.controller.ts`)
- Auth API → Auth use case: invokes (evidence: `src/frameworks/primary/controllers/auth/auth.controller.ts`)
- User API → User domain: constructs (evidence: `src/frameworks/primary/controllers/user/user.controller.ts`)
- Role API → Role domain: constructs (evidence: `src/frameworks/primary/controllers/role/role.controller.ts`)
- User API → Request security: requires privilege
- Role API → Request security: requires privilege
- Privilege API → Request security: requires privilege
- Nest app setup → User module wiring: loads (evidence: `src/app.module.ts`)
- Nest app setup → Auth module: loads (evidence: `src/app.module.ts`)
- Nest app setup → Upload module: loads (evidence: `src/app.module.ts`)
- Nest app setup → TypeORM configuration: configures (evidence: `src/app.module.ts`)
- Nest app setup → Request security: registers guard (evidence: `src/app.module.ts`)
- Auth module → User module wiring: imports (evidence: `src/modules/auth/auth.module.ts`)
- User module wiring → User API: registers (evidence: `src/modules/user/user.module.ts`)
- User module wiring → Role API: registers (evidence: `src/modules/user/user.module.ts`)
- User module wiring → Privilege API: registers (evidence: `src/modules/user/user.module.ts`)
- User module wiring → User use case: binds (evidence: `src/modules/user/user.module.ts`)
- User module wiring → Role use case: binds (evidence: `src/modules/user/user.module.ts`)
- User module wiring → Privilege use case: binds (evidence: `src/modules/user/user.module.ts`)
- User module wiring → User repository: binds (evidence: `src/modules/user/user.module.ts`)
- User module wiring → Role repository: binds (evidence: `src/modules/user/user.module.ts`)
- User module wiring → Privilege repository: binds (evidence: `src/modules/user/user.module.ts`)
- User module wiring → User entity: registers (evidence: `src/modules/user/user.module.ts`)
- User module wiring → Role entity: registers (evidence: `src/modules/user/user.module.ts`)
- User module wiring → Privilege entity: registers (evidence: `src/modules/user/user.module.ts`)
- User repository → User entity: uses (evidence: `src/frameworks/secondary/user/user.repository.ts`)
- Role repository → Role entity: uses (evidence: `src/frameworks/secondary/role/role.repository.ts`)
- Privilege repository → Privilege entity: uses (evidence: `src/frameworks/secondary/privilege/privilege.repository.ts`)
- Role entity → Privilege entity: relates (evidence: `src/frameworks/secondary/role/role.entity.ts`)
- User entity → Role entity: relates (evidence: `src/frameworks/secondary/user/user.entity.ts`)
- TypeORM configuration → Relational database: connects
- User repository → User use case: implements port
- Role repository → Role use case: implements port
- Privilege repository → Privilege use case: implements port
- Auth API → JWT strategy: authenticates via
- Upload API → Upload storage: stores files
- Seed data → Relational database: populates
