# bashleigh/nestjs-blog architecture

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

- Interactive diagram: https://gitdiagram.com/bashleigh/nestjs-blog
- Repository: https://github.com/bashleigh/nestjs-blog

## Overview

1. **System shape**
   - This repo is a **single NestJS backend application** for a basic blog API.
   - It is organized as a modular monolith with three main feature areas: **auth**, **user**, and **blog**.

2. **Runtime and deployment model**
   - The application runs on **Node.js/NestJS**.
   - In development it uses **nodemon / HMR** (`main.hmr.ts`, `nodemon.json`, `webpack.config.js`) for reloads.
   - In production it is intended to run from the compiled `dist` output.
   - The backing datastore is **MySQL**, started locally via `docker-compose.yml`.

3. **Composition root**
   - `src/app.module.ts` is the top-level wiring point.
   - It aggregates the feature modules and config/database setup, so the architecture is centered around Nest’s dependency injection and module boundaries.

4. **Auth subsystem**
   - `src/auth` contains the authentication boundary:
     - `auth.controller.ts` exposes auth endpoints.
     - `auth.service.ts` contains the login/token logic.
     - `jwt.strategy.ts` integrates JWT validation with Nest/Passport.
     - `interfaces/jwt-payload.interface.ts` defines token payload shape.
   - This module is the security gate for protected routes.

5. **User subsystem**
   - `src/user` is the user-domain module with controller and service layers.
   - It likely supports user creation/retrieval and is used both directly and indirectly by auth.
   - The user service is a distinct domain service, not just an auth helper, which keeps identity data separate from token handling.

6. **Blog subsystem**
   - `src/blog` is the core content module.
   - `blog.controller.ts` handles blog endpoints.
   - `blog.service.ts` contains blog business logic.
   - `slug.provider.ts` is a dedicated helper for generating URL-friendly slugs, showing that slug creation is treated as domain logic rather than a controller concern.
   - `src/config/slugify.ts` and the slug provider together suggest titles are normalized into stable blog identifiers.

7. **Persistence layer**
   - `src/entities` contains the TypeORM persistence model:
     - `base.entity.ts` for shared entity fields
     - `user.entity.ts`
     - `blog.entity.ts`
   - These entities are the bridge between Nest services and MySQL through TypeORM.
   - The data flow is therefore: **controller → service → TypeORM entity/repository → MySQL**.

8. **API/data contract layer**
   - `src/models` holds API-facing shapes for auth, blog, and user payloads.
   - This separation indicates the repo distinguishes between **database entities** and **response/request models**, which helps keep external API contracts decoupled from persistence details.

9. **Shared utilities**
   - `src/paginate` provides reusable pagination interfaces and helpers.
   - This is a cross-cutting concern used by listing endpoints, most likely blog and user queries.
   - It acts as a small shared infrastructure layer inside the app.

10. **Configuration boundaries**
   - `src/config/database.ts` configures TypeORM/MySQL connectivity.
   - `src/config/jwt.ts` holds JWT settings.
   - `src/config/slugify.ts` centralizes slug formatting behavior.
   - `.env.dist` implies runtime behavior is environment-driven, with config values injected rather than hardcoded.

11. **Testing structure**
   - Unit tests live beside services/providers as `*.spec.ts`.
   - End-to-end coverage lives under `test/` with `app.e2e-spec.ts`.
   - This shows the repo validates both isolated domain logic and full HTTP/module wiring.

12. **Architecture summary for a diagram**
   - The clean diagram is: **HTTP clients → Nest controllers → domain services → TypeORM entities/repositories → MySQL**.
   - Cross-cutting concerns sit alongside that path: **JWT auth/strategy** protects endpoints, **slug generation** supports blog creation, and **pagination** supports list responses.
   - The app is a conventional NestJS layered backend with clear separation between API, domain logic, and persistence.

