# santiq/bulletproof-nodejs architecture

> Architecture diagram of the GitHub repository santiq/bulletproof-nodejs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/santiq/bulletproof-nodejs
- Repository: https://github.com/santiq/bulletproof-nodejs

## Overview

##### Project type and purpose
- This is a backend API service written in Node.js + TypeScript following the “Bulletproof Node.js” layered architecture.
- Its role is to expose a user CRUD API with authentication, validation, email sequences and job scheduling.

##### File structure
- Top-level:
- config files (.env, CircleCI, Gitpod, ESLint, Prettier, Optic, Procfile)
- src/ – the entire server codebase
- tests/ – unit/integration tests
- src/
- api/ – Express routes and middlewares
- loaders/ – bootstrap modules (Express server, Mongoose, DI container, Agenda jobs, event system, logger)
- services/ – business logic (auth, mailer, etc.)
- models/ – Mongoose user schema
- jobs/ – Agenda job definitions (e.g., emailSequence)
- subscribers/ – event handlers subscribing to domain events
- decorators/ – custom decorators (e.g., eventDispatcher)
- config/, interfaces/, types/ – type definitions and app configuration

##### README for additional insights
- Mentions Celebrate+Joi for request validation
- Uses Optic for API documentation
- Emphasizes a layered, dependency-injected, event-driven design

1. Client (e.g., Postman / Frontend)
2. Express API Gateway
3. Validation Layer (celebrate/Joi)
4. Authentication & Authorization middleware
5. Router → Controllers
6. Dependency Injection Container (wires services, repositories, eventDispatcher)
7. Services Layer (authService, mailerService, userService, etc.)
8. Data Layer (Mongoose + MongoDB)
9. Event Bus (in-process EventEmitter)
10. Subscribers (userCreated, emailSent handlers)
11. Job Scheduler (Agenda, jobs like emailSequence)
12. External Services (SMTP/email provider, Optic CLI, third-party services if any)
13. CI/CD (CircleCI) and Deployment (Heroku/Elastic Beanstalk via Procfile)

b. Relationships & interactions:
- Requests flow: Client → API Gateway → Validation → Auth Middleware → Router → Controller
- Controller → calls Services → Services → DAO (Mongoose) → MongoDB
- Services dispatch domain events → Event Bus → Subscribers
- Subscribers may schedule jobs in Agenda → Agenda Worker → execute job definitions (e.g. emailSequence → mailerService → SMTP)
- Optic CLI captures requests for API spec (separate side-channel)
- CircleCI pipeline runs tests & lint on push

c. Architectural patterns / principles:
- Layered (Presentation → API → Services → Data)
- Dependency Injection to decouple modules
- Event-Driven for cross-cutting concerns (logging, emails, audits)
- Job Scheduling for background tasks (Agenda)
- Validation at the edge (Celebrate+)
- Separation of concerns: loaders initialize each layer

