# losefor/nest-starter architecture

> Architecture diagram of the GitHub repository losefor/nest-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/losefor/nest-starter
- Repository: https://github.com/losefor/nest-starter

## Overview

##### Project Type and Purpose
- This is a production-grade Nest.js backend (modular monolith) with the following capabilities:
- REST API with versioning support
- Authentication (JWT + Passport) and ACL (CASL)
- File upload & image processing (Sharp)
- Database access via Prisma ORM (PostgreSQL/MySQL)
- Internationalization (i18n)
- A shared image-manipulation library under `libs/`

##### Main Architectural Layers & Components
- API Layer (Express + Nest Controllers)
- Routes grouped by modules: Auth, Users, Permissions, Uploads
- Business Logic Layer (Nest Services + CASL Ability Factory)
- Data Access Layer (Prisma Module & Services)
- Shared Library (Image-Manipulation Lib)
- Cross-cutting Modules & Middleware
- Common module (logging, version headers, user decorator)
- i18n module (localization JSON files)
- Guards & Strategies (JWT, permissions, anonymous)
- External Dependencies
- Relational Database (PostgreSQL/MySQL)
- Object Storage (DigitalOcean Spaces via Multer + Sharp)
- Process Management (PM2)

##### Relationships & Data Flow
1. Client → API Gateway (Nest + Express + Cors + Helmet + Morgan)
2. Controller (e.g., `UploadsController`) receives HTTP request
3. Guards & Interceptors enforce auth, permissions, versioning, i18n
4. Controller calls Service (e.g., `UploadsService`)
5. Service applies business rules, calls CASL Ability Factory if needed
6. For DB operations → PrismaService → Database
7. For file handling → Multer middleware → UploadsService → Sharp/Image-Manipulation Lib → DigitalOcean Spaces
8. Responses propagate back up to Controller and are sent to Client

