# brocoders/nestjs-boilerplate architecture

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

- Interactive diagram: https://gitdiagram.com/brocoders/nestjs-boilerplate
- Repository: https://github.com/brocoders/nestjs-boilerplate

## Overview

This repository is a NestJS REST API boilerplate. Its main workflow accepts email or social sign-in, validates credentials or provider identity, then uses user and session services to issue JWT and refresh-token responses; registration and account confirmation also use mailing. Admin user endpoints provide a separate management path. The README documents dual database backends, seeding, roles, translations, and local/S3 uploads. The graph preserves those capabilities, but the source excerpts do not expose every implementation or all runtime wiring, so some documented subsystem links are dashed and unverified.

Main entry points: [`src/app.module.ts`](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/app.module.ts) (Nest application), [`src/auth/auth.service.ts`](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth/auth.service.ts) (Auth workflow), [`src/files/files.service.ts`](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/files/files.service.ts) (File management), [`src/auth-google/auth-google.controller.ts`](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth-google/auth-google.controller.ts) (Social endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_app["Nest application<br/>[app.module.ts]"]
  node_config["Configuration<br/>[config.type.ts]"]
  node_i18n["Translations<br/>[app.module.ts]"]
end

subgraph group_identity["Identity and access"]
  node_authapi["Auth endpoints<br/>[auth.controller.ts]"]
  node_auth["Auth workflow<br/>[auth.service.ts]"]
  node_socialapi["Social endpoints"]
  node_apple["Apple identity"]
  node_facebook["Facebook identity"]
  node_google["Google identity"]
  node_jwt["JWT strategies<br/>[jwt.strategy.ts]"]
  node_roles["Role authorization<br/>[roles.guard.ts]"]
end

subgraph group_accounts["Accounts and persistence"]
  node_usersapi["User endpoints"]
  node_users["User service<br/>[users.service.ts]"]
  node_userstore[("User persistence<br/>[user.repository.ts]")]
  node_sessions["Session service<br/>[session.service.ts]"]
  node_sessionstore[("Session persistence")]
  node_database[("Database adapters")]
  node_seeds["Database seeding"]
end

subgraph group_capabilities["Product capabilities"]
  node_mail["Mail workflows<br/>[mail.service.ts]"]
  node_mailer["Mailer transport<br/>[mailer.service.ts]"]
  node_files["File management<br/>[files.service.ts]"]
  node_localupload["Local uploads<br/>[files.service.ts]"]
  node_s3upload["S3 uploads<br/>[files.service.ts]"]
  node_presigned["Presigned uploads<br/>[files.service.ts]"]
  node_filestore[("File persistence<br/>[file.repository.ts]")]
end

node_client(("API clients"))
node_external_social(("Social providers"))
node_external_mail(("Mail transport"))
node_external_storage(("S3 storage"))

node_client -->|"sends requests"| node_app
node_app -->|"loads settings"| node_config
node_app -->|"configures translations"| node_i18n
node_app -->|"registers"| node_authapi
node_app -->|"registers"| node_usersapi
node_authapi -->|"delegates"| node_auth
node_authapi -.->|"refreshes sessions"| node_sessions
node_auth -->|"looks up users"| node_users
node_auth -->|"creates sessions"| node_sessions
node_auth -->|"sends account mail"| node_mail
node_auth -.->|"issues tokens"| node_jwt
node_socialapi -->|"verifies identity"| node_google
node_socialapi -->|"starts sign-in"| node_auth
node_socialapi -.->|"routes Apple login"| node_apple
node_socialapi -.->|"routes Facebook login"| node_facebook
node_google -.->|"verifies token"| node_external_social
node_facebook -->|"requests profile"| node_external_social
node_usersapi -->|"delegates"| node_users
node_usersapi -->|"checks access"| node_roles
node_users -->|"reads and writes"| node_userstore
node_users -->|"uses file service"| node_files
node_sessions -->|"delegates persistence"| node_sessionstore
node_app -->|"selects backend"| node_database
node_app -.->|"provides seeding"| node_seeds
node_mail -->|"sends mail"| node_mailer
node_mailer -.->|"delivers messages"| node_external_mail
node_files -.->|"uses persistence"| node_filestore
node_files -.->|"supports local driver"| node_localupload
node_files -.->|"supports S3 driver"| node_s3upload
node_files -.->|"offers presigned uploads"| node_presigned
node_s3upload -.->|"stores objects"| node_external_storage
node_presigned -.->|"uses signed access"| node_external_storage

click node_app "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/app.module.ts"
click node_config "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/config/config.type.ts"
click node_i18n "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/app.module.ts"
click node_authapi "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth/auth.controller.ts"
click node_auth "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth/auth.service.ts"
click node_socialapi "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth-google/auth-google.controller.ts"
click node_apple "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth-apple/auth-apple.service.ts"
click node_facebook "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth-facebook/auth-facebook.service.ts"
click node_google "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth-google/auth-google.service.ts"
click node_jwt "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth/strategies/jwt.strategy.ts"
click node_roles "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/roles/roles.guard.ts"
click node_usersapi "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/users/users.controller.ts"
click node_users "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/users/users.service.ts"
click node_userstore "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/users/infrastructure/persistence/user.repository.ts"
click node_sessions "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/session/session.service.ts"
click node_sessionstore "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/session/infrastructure/persistence/session.repository.ts"
click node_database "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/database/typeorm-config.service.ts"
click node_seeds "https://github.com/brocoders/nestjs-boilerplate/tree/main/src/database/seeds"
click node_mail "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/mail/mail.service.ts"
click node_mailer "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/mailer/mailer.service.ts"
click node_files "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/files/files.service.ts"
click node_localupload "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/files/infrastructure/uploader/local/files.service.ts"
click node_s3upload "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/files/infrastructure/uploader/s3/files.service.ts"
click node_presigned "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/files/infrastructure/uploader/s3-presigned/files.service.ts"
click node_filestore "https://github.com/brocoders/nestjs-boilerplate/blob/main/src/files/infrastructure/persistence/file.repository.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,node_config,node_i18n,node_client toneBlue
class node_authapi,node_auth,node_socialapi,node_apple,node_facebook,node_google,node_jwt,node_roles,node_external_storage toneAmber
class node_usersapi,node_users,node_userstore,node_sessions,node_sessionstore,node_database,node_seeds toneMint
class node_mail,node_mailer,node_files,node_localupload,node_s3upload,node_presigned,node_filestore toneRose
class node_external_social,node_external_mail toneIndigo
```

## Components

### Application runtime

- [Nest application](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/app.module.ts): `src/app.module.ts`
- [Configuration](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/config/config.type.ts): `src/config/config.type.ts`
- [Translations](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/app.module.ts): `src/app.module.ts`

### Identity and access

- [Auth endpoints](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth/auth.controller.ts): `src/auth/auth.controller.ts`
- [Auth workflow](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth/auth.service.ts): `src/auth/auth.service.ts`
- [Social endpoints](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth-google/auth-google.controller.ts): `src/auth-google/auth-google.controller.ts`
- [Apple identity](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth-apple/auth-apple.service.ts): `src/auth-apple/auth-apple.service.ts`
- [Facebook identity](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth-facebook/auth-facebook.service.ts): `src/auth-facebook/auth-facebook.service.ts`
- [Google identity](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth-google/auth-google.service.ts): `src/auth-google/auth-google.service.ts`
- [JWT strategies](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/auth/strategies/jwt.strategy.ts): `src/auth/strategies/jwt.strategy.ts`
- [Role authorization](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/roles/roles.guard.ts): `src/roles/roles.guard.ts`

### Accounts and persistence

- [User endpoints](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/users/users.controller.ts): `src/users/users.controller.ts`
- [User service](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/users/users.service.ts): `src/users/users.service.ts`
- [User persistence](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/users/infrastructure/persistence/user.repository.ts): `src/users/infrastructure/persistence/user.repository.ts`
- [Session service](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/session/session.service.ts): `src/session/session.service.ts`
- [Session persistence](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/session/infrastructure/persistence/session.repository.ts): `src/session/infrastructure/persistence/session.repository.ts`
- [Database adapters](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/database/typeorm-config.service.ts): `src/database/typeorm-config.service.ts`
- [Database seeding](https://github.com/brocoders/nestjs-boilerplate/tree/main/src/database/seeds): `src/database/seeds`

### Product capabilities

- [Mail workflows](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/mail/mail.service.ts): `src/mail/mail.service.ts`
- [Mailer transport](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/mailer/mailer.service.ts): `src/mailer/mailer.service.ts`
- [File management](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/files/files.service.ts): `src/files/files.service.ts`
- [Local uploads](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/files/infrastructure/uploader/local/files.service.ts): `src/files/infrastructure/uploader/local/files.service.ts`
- [S3 uploads](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/files/infrastructure/uploader/s3/files.service.ts): `src/files/infrastructure/uploader/s3/files.service.ts`
- [Presigned uploads](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/files/infrastructure/uploader/s3-presigned/files.service.ts): `src/files/infrastructure/uploader/s3-presigned/files.service.ts`
- [File persistence](https://github.com/brocoders/nestjs-boilerplate/blob/main/src/files/infrastructure/persistence/file.repository.ts): `src/files/infrastructure/persistence/file.repository.ts`

### Other components

- **API clients**
- **Social providers**
- **Mail transport**
- **S3 storage**

## Connections

- API clients → Nest application: sends requests
- Nest application → Configuration: loads settings (evidence: `src/app.module.ts`)
- Nest application → Translations: configures translations (evidence: `src/app.module.ts`)
- Nest application → Auth endpoints: registers (evidence: `src/app.module.ts`)
- Nest application → User endpoints: registers (evidence: `src/app.module.ts`)
- Auth endpoints → Auth workflow: delegates (evidence: `src/auth/auth.controller.ts`)
- Auth endpoints → Session service: refreshes sessions
- Auth workflow → User service: looks up users (evidence: `src/auth/auth.service.ts`)
- Auth workflow → Session service: creates sessions (evidence: `src/auth/auth.service.ts`)
- Auth workflow → Mail workflows: sends account mail (evidence: `src/auth/auth.service.ts`)
- Auth workflow → JWT strategies: issues tokens
- Social endpoints → Google identity: verifies identity (evidence: `src/auth-google/auth-google.controller.ts`)
- Social endpoints → Auth workflow: starts sign-in (evidence: `src/auth-google/auth-google.controller.ts`)
- Social endpoints → Apple identity: routes Apple login
- Social endpoints → Facebook identity: routes Facebook login
- Google identity → Social providers: verifies token
- Facebook identity → Social providers: requests profile (evidence: `src/auth-facebook/auth-facebook.service.ts`)
- User endpoints → User service: delegates (evidence: `src/users/users.controller.ts`)
- User endpoints → Role authorization: checks access (evidence: `src/users/users.controller.ts`)
- User service → User persistence: reads and writes (evidence: `src/users/users.service.ts`)
- User service → File management: uses file service (evidence: `src/users/users.service.ts`)
- Session service → Session persistence: delegates persistence (evidence: `src/session/session.service.ts`)
- Nest application → Database adapters: selects backend (evidence: `src/app.module.ts`)
- Nest application → Database seeding: provides seeding (evidence: `README.md`)
- Mail workflows → Mailer transport: sends mail (evidence: `src/mail/mail.service.ts`)
- Mailer transport → Mail transport: delivers messages
- File management → File persistence: uses persistence
- File management → Local uploads: supports local driver (evidence: `README.md`)
- File management → S3 uploads: supports S3 driver (evidence: `README.md`)
- File management → Presigned uploads: offers presigned uploads
- S3 uploads → S3 storage: stores objects (evidence: `README.md`)
- Presigned uploads → S3 storage: uses signed access