d. Key technologies / libraries:
- Node.js + TypeScript
- Express.js
- Celebrate + Joi
- Mongoose + MongoDB
- Agenda (job scheduling)
- EventEmitter pattern via custom decorator
- Dependency Injector (tsyringe/inversify or custom)
- Optic (API docs)
- CircleCI (CI)
- dotenv / config

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    Client["Client (Postman/Frontend)"]:::external
    SMTP["SMTP / Email Provider"]:::external
    MongoDB["MongoDB"]:::external
    Optic["Optic CLI"]:::external
    CI["CircleCI"]:::external

    %% API Layer
    subgraph "API Layer" 
        direction TB
        APPI["Express API Gateway\n(src/app.ts)"]:::api
        EXP["Express Loader\n(src/loaders/express.ts)"]:::api
        APIIDX["API Index\n(src/api/index.ts)"]:::api
        VAL["Validation Middleware\n(Celebrate/Joi)"]:::api
        AUTHMW["Auth Middleware\n(src/api/middlewares/isAuth.ts)"]:::api
        ATTACH["Attach User Middleware\n(src/api/middlewares/attachCurrentUser.ts)"]:::api
        subgraph "Routes"
            direction TB
            AuthRoute["Auth Route\n(src/api/routes/auth.ts)"]:::api
            UserRoute["User Route\n(src/api/routes/user.ts)"]:::api
            AgendaDash["Agendash Route\n(src/api/routes/agendash.ts)"]:::api
        end
    end

    %% Services Layer
    subgraph "Services Layer"
        direction TB
        DI["Dependency Injector\n(src/loaders/dependencyInjector.ts)"]:::service
        AuthSvc["Auth Service\n(src/services/auth.ts)"]:::service
        MailerSvc["Mailer Service\n(src/services/mailer.ts)"]:::service
        UserSvc["User Service"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        MONGOLOAD["Mongoose Loader\n(src/loaders/mongoose.ts)"]:::data
        UserModel["User Model\n(src/models/user.ts)"]:::data
        DB["MongoDB"]:::external
    end

    %% Event & Jobs
    subgraph "Events & Jobs"
        direction TB
        EventLoader["Event Loader\n(src/loaders/events.ts)"]:::job
        EventDec["Event Dispatcher Decorator\n(src/decorators/eventDispatcher.ts)"]:::job
        subgraph "Subscribers"
            direction TB
            SubEvents["Events Subscriber\n(src/subscribers/events.ts)"]:::job
            SubUser["User Subscriber\n(src/subscribers/user.ts)"]:::job
        end
        AgendaLoad["Agenda Loader\n(src/loaders/agenda.ts)"]:::job
        JobsLoad["Jobs Loader\n(src/loaders/jobs.ts)"]:::job
        EmailJob["Email Sequence Job\n(src/jobs/emailSequence.ts)"]:::job
    end

    %% Configuration & CI/CD
    subgraph "Config & CI/CD"
        direction TB
        Config["App Config\n(src/config/index.ts)"]:::config
        Env[".env.example"]:::config
        Proc["Procfile"]:::config
        Circle["CI Config\n(.circleci/config.yml)"]:::config
        OpticSpec["Optic Spec\n(.optic/api/specification.json)"]:::config
        OpticYml["Optic Config\n(optic.yml)"]:::config
    end

    %% Connections
    Client -->|"POST /signup"| APPI
    APPI --> EXP
    EXP --> APIIDX
    APIIDX --> VAL
    VAL --> ATTACH
    ATTACH --> AUTHMW
    AUTHMW --> AuthRoute
    AUTHMW --> UserRoute
    AUTHMW --> AgendaDash

    AuthRoute -->|"calls login/signup"| AuthSvc
    UserRoute -->|"calls user operations"| UserSvc
    AgendaDash -->|"dashboard UI"| DI

    DI --> AuthSvc
    DI --> MailerSvc
    DI --> UserSvc
    DI --> EventLoader
    DI --> AgendaLoad
    DI --> MONGOLOAD

    AuthSvc --> UserModel
    UserSvc --> UserModel
    UserModel --> DB

    AuthSvc -->|"dispatch:user.created"| EventLoader
    UserSvc -->|"dispatch:user.updated"| EventLoader
    EventLoader --> EventDec
    EventDec --> SubEvents
    EventDec --> SubUser

    SubUser -->|"Agenda.schedule"| AgendaLoad
    AgendaLoad --> JobsLoad
    JobsLoad --> EmailJob
    EmailJob --> MailerSvc
    MailerSvc --> SMTP

    APPI -->|captures| Optic
    CI -->|runs tests/lint| APPI

    Config --> APPI
    Env --> Config
    Proc --> APPI
    OpticSpec --> Optic
    OpticYml --> Optic

    %% Click Events
    click APPI "https://github.com/santiq/bulletproof-nodejs/blob/master/src/app.ts"
    click EXP "https://github.com/santiq/bulletproof-nodejs/blob/master/src/loaders/express.ts"
    click APIIDX "https://github.com/santiq/bulletproof-nodejs/blob/master/src/api/index.ts"
    click AuthRoute "https://github.com/santiq/bulletproof-nodejs/blob/master/src/api/routes/auth.ts"
    click UserRoute "https://github.com/santiq/bulletproof-nodejs/blob/master/src/api/routes/user.ts"
    click AgendaDash "https://github.com/santiq/bulletproof-nodejs/blob/master/src/api/routes/agendash.ts"
    click AUTHMW "https://github.com/santiq/bulletproof-nodejs/blob/master/src/api/middlewares/isAuth.ts"
    click ATTACH "https://github.com/santiq/bulletproof-nodejs/blob/master/src/api/middlewares/attachCurrentUser.ts"
    click DI "https://github.com/santiq/bulletproof-nodejs/blob/master/src/loaders/dependencyInjector.ts"
    click AuthSvc "https://github.com/santiq/bulletproof-nodejs/blob/master/src/services/auth.ts"
    click MailerSvc "https://github.com/santiq/bulletproof-nodejs/blob/master/src/services/mailer.ts"
    click MONGOLOAD "https://github.com/santiq/bulletproof-nodejs/blob/master/src/loaders/mongoose.ts"
    click UserModel "https://github.com/santiq/bulletproof-nodejs/blob/master/src/models/user.ts"
    click EventLoader "https://github.com/santiq/bulletproof-nodejs/blob/master/src/loaders/events.ts"
    click EventDec "https://github.com/santiq/bulletproof-nodejs/blob/master/src/decorators/eventDispatcher.ts"
    click SubEvents "https://github.com/santiq/bulletproof-nodejs/blob/master/src/subscribers/events.ts"
    click SubUser "https://github.com/santiq/bulletproof-nodejs/blob/master/src/subscribers/user.ts"
    click AgendaLoad "https://github.com/santiq/bulletproof-nodejs/blob/master/src/loaders/agenda.ts"
    click JobsLoad "https://github.com/santiq/bulletproof-nodejs/blob/master/src/loaders/jobs.ts"
    click EmailJob "https://github.com/santiq/bulletproof-nodejs/blob/master/src/jobs/emailSequence.ts"
    click Config "https://github.com/santiq/bulletproof-nodejs/blob/master/src/config/index.ts"
    click Env "https://github.com/santiq/bulletproof-nodejs/blob/master/.env.example"
    click Proc "https://github.com/santiq/bulletproof-nodejs/tree/master/Procfile"
    click Circle "https://github.com/santiq/bulletproof-nodejs/blob/master/.circleci/config.yml"
    click OpticSpec "https://github.com/santiq/bulletproof-nodejs/blob/master/.optic/api/specification.json"
    click OpticYml "https://github.com/santiq/bulletproof-nodejs/blob/master/optic.yml"

    %% Styles
    classDef external fill:#b2f2bb,stroke:#2f9e44,color:#1b4332
    classDef api fill:#99e9f2,stroke:#1098ad,color:#0c525d
    classDef service fill:#ffd8a8,stroke:#f76707,color:#ae3b0c
    classDef data fill:#d0bfff,stroke:#7048e8,color:#341a59
    classDef job fill:#ffe066,stroke:#f08c00,color:#663c00
    classDef config fill:#e9ecef,stroke:#adb5bd,color:#495057
```
