# arun12kumar/lead_management_system architecture

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

- Interactive diagram: https://gitdiagram.com/arun12kumar/lead_management_system
- Repository: https://github.com/arun12kumar/lead_management_system

## Overview

This is a **backend-only Express.js REST API** for an **Insurance Lead Management System**:
- **HTTP API** (Express) exposing endpoints for auth and lead lifecycle operations
- **PostgreSQL** persistence via **Sequelize ORM**
- **JWT-based authentication**
- **Swagger UI** for interactive API docs
- Conventional layering: **Routes → Controllers → Services → Models/DB**, with **Middlewares** for auth + validation and **Migrations** for schema management

##### Runtime entry + composition root
- `src/server.js`
The app bootstrap: creates the Express app, wires middleware, routes, swagger, logging, connects DB.

##### Configuration / integration components
- `src/config/db.js`
Sequelize init + Postgres connection (likely builds Sequelize instance using env vars)
- `src/config/config.cjs`
Sequelize CLI config per environment (used by migrations)
- `src/config/swagger.js`
Swagger spec setup and route mounting (e.g., `/api/docs`)

##### API surface (routing layer)
- `src/routes/authRoute.js`
- `src/routes/leadRoutes.js`
Endpoint paths, attach middlewares, forward to controllers.

##### Request handling (controller layer)
- `src/controllers/authController.js`
- `src/controllers/leadController.js`
Thin HTTP-focused handlers: parse request, call service, set status/response.

##### Business logic (service layer)
- `src/services/leadService.js`

##### Cross-cutting middleware
- `src/middlewares/authMiddleware.js`
JWT verification, request user context; protects routes.
- `src/middlewares/leadValidators.js`
Input validation for lead operations; fails fast before controller.

##### Persistence layer
- `src/models/User.js`
- `src/models/Lead.js`
Sequelize model definitions and associations (if any).

##### Schema management (not runtime critical, but architectural)
- `src/migrations/*create-users.cjs`, `*create-leads.cjs`
One-time / deploy-time schema evolution managed by Sequelize CLI.

##### Observability
- `src/utils/logger.js`
Winston logger; plus README mentions Morgan (HTTP access logs) likely wired in `server.js`.

##### Inbound
- Client (HTTP)

##### Express app pipeline (in `server.js`)
- Express Router mount points: `/api/auth/*`, `/api/leads/*`, `/api/docs`
- Global middleware: JSON parser, Morgan (if used), error handler (if present—if not, leave as “default error handling”)

##### Routes layer (`src/routes`)
- `authRoute.js`
- `leadRoutes.js`

##### Middleware layer (`src/middlewares`)
- `authMiddleware.js` (applies to protected lead routes)
- `leadValidators.js` (applies to create/update lead endpoints)

##### Controllers (`src/controllers`)
- `authController.js`
- `leadController.js`

##### Services (`src/services`)
- `leadService.js`

##### Persistence (`src/models`)
- `User` model
- `Lead` model
- Sequelize instance (from `src/config/db.js`)

##### Database
- PostgreSQL: tables `users`, `leads` (from migrations)

##### Docs + Config
- Swagger setup (`src/config/swagger.js`) feeding `/api/docs`
- Sequelize CLI config (`src/config/config.cjs`) used by migrations (show as “build/deploy-time” linkage, not runtime)

##### Logging
- `src/utils/logger.js` used by server/controllers/services

- Client → `leadRoutes` (e.g., `POST /api/leads`)
- `leadRoutes` → `authMiddleware` (Bearer token verification)
- `leadRoutes` → `leadValidators`
- `leadRoutes` → `leadController`
- `leadController` → `leadService`
- `leadService` → `Lead` model (Sequelize)
- `Lead` model → PostgreSQL (table: `leads`)

Auth flow:
- Client → `authRoute` (`POST /api/auth/login`)
- `authRoute` → `authController`
- `authController` → `User` model → PostgreSQL (`users`)
- `authController` → JWT signing (label “JWT_SECRET”)
- Response contains token → Client

Swagger flow:
- Client (browser) → `/api/docs`
- Express → Swagger UI/JSON (from `swagger.js`)