Main entry points: [`src/app.module.ts`](https://github.com/bashleigh/nestjs-blog/blob/master/src/app.module.ts) (App module), [`src/entities/index.ts`](https://github.com/bashleigh/nestjs-blog/blob/master/src/entities/index.ts) (Entities), [`src/auth/auth.module.ts`](https://github.com/bashleigh/nestjs-blog/blob/master/src/auth/auth.module.ts) (Auth module), [`src/blog/blog.module.ts`](https://github.com/bashleigh/nestjs-blog/blob/master/src/blog/blog.module.ts) (Blog module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entrypoints"]
  node_main["App bootstrap<br/>Nest bootstrap<br/>[main.ts]"]
  node_main_hmr["HMR bootstrap<br/>Nest HMR<br/>[main.hmr.ts]"]
  node_app_module["App module<br/>Composition root<br/>[app.module.ts]"]
end

subgraph group_features["Feature modules"]
  node_auth_module["Auth module<br/>Security module<br/>[auth.module.ts]"]
  node_auth_controller["Auth API<br/>Controller<br/>[auth.controller.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
  node_jwt_strategy["JWT strategy<br/>Passport strategy<br/>[jwt.strategy.ts]"]
  node_user_module["User module<br/>Identity module<br/>[user.module.ts]"]
  node_user_controller["User API<br/>Controller<br/>[user.controller.ts]"]
  node_user_service["User service<br/>[user.service.ts]"]
  node_blog_module["Blog module<br/>Content module<br/>[blog.module.ts]"]
  node_blog_controller["Blog API<br/>Controller<br/>[blog.controller.ts]"]
  node_blog_service["Blog service<br/>[blog.service.ts]"]
  node_slug_provider["Slug helper<br/>Provider<br/>[slug.provider.ts]"]
end

subgraph group_shared["Shared layer"]
  node_database_config["Database config<br/>TypeORM config<br/>[database.ts]"]
  node_jwt_config["JWT config<br/>[jwt.ts]"]
  node_slugify_config["Slug config<br/>[slugify.ts]"]
  node_models["API models<br/>DTO models<br/>[index.ts]"]
  node_paginate["Pagination<br/>Shared helper<br/>[pagination.ts]"]
end

subgraph group_persistence["Persistence"]
  node_entities[("Entities<br/>TypeORM models<br/>[index.ts]")]
  node_user_entity[("User entity<br/>[user.entity.ts]")]
  node_blog_entity[("Blog entity<br/>[blog.entity.ts]")]
  node_base_entity[("Base entity<br/>Entity base<br/>[base.entity.ts]")]
end

subgraph group_infra["Runtime infra"]
  node_mysql[("MySQL<br/>Database<br/>[docker-compose.yml]")]
  node_webpack["Webpack HMR<br/>Dev build<br/>[webpack.config.js]"]
end

node_main -->|"boots"| node_app_module
node_main_hmr -->|"uses"| node_webpack
node_main_hmr -->|"boots"| node_app_module
node_app_module -->|"imports"| node_auth_module
node_app_module -->|"imports"| node_user_module
node_app_module -->|"imports"| node_blog_module
node_app_module -->|"configures"| node_database_config
node_app_module -->|"configures"| node_jwt_config
node_auth_module -->|"contains"| node_auth_controller
node_auth_module -->|"provides"| node_auth_service
node_auth_module -->|"uses"| node_jwt_strategy
node_auth_service -->|"reads users"| node_user_service
node_auth_service -.->|"returns"| node_models
node_jwt_strategy -->|"reads"| node_jwt_config
node_user_module -->|"contains"| node_user_controller
node_user_module -->|"provides"| node_user_service
node_user_service -->|"persists via"| node_entities
node_blog_module -->|"contains"| node_blog_controller
node_blog_module -->|"provides"| node_blog_service
node_blog_module -->|"uses"| node_slug_provider
node_blog_service -->|"persists via"| node_entities
node_blog_service -->|"lists with"| node_paginate
node_slug_provider -->|"reads"| node_slugify_config
node_entities -->|"extends"| node_base_entity
node_entities -->|"includes"| node_user_entity
node_entities -->|"includes"| node_blog_entity
node_entities -->|"stored in"| node_mysql
node_models -.->|"shapes"| node_auth_module
node_models -.->|"shapes"| node_user_module
node_models -.->|"shapes"| node_blog_module

click node_main "https://github.com/bashleigh/nestjs-blog/blob/master/src/main.ts"
click node_main_hmr "https://github.com/bashleigh/nestjs-blog/blob/master/src/main.hmr.ts"
click node_app_module "https://github.com/bashleigh/nestjs-blog/blob/master/src/app.module.ts"
click node_auth_module "https://github.com/bashleigh/nestjs-blog/blob/master/src/auth/auth.module.ts"
click node_auth_controller "https://github.com/bashleigh/nestjs-blog/blob/master/src/auth/auth.controller.ts"
click node_auth_service "https://github.com/bashleigh/nestjs-blog/blob/master/src/auth/auth.service.ts"
click node_jwt_strategy "https://github.com/bashleigh/nestjs-blog/blob/master/src/auth/jwt.strategy.ts"
click node_user_module "https://github.com/bashleigh/nestjs-blog/blob/master/src/user/user.module.ts"
click node_user_controller "https://github.com/bashleigh/nestjs-blog/blob/master/src/user/user.controller.ts"
click node_user_service "https://github.com/bashleigh/nestjs-blog/blob/master/src/user/user.service.ts"
click node_blog_module "https://github.com/bashleigh/nestjs-blog/blob/master/src/blog/blog.module.ts"
click node_blog_controller "https://github.com/bashleigh/nestjs-blog/blob/master/src/blog/blog.controller.ts"
click node_blog_service "https://github.com/bashleigh/nestjs-blog/blob/master/src/blog/blog.service.ts"
click node_slug_provider "https://github.com/bashleigh/nestjs-blog/blob/master/src/blog/slug.provider.ts"
click node_database_config "https://github.com/bashleigh/nestjs-blog/blob/master/src/config/database.ts"
click node_jwt_config "https://github.com/bashleigh/nestjs-blog/blob/master/src/config/jwt.ts"
click node_slugify_config "https://github.com/bashleigh/nestjs-blog/blob/master/src/config/slugify.ts"
click node_models "https://github.com/bashleigh/nestjs-blog/blob/master/src/models/index.ts"
click node_paginate "https://github.com/bashleigh/nestjs-blog/blob/master/src/paginate/pagination.ts"
click node_entities "https://github.com/bashleigh/nestjs-blog/blob/master/src/entities/index.ts"
click node_user_entity "https://github.com/bashleigh/nestjs-blog/blob/master/src/entities/user.entity.ts"
click node_blog_entity "https://github.com/bashleigh/nestjs-blog/blob/master/src/entities/blog.entity.ts"
click node_base_entity "https://github.com/bashleigh/nestjs-blog/blob/master/src/entities/base.entity.ts"
click node_mysql "https://github.com/bashleigh/nestjs-blog/blob/master/docker-compose.yml"
click node_webpack "https://github.com/bashleigh/nestjs-blog/blob/master/webpack.config.js"

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_main,node_main_hmr,node_app_module toneBlue
class node_auth_module,node_auth_controller,node_auth_service,node_jwt_strategy,node_user_module,node_user_controller,node_user_service,node_blog_module,node_blog_controller,node_blog_service,node_slug_provider toneAmber
class node_database_config,node_jwt_config,node_slugify_config,node_models,node_paginate toneMint
class node_entities,node_user_entity,node_blog_entity,node_base_entity toneRose
class node_mysql,node_webpack toneIndigo
```

## Components

### Entrypoints

Application bootstrap and development reload entrypoints.

- [App bootstrap](https://github.com/bashleigh/nestjs-blog/blob/master/src/main.ts): Nest bootstrap · Production NestJS entrypoint that starts the HTTP server. · `src/main.ts`
- [HMR bootstrap](https://github.com/bashleigh/nestjs-blog/blob/master/src/main.hmr.ts): Nest HMR · Development entrypoint for hot reload and nodemon-based iteration. · `src/main.hmr.ts`
- [App module](https://github.com/bashleigh/nestjs-blog/blob/master/src/app.module.ts): Composition root · Top-level Nest module that wires feature modules and infrastructure. · `src/app.module.ts`

### Feature modules

Main NestJS domain boundaries.

- [Auth module](https://github.com/bashleigh/nestjs-blog/blob/master/src/auth/auth.module.ts): Security module · Authentication boundary for login and JWT validation. · `src/auth/auth.module.ts`
- [Auth API](https://github.com/bashleigh/nestjs-blog/blob/master/src/auth/auth.controller.ts): Controller · Exposes authentication endpoints. · `src/auth/auth.controller.ts`
- [Auth service](https://github.com/bashleigh/nestjs-blog/blob/master/src/auth/auth.service.ts): Service · Implements login and token logic. · `src/auth/auth.service.ts`
- [JWT strategy](https://github.com/bashleigh/nestjs-blog/blob/master/src/auth/jwt.strategy.ts): Passport strategy · Validates JWTs and integrates protected-route auth. · `src/auth/jwt.strategy.ts`
- [User module](https://github.com/bashleigh/nestjs-blog/blob/master/src/user/user.module.ts): Identity module · User-domain boundary for account data and retrieval. · `src/user/user.module.ts`
- [User API](https://github.com/bashleigh/nestjs-blog/blob/master/src/user/user.controller.ts): Controller · Exposes user-related endpoints. · `src/user/user.controller.ts`
- [User service](https://github.com/bashleigh/nestjs-blog/blob/master/src/user/user.service.ts): Service · Handles user-domain business logic. · `src/user/user.service.ts`
- [Blog module](https://github.com/bashleigh/nestjs-blog/blob/master/src/blog/blog.module.ts): Content module · Core content boundary for posts and slugs. · `src/blog/blog.module.ts`
- [Blog API](https://github.com/bashleigh/nestjs-blog/blob/master/src/blog/blog.controller.ts): Controller · Exposes blog endpoints. · `src/blog/blog.controller.ts`
- [Blog service](https://github.com/bashleigh/nestjs-blog/blob/master/src/blog/blog.service.ts): Service · Implements blog creation and content logic. · `src/blog/blog.service.ts`
- [Slug helper](https://github.com/bashleigh/nestjs-blog/blob/master/src/blog/slug.provider.ts): Provider · Generates stable URL-friendly slugs for blog content. · `src/blog/slug.provider.ts`

### Shared layer

Cross-cutting configuration, models, and helpers.

- [Database config](https://github.com/bashleigh/nestjs-blog/blob/master/src/config/database.ts): TypeORM config · Configures MySQL/TypeORM connectivity. · `src/config/database.ts`
- [JWT config](https://github.com/bashleigh/nestjs-blog/blob/master/src/config/jwt.ts): Config · Holds JWT settings used by auth. · `src/config/jwt.ts`
- [Slug config](https://github.com/bashleigh/nestjs-blog/blob/master/src/config/slugify.ts): Config · Centralizes slug formatting behavior. · `src/config/slugify.ts`
- [API models](https://github.com/bashleigh/nestjs-blog/blob/master/src/models/index.ts): DTO models · Request/response shapes for auth, blog, and user APIs. · `src/models/index.ts`
- [Pagination](https://github.com/bashleigh/nestjs-blog/blob/master/src/paginate/pagination.ts): Shared helper · Reusable pagination interfaces and utilities. · `src/paginate/pagination.ts`

### Persistence

TypeORM entities and database connectivity.

- [Entities](https://github.com/bashleigh/nestjs-blog/blob/master/src/entities/index.ts): TypeORM models · Persistence models bridging services and MySQL. · `src/entities/index.ts`
- [User entity](https://github.com/bashleigh/nestjs-blog/blob/master/src/entities/user.entity.ts): Entity · Database model for users. · `src/entities/user.entity.ts`
- [Blog entity](https://github.com/bashleigh/nestjs-blog/blob/master/src/entities/blog.entity.ts): Entity · Database model for blog posts. · `src/entities/blog.entity.ts`
- [Base entity](https://github.com/bashleigh/nestjs-blog/blob/master/src/entities/base.entity.ts): Entity base · Shared entity fields and persistence defaults. · `src/entities/base.entity.ts`

### Runtime infra

Local database and deployment support.

- [MySQL](https://github.com/bashleigh/nestjs-blog/blob/master/docker-compose.yml): Database · Backing datastore used by the application. · `docker-compose.yml`
- [Webpack HMR](https://github.com/bashleigh/nestjs-blog/blob/master/webpack.config.js): Dev build · Development bundling used for hot reload. · `webpack.config.js`

## Connections

- App bootstrap → App module: boots · Production startup loads the Nest composition root.
- HMR bootstrap → Webpack HMR: uses · Development startup depends on the HMR webpack build.
- HMR bootstrap → App module: boots · Hot-reload entry still initializes the same application module.
- App module → Auth module: imports · Wires the authentication boundary into the application.
- App module → User module: imports · Wires the user boundary into the application.
- App module → Blog module: imports · Wires the content boundary into the application.
- App module → Database config: configures · Provides database connectivity to feature modules.
- App module → JWT config: configures · Supplies JWT settings to authentication.
- Auth module → Auth API: contains · Exposes auth HTTP endpoints.
- Auth module → Auth service: provides · Encapsulates authentication logic.
- Auth module → JWT strategy: uses · Attaches JWT validation for protected routes.
- Auth service → User service: reads users · Authentication depends on user-domain data.
- Auth service → API models: returns · Uses API-facing auth shapes.
- JWT strategy → JWT config: reads · Uses JWT configuration for validation.
- User module → User API: contains · Exposes user HTTP endpoints.
- User module → User service: provides · Encapsulates user business logic.
- User service → Entities: persists via · User operations flow through TypeORM models.
- Blog module → Blog API: contains · Exposes blog HTTP endpoints.
- Blog module → Blog service: provides · Encapsulates blog business logic.
- Blog module → Slug helper: uses · Blog behavior depends on slug generation.
- Blog service → Entities: persists via · Blog operations flow through TypeORM models.
- Blog service → Pagination: lists with · Blog listing endpoints use shared pagination.
- Slug helper → Slug config: reads · Slug formatting is centralized in config.
- Entities → Base entity: extends · Domain entities share common base fields.
- Entities → User entity: includes · Persistence model for users.
- Entities → Blog entity: includes · Persistence model for blog posts.
- Entities → MySQL: stored in · TypeORM maps entities to MySQL tables.
- API models → Auth module: shapes · Auth request/response contracts.
- API models → User module: shapes · User API contracts.
- API models → Blog module: shapes · Blog API contracts.