##### Architectural Patterns & Principles
- Modular structure: each feature in its own Nest module
- Layered architecture: Controllers → Services → Prisma → DB
- Dependency Injection for services, Prisma client, and shared libs
- Separation of concerns: Auth, ACL, i18n, image processing all isolated
- Versioning enforced via custom decorators & interceptors
- Shared library (`libs/image-manipulation`) for reusable image logic

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients and Gateway
    Client["Client"]:::client
    API["Nest API Gateway\n(Express + Cors + Helmet + Morgan)"]:::gateway
    Client -->|HTTP Request| API

    %% Controllers Layer
    subgraph "API Layer: Controllers"
        direction TB
        AuthController["AuthController"]:::controller
        UsersController["UsersController"]:::controller
        PermissionsController["PermissionsController"]:::controller
        UploadsController["UploadsController"]:::controller
    end
    API --> AuthController
    API --> UsersController
    API --> PermissionsController
    API --> UploadsController

    %% Guards & Interceptors
    subgraph "Guards & Interceptors" 
        direction TB
        JWTGuard["JwtAuthGuard"]:::guard
        OptJWTGuard["JwtAuthOptionalGuard"]:::guard
        PermissionGuard["PermissionGuard"]:::guard
        AnonymousStrat["AnonymousStrategy"]:::guard
        JWTStrat["JwtStrategy"]:::guard
        I18nInt["i18nInterceptor"]:::interceptor
        VersionInt["VersionInterceptor"]:::interceptor
    end
    AuthController --> JWTGuard
    AuthController --> PermissionGuard
    UsersController --> JWTGuard
    UsersController --> PermissionGuard
    PermissionsController --> JWTGuard
    PermissionsController --> PermissionGuard
    UploadsController --> JWTGuard
    UploadsController --> PermissionGuard
    AuthController --> I18nInt
    UsersController --> I18nInt
    PermissionsController --> I18nInt
    UploadsController --> I18nInt
    AuthController --> VersionInt
    UsersController --> VersionInt
    PermissionsController --> VersionInt
    UploadsController --> VersionInt

    %% Service Layer
    subgraph "Business Logic Layer: Services"
        direction TB
        AuthService["AuthService"]:::service
        UsersService["UsersService"]:::service
        PermissionsService["PermissionsService"]:::service
        UploadsService["UploadsService"]:::service
        CASLFactory["CaslAbilityFactory"]:::service
        CommonService["CommonService"]:::service
    end
    AuthController --> AuthService
    UsersController --> UsersService
    PermissionsController --> PermissionsService
    UploadsController --> UploadsService
    AuthService --> CASLFactory
    UsersService --> CASLFactory
    PermissionsService --> CASLFactory
    UploadsService --> CASLFactory
    AuthService --> CommonService
    UsersService --> CommonService
    PermissionsService --> CommonService
    UploadsService --> CommonService

    %% Shared Image Manipulation Library
    subgraph "Shared Library"
        direction TB
        ImageLibModule["ImageManipulationModule"]:::library
        ImageLibService["ImageManipulationService"]:::library
    end
    UploadsService --> ImageLibService

    %% Prisma and Database
    subgraph "Data Access Layer"
        direction TB
        PrismaModule["PrismaModule"]:::database
        PrismaService["PrismaService"]:::database
        Database["Relational DB\n(PostgreSQL/MySQL)"]:::db
    end
    AuthService --> PrismaService
    UsersService --> PrismaService
    PermissionsService --> PrismaService
    UploadsService --> PrismaService
    PrismaService --> Database

    %% External Storage
    Storage["External Storage\n(DigitalOcean Spaces)"]:::storage
    ImageLibService --> Storage

    %% Cross-Cutting Modules
    subgraph "Cross-Cutting Modules"
        direction TB
        CommonModule["CommonModule"]:::crosscut
        CaslModule["CaslModule"]:::crosscut
        I18nModule["I18nModule"]:::crosscut
    end
    CommonModule -.-> AuthController
    CommonModule -.-> UsersController
    CommonModule -.-> PermissionsController
    CommonModule -.-> UploadsController
    CaslModule -.-> AuthService
    CaslModule -.-> UsersService
    CaslModule -.-> PermissionsService
    CaslModule -.-> UploadsService
    I18nModule -.-> AuthController
    I18nModule -.-> UsersController
    I18nModule -.-> PermissionsController
    I18nModule -.-> UploadsController

    %% Configuration & Bootstrap
    subgraph "Configuration & Bootstrap"
        direction TB
        Main["main.ts"]:::config
        PM2["pm2.config.js"]:::config
        Env[".env.example"]:::config
        CLI["nest-cli.json"]:::config
        Package["package.json"]:::config
        TSConfig["tsconfig.json"]:::config
    end
    Main --> API

    %% Click Events for Mapping
    click AuthController "https://github.com/losefor/nest-starter/blob/main/src/auth/auth.controller.ts"
    click UsersController "https://github.com/losefor/nest-starter/blob/main/src/users/users.controller.ts"
    click PermissionsController "https://github.com/losefor/nest-starter/blob/main/src/permissions/permissions.controller.ts"
    click UploadsController "https://github.com/losefor/nest-starter/blob/main/src/uploads/uploads.controller.ts"
    click AuthService "https://github.com/losefor/nest-starter/blob/main/src/auth/auth.service.ts"
    click AuthModule "https://github.com/losefor/nest-starter/blob/main/src/auth/auth.module.ts"
    click JWTGuard "https://github.com/losefor/nest-starter/blob/main/src/auth/guards/jwt-auth.guard.ts"
    click OptJWTGuard "https://github.com/losefor/nest-starter/blob/main/src/auth/guards/jwt-auth-optional.guard.ts"
    click PermissionGuard "https://github.com/losefor/nest-starter/blob/main/src/auth/guards/permission.guard.ts"
    click AnonymousStrat "https://github.com/losefor/nest-starter/blob/main/src/auth/strategies/anonymous.strategy.ts"
    click JWTStrat "https://github.com/losefor/nest-starter/blob/main/src/auth/strategies/jwt.strategy.ts"
    click UsersService "https://github.com/losefor/nest-starter/blob/main/src/users/users.service.ts"
    click UsersModule "https://github.com/losefor/nest-starter/blob/main/src/users/users.module.ts"
    click PermissionsService "https://github.com/losefor/nest-starter/blob/main/src/permissions/permissions.service.ts"
    click PermissionsModule "https://github.com/losefor/nest-starter/blob/main/src/permissions/permissions.module.ts"
    click UploadsService "https://github.com/losefor/nest-starter/blob/main/src/uploads/uploads.service.ts"
    click UploadsModule "https://github.com/losefor/nest-starter/blob/main/src/uploads/uploads.module.ts"
    click PrismaModule "https://github.com/losefor/nest-starter/blob/main/src/prisma/prisma.module.ts"
    click PrismaService "https://github.com/losefor/nest-starter/blob/main/src/prisma/prisma.service.ts"
    click PrismaSchema "https://github.com/losefor/nest-starter/blob/main/src/prisma/schema.prisma"
    click ImageLibModule "https://github.com/losefor/nest-starter/blob/main/libs/image-manipulation/src/image-manipulation.module.ts"
    click ImageLibService "https://github.com/losefor/nest-starter/blob/main/libs/image-manipulation/src/image-manipulation.service.ts"
    click CommonModule "https://github.com/losefor/nest-starter/blob/main/src/common/common.module.ts"
    click CommonService "https://github.com/losefor/nest-starter/blob/main/src/common/common.service.ts"
    click CaslModule "https://github.com/losefor/nest-starter/blob/main/src/casl/casl.module.ts"
    click CASLFactory "https://github.com/losefor/nest-starter/blob/main/src/casl/casl-ability.factory.ts"
    click I18nModule "https://github.com/losefor/nest-starter/blob/main/src/i18n/en/index.json"
    click Main "https://github.com/losefor/nest-starter/blob/main/src/main.ts"
    click PM2 "https://github.com/losefor/nest-starter/blob/main/pm2.config.js"
    click Env "https://github.com/losefor/nest-starter/blob/main/.env.example"
    click CLI "https://github.com/losefor/nest-starter/blob/main/nest-cli.json"
    click Package "https://github.com/losefor/nest-starter/blob/main/package.json"
    click TSConfig "https://github.com/losefor/nest-starter/blob/main/tsconfig.json"

    %% Styles
    classDef client fill:#e3f2fd,stroke:#90caf9,color:#0d47a1
    classDef gateway fill:#bbdefb,stroke:#64b5f6,color:#0d47a1
    classDef controller fill:#e1f5fe,stroke:#81d4fa,color:#01579b
    classDef guard fill:#fff3e0,stroke:#ffb74d,color:#e65100
    classDef interceptor fill:#fff8e1,stroke:#ffe082,color:#ff6f00
    classDef service fill:#e3f2fd,stroke:#64b5f6,color:#0d47a1
    classDef library fill:#f3e5f5,stroke:#ce93d8,color:#4a148c
    classDef database fill:#c8e6c9,stroke:#81c784,color:#1b5e20
    classDef db fill:#a5d6a7,stroke:#66bb6a,color:#1b5e20
    classDef storage fill:#ffe0b2,stroke:#ffb74d,color:#e65100
    classDef crosscut fill:#f1f8e9,stroke:#aed581,color:#33691e
    classDef config fill:#eeeeee,stroke:#bdbdbd,color:#424242
```