Migrations (separate lane):
- “Sequelize CLI (npm run migrate)” → `src/migrations/*.cjs` → PostgreSQL schema

##### Important architectural patterns to highlight
- **Layered architecture**: Routes (transport) → Controllers (HTTP concerns) → Services (business logic) → Models/ORM (data access)
- **Middleware pipeline**: Auth + validation executed before controllers
- **Schema-as-code**: migrations define DB evolution; README explicitly avoids `sequelize.sync()` in production
- **Cross-cutting concerns**:
- Security: JWT issuance + verification
- Observability: Morgan (request logs) + Winston logger
- API discoverability: Swagger docs served from same app

##### Split by lanes
- **Runtime (Request Path)**
- **Data (Models + DB)**
- **Build/Deploy time (Migrations)**
- **Cross-cutting (Logging, Swagger)**

- Protocol: HTTP/JSON, SQL
- Auth mechanism: “Bearer JWT”
- Key endpoints: `/api/auth/login`, `/api/leads/*`, `/api/docs`

##### *real* dependencies implied by the tree
- Routes depend on middlewares + controllers
- Controllers depend on services
- Services depend on models
- Models depend on Sequelize instance/config
- Migrations depend on Sequelize CLI config

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================================================
%% Diagram A — Context (C4 L1)
%% =========================================================
subgraph A["A) Context — C4 Level 1"]
  direction TB

  A_client["API Clients\n(Admin UI / CRM / Postman / Partner)"]:::external
  A_api["Insurance Lead Management System\n(Express REST API)"]:::container
  A_db[("PostgreSQL Database")]:::db
  A_docs["Swagger UI / OpenAPI\n(/api/docs)"]:::docs

  A_client -->|"HTTPS/REST (JSON)\nBearer JWT"| A_api
  A_api -->|"JSON responses\nJWT issuance (login)"| A_client
  A_api -->|"SQL via Sequelize ORM"| A_db
  A_client -->|"Browse API docs"| A_docs
  A_docs -->|"Served by API"| A_api
end

%% =========================================================
%% Diagram B — Container (C4 L2)
%% =========================================================
subgraph B["B) Container — C4 Level 2"]
  direction TB

  B_user["User/Developer Browser"]:::external
  B_clients["API Clients"]:::external

  subgraph B_runtime["Runtime / Deployment"]
    direction TB
    B_node["Node.js / Express API\n(single deployable unit)"]:::container
    B_pg[("PostgreSQL\n(managed service / container)")]:::db
    B_logs[("Log sink\n(console / file)")]:::infra
  end

  B_env["Env vars\nPORT, DB_*, JWT_SECRET,\nJWT_EXPIRES_IN, NODE_ENV"]:::note
  B_migrate["Sequelize CLI job\nnpm run migrate"]:::deploy
  B_cfg["Sequelize CLI env config\n(config.cjs + .sequelizerc)"]:::deploy

  B_clients -->|"HTTPS/REST (JSON)"| B_node
  B_user -->|"Open /api/docs"| B_node
  B_node -->|"Serve Swagger UI"| B_user

  B_node -->|"Sequelize (SQL)"| B_pg
  B_node -->|"Winston + Morgan (HTTP access logs)"| B_logs

  B_env -.->|"configures"| B_node
  B_env -.->|"configures"| B_migrate

  B_migrate -.->|"uses"| B_cfg
  B_migrate -.->|"applies migrations to"| B_pg
end

%% =========================================================
%% Diagram C — Component (C4 L3)
%% =========================================================
subgraph C["C) Component — C4 Level 3 (inside Express API)"]
  direction TB

  C_client["Client\n(HTTP/JSON)"]:::external

  subgraph C_app["Express App Pipeline (server.js)"]
    direction TB
    C_server["server.js\nBootstrap + wiring"]:::container
    C_mount_auth["Mount: /api/auth/*"]:::api
    C_mount_leads["Mount: /api/leads/*"]:::api
    C_mount_docs["Mount: /api/docs"]:::docs
    C_global_mw["Global middleware\nJSON parser + Morgan + default error handling"]:::middleware
  end

  subgraph C_routes["Routes (src/routes)"]
    direction TB
    C_authRoute["authRoute.js"]:::api
    C_leadRoutes["leadRoutes.js"]:::api
  end

  subgraph C_mw["Middlewares (src/middlewares)"]
    direction TB
    C_authMW["authMiddleware.js\nJWT verify + req.user"]:::middleware
    C_leadVal["leadValidators.js\nInput validation"]:::middleware
  end

  subgraph C_ctrl["Controllers (src/controllers)"]
    direction TB
    C_authCtrl["authController.js\nLogin + JWT issuance"]:::controller
    C_leadCtrl["leadController.js\nLead HTTP handlers"]:::controller
  end

  subgraph C_svc["Services (src/services)"]
    direction TB
    C_leadSvc["leadService.js\nCore lead business logic"]:::service
  end

  subgraph C_persist["Persistence (Sequelize)"]
    direction TB
    C_dbInit["db.js\nSequelize init + Postgres conn"]:::persistence
    C_userModel["User.js\nSequelize model"]:::persistence
    C_leadModel["Lead.js\nSequelize model"]:::persistence
  end

  C_pg[("PostgreSQL\nTables: users, leads")]:::db

  subgraph C_cross["Cross-cutting"]
    direction TB
    C_swagger["swagger.js\nOpenAPI spec + Swagger UI"]:::docs
    C_logger["logger.js\nWinston logger"]:::infra
    C_jwt["JWT (HS256)\nJWT_SECRET + JWT_EXPIRES_IN"]:::security
  end

  subgraph C_deploy["Build/Deploy-time (Schema-as-code)"]
    direction TB
    C_sequelizerc[".sequelizerc\nSequelize CLI hook"]:::deploy
    C_cliCfg["config.cjs\nSequelize CLI env config"]:::deploy
    C_mig_users["20240101000001-create-users.cjs"]:::deploy
    C_mig_leads["20240101000002-create-leads.cjs"]:::deploy
    C_cli["Sequelize CLI\nnpm run migrate"]:::deploy
  end

  %% --- Request flow wiring (vertical, explicit) ---
  C_client -->|"HTTP/JSON"| C_server
  C_server -->|"uses"| C_global_mw
  C_server -->|"mounts"| C_mount_auth
  C_server -->|"mounts"| C_mount_leads
  C_server -->|"mounts"| C_mount_docs

  %% --- Swagger docs flow ---
  C_mount_docs -->|"serves"| C_swagger
  C_client -.->|"browse /api/docs"| C_mount_docs
  C_swagger -.->|"Try-it-out calls"| C_mount_auth
  C_swagger -.->|"Try-it-out calls"| C_mount_leads

  %% --- Auth route flow ---
  C_mount_auth -->|"routes"| C_authRoute
  C_authRoute -->|"POST /api/auth/login"| C_authCtrl
  C_authCtrl -->|"lookup user"| C_userModel
  C_authCtrl -->|"sign token"| C_jwt
  C_authCtrl -->|"log events"| C_logger
  C_authCtrl -->|"JSON (token)"| C_client

  %% --- Lead route flow (protected + validated) ---
  C_mount_leads -->|"routes"| C_leadRoutes
  C_leadRoutes -->|"Bearer JWT"| C_authMW
  C_leadRoutes -->|"validate body/params"| C_leadVal
  C_authMW -->|"next()"| C_leadCtrl
  C_leadVal -->|"next()"| C_leadCtrl
  C_leadCtrl -->|"call"| C_leadSvc
  C_leadSvc -->|"CRUD via Sequelize"| C_leadModel
  C_leadSvc -->|"log events"| C_logger
  C_leadCtrl -->|"JSON response"| C_client

  %% --- Persistence dependencies ---
  C_dbInit -->|"provides Sequelize instance"| C_userModel
  C_dbInit -->|"provides Sequelize instance"| C_leadModel
  C_userModel -->|"SQL"| C_pg
  C_leadModel -->|"SQL"| C_pg

  %% --- Server logging hookup ---
  C_server -->|"app logger"| C_logger
  C_global_mw -->|"HTTP access logs (Morgan)"| C_logger

  %% --- Migrations lane (deploy-time) ---
  C_cli -->|"uses"| C_sequelizerc
  C_cli -->|"reads envs"| C_cliCfg
  C_cli -->|"runs"| C_mig_users
  C_cli -->|"runs"| C_mig_leads
  C_mig_users -.->|"create table users"| C_pg
  C_mig_leads -.->|"create table leads"| C_pg

  %% --- Layout helpers (keep vertical, avoid long horizontal) ---
  C_dbInit -.->|"configured by env vars"| C_server
end

%% =========================================================
%% Click Events (from component_mapping)
%% =========================================================
click C_server "https://github.com/arun12kumar/lead_management_system/blob/main/src/server.js"
click C_dbInit "https://github.com/arun12kumar/lead_management_system/blob/main/src/config/db.js"
click C_cliCfg "https://github.com/arun12kumar/lead_management_system/blob/main/src/config/config.cjs"
click C_swagger "https://github.com/arun12kumar/lead_management_system/blob/main/src/config/swagger.js"
click C_authRoute "https://github.com/arun12kumar/lead_management_system/blob/main/src/routes/authRoute.js"
click C_leadRoutes "https://github.com/arun12kumar/lead_management_system/blob/main/src/routes/leadRoutes.js"
click C_authCtrl "https://github.com/arun12kumar/lead_management_system/blob/main/src/controllers/authController.js"
click C_leadCtrl "https://github.com/arun12kumar/lead_management_system/blob/main/src/controllers/leadController.js"
click C_leadSvc "https://github.com/arun12kumar/lead_management_system/blob/main/src/services/leadService.js"
click C_authMW "https://github.com/arun12kumar/lead_management_system/blob/main/src/middlewares/authMiddleware.js"
click C_leadVal "https://github.com/arun12kumar/lead_management_system/blob/main/src/middlewares/leadValidators.js"
click C_userModel "https://github.com/arun12kumar/lead_management_system/blob/main/src/models/User.js"
click C_leadModel "https://github.com/arun12kumar/lead_management_system/blob/main/src/models/Lead.js"
click C_mig_users "https://github.com/arun12kumar/lead_management_system/blob/main/src/migrations/20240101000001-create-users.cjs"
click C_mig_leads "https://github.com/arun12kumar/lead_management_system/blob/main/src/migrations/20240101000002-create-leads.cjs"
click C_logger "https://github.com/arun12kumar/lead_management_system/blob/main/src/utils/logger.js"
click C_sequelizerc "https://github.com/arun12kumar/lead_management_system/blob/main/.sequelizerc"

%% =========================================================
%% Styles
%% =========================================================
classDef external fill:#E8F1FF,stroke:#2B6CB0,stroke-width:1.5px,color:#0B1F3A;
classDef container fill:#D9EEFF,stroke:#1E5AA8,stroke-width:2px,color:#0B1F3A;
classDef api fill:#CFE8FF,stroke:#1E5AA8,stroke-width:1.5px,color:#0B1F3A;
classDef controller fill:#B9DCFF,stroke:#1E5AA8,stroke-width:1.5px,color:#0B1F3A;

classDef middleware fill:#E7D9FF,stroke:#6B46C1,stroke-width:1.5px,color:#1D1238;
classDef service fill:#D7F7E0,stroke:#2F855A,stroke-width:1.5px,color:#0C2A1B;
classDef persistence fill:#FFE6BF,stroke:#C05621,stroke-width:1.5px,color:#3B1F0F;

classDef db fill:#E5E7EB,stroke:#374151,stroke-width:2px,color:#111827;
classDef infra fill:#E5E7EB,stroke:#4B5563,stroke-width:1.5px,color:#111827;

classDef docs fill:#FFF3B0,stroke:#B7791F,stroke-width:1.5px,color:#2D1B00;
classDef security fill:#FFD6D6,stroke:#C53030,stroke-width:1.5px,color:#2B0B0B;

classDef deploy fill:#F3F4F6,stroke:#6B7280,stroke-width:1.5px,stroke-dasharray:5 3,color:#111827;
classDef note fill:#F9FAFB,stroke:#9CA3AF,stroke-width:1px,stroke-dasharray:3 3,color:#111827;
```
