# rajappan47/incident-management-portal-backend architecture

> Architecture diagram of the GitHub repository rajappan47/incident-management-portal-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rajappan47/incident-management-portal-backend
- Repository: https://github.com/rajappan47/incident-management-portal-backend

## Overview

#### Purpose and entry point
This is a Node.js backend for incident management: authentication, users/admin operations, incident lifecycle, categories, comments, activity auditing, dashboards, and health checks. Application startup is `index.js`; HTTP surface is organized under `routes/`.

#### HTTP and request boundary
Route modules expose domain APIs and hand requests to controllers:
- Incident workflows: `routes/incidentRoutes.js`, `controllers/incidentController.js`
- Identity/access: `routes/authRoutes.js`, `controllers/authController.js`, `routes/userRoutes.js`
- Operational views: `routes/dashboardRoutes.js`, `controllers/dashboardController.js`, `routes/healthRoutes.js`

Cross-cutting request enforcement is implemented before controller handling: authentication and roles in `middlewares/authMiddleware.js` and `middlewares/roleMiddleware.js`; validation in `middlewares/validationMiddleware.js`; rate limiting, logging, uploads, and error conversion in `middlewares/rateLimiter.js`, `middlewares/uploadMiddleware.js`, and `middlewares/errorHandler.js`.

#### Domain service layer
Controllers delegate business operations to services, separating HTTP concerns from domain logic. The primary workflow service is `services/incidentService.js`, supported by `services/commentService.js`, `services/categoryService.js`, and `services/activityService.js`. Identity and administration are handled by `services/authService.js`, `services/userService.js`, and `services/adminService.js`. Dashboard aggregation and outbound notification responsibilities sit in `services/dashboardService.js` and `services/notificationService.js`.

#### Persistence and core entities
The data model is document/model-oriented, with database setup centralized in `config/db.js`. Core persisted entities are incidents, users, categories, comments, attachments, priorities, and audit records:
`models/Incident.js`, `models/User.js`, `models/Category.js`, `models/Comment.js`, `models/Attachment.js`, `models/Priority.js`, and `models/ActivityLog.js`.

The principal data flow is request → middleware → route/controller → service → model/database, with service results returned through controllers and failures routed to centralized error handling.

#### Incident lifecycle, SLA, and auditing
Incident handling is the architectural center: creation and updates pass through incident validation (`validators/incidentValidator.js`), are processed by `controllers/incidentController.js` and `services/incidentService.js`, and persist through `models/Incident.js`. SLA calculation is isolated in `utils/calculateSLA.js`. Activity changes are recorded through `utils/activityLogger.js` and `services/activityService.js` into `models/ActivityLog.js`; comments and attachments extend the incident record via their own models/services.

#### Background and external-facing operations
`jobs/escalationJob.js` is the asynchronous control path for escalation/SLA-related processing, independent of synchronous API requests. Notifications are abstracted by `services/notificationService.js`, creating a boundary for external delivery providers. File uploads cross a filesystem boundary through `middlewares/uploadMiddleware.js` into `uploads/`. API documentation configuration is present at `config/swagger.js`.

#### Runtime and operational boundaries
The runtime is a JavaScript/Node.js service (`index.js`, `package.json`). Database connectivity is encapsulated by `config/db.js`; callers should not spread database initialization into controllers or routes. Operational observability is split between request logging (`middlewares/morganMiddleware.js`), application logging (`utils/logger.js`), activity auditing, and a dedicated health endpoint (`routes/healthRoutes.js`).

Main entry points: [`routes/incidentRoutes.js`](https://github.com/rajappan47/incident-management-portal-backend/blob/main/routes/incidentRoutes.js) (API routes), [`services/incidentService.js`](https://github.com/rajappan47/incident-management-portal-backend/blob/main/services/incidentService.js) (Incident service), [`models/Incident.js`](https://github.com/rajappan47/incident-management-portal-backend/blob/main/models/Incident.js) (Core models), [`middlewares/authMiddleware.js`](https://github.com/rajappan47/incident-management-portal-backend/blob/main/middlewares/authMiddleware.js) (Request middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app{{"Node application<br/>Node.js runtime<br/>[index.js]"}}
end

subgraph group_http["HTTP boundary"]
  node_routes["API routes<br/>route modules<br/>[incidentRoutes.js]"]
  node_middleware["Request middleware<br/>cross-cutting middleware<br/>[authMiddleware.js]"]
  node_incident_validator["Incident validation<br/>validator"]
  node_incident_controller["Incident controller"]
  node_identity_controllers["Identity controllers<br/>[authController.js]"]
  node_ops_controllers["Operational controllers"]
end

subgraph group_domain["Domain services"]
  node_incident_service["Incident service<br/>workflow service<br/>[incidentService.js]"]
  node_support_services["Incident support services<br/>domain services<br/>[commentService.js]"]
  node_identity_services["Identity services<br/>domain services<br/>[authService.js]"]
  node_dashboard_service["Dashboard service<br/>aggregation service"]
  node_notification_service["Notification service<br/>delivery boundary"]
  node_sla["SLA calculation<br/>domain utility<br/>[calculateSLA.js]"]
  node_activity_logger["Activity logger<br/>audit utility<br/>[activityLogger.js]"]
end

subgraph group_data["Persistence &amp; operations"]
  node_db[("Database connection<br/>database setup<br/>[db.js]")]
  node_core_models[("Core models<br/>document models<br/>[Incident.js]")]
  node_uploads["Upload storage<br/>filesystem boundary"]
  node_escalation_job["Escalation job<br/>background job<br/>[escalationJob.js]"]
  node_app_logger["Application logger<br/>observability utility<br/>[logger.js]"]
end

node_app -->|"initializes"| node_db
node_app -->|"mounts"| node_routes
node_app -->|"installs"| node_middleware
node_middleware -->|"enforces before"| node_routes
node_middleware -->|"stores uploads"| node_uploads
node_middleware -->|"request logging"| node_app_logger
node_routes -->|"validates incidents"| node_incident_validator
node_routes -->|"dispatches"| node_incident_controller
node_routes -->|"dispatches"| node_identity_controllers
node_routes -->|"dispatches"| node_ops_controllers
node_incident_controller -->|"delegates"| node_incident_service
node_identity_controllers -->|"delegates"| node_identity_services
node_ops_controllers -->|"delegates"| node_dashboard_service
node_incident_service -->|"calculates SLA"| node_sla
node_incident_service -->|"uses comments and audit"| node_support_services
node_incident_service -->|"persists incidents"| node_core_models
node_support_services -->|"records changes"| node_activity_logger
node_activity_logger -->|"writes audit records"| node_core_models
node_support_services -->|"persists related entities"| node_core_models
node_identity_services -->|"persists users"| node_core_models
node_dashboard_service -->|"aggregates"| node_core_models
node_notification_service -.->|"supports lifecycle alerts"| node_incident_service
node_escalation_job -.->|"processes escalation"| node_incident_service
node_escalation_job -.->|"sends escalation alerts"| node_notification_service
node_core_models -->|"uses"| node_db

click node_app "https://github.com/rajappan47/incident-management-portal-backend/blob/main/index.js"
click node_routes "https://github.com/rajappan47/incident-management-portal-backend/blob/main/routes/incidentRoutes.js"
click node_middleware "https://github.com/rajappan47/incident-management-portal-backend/blob/main/middlewares/authMiddleware.js"
click node_incident_validator "https://github.com/rajappan47/incident-management-portal-backend/blob/main/validators/incidentValidator.js"
click node_incident_controller "https://github.com/rajappan47/incident-management-portal-backend/blob/main/controllers/incidentController.js"
click node_identity_controllers "https://github.com/rajappan47/incident-management-portal-backend/blob/main/controllers/authController.js"
click node_ops_controllers "https://github.com/rajappan47/incident-management-portal-backend/blob/main/controllers/dashboardController.js"
click node_incident_service "https://github.com/rajappan47/incident-management-portal-backend/blob/main/services/incidentService.js"
click node_support_services "https://github.com/rajappan47/incident-management-portal-backend/blob/main/services/commentService.js"
click node_identity_services "https://github.com/rajappan47/incident-management-portal-backend/blob/main/services/authService.js"
click node_dashboard_service "https://github.com/rajappan47/incident-management-portal-backend/blob/main/services/dashboardService.js"
click node_notification_service "https://github.com/rajappan47/incident-management-portal-backend/blob/main/services/notificationService.js"
click node_sla "https://github.com/rajappan47/incident-management-portal-backend/blob/main/utils/calculateSLA.js"
click node_activity_logger "https://github.com/rajappan47/incident-management-portal-backend/blob/main/utils/activityLogger.js"
click node_db "https://github.com/rajappan47/incident-management-portal-backend/blob/main/config/db.js"
click node_core_models "https://github.com/rajappan47/incident-management-portal-backend/blob/main/models/Incident.js"
click node_escalation_job "https://github.com/rajappan47/incident-management-portal-backend/blob/main/jobs/escalationJob.js"
click node_app_logger "https://github.com/rajappan47/incident-management-portal-backend/blob/main/utils/logger.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_app toneBlue
class node_routes,node_middleware,node_incident_validator,node_incident_controller,node_identity_controllers,node_ops_controllers toneAmber
class node_incident_service,node_support_services,node_identity_services,node_dashboard_service,node_notification_service,node_sla,node_activity_logger toneMint
class node_db,node_core_models,node_uploads,node_escalation_job,node_app_logger toneRose
```

## Components

### Runtime

- [Node application](https://github.com/rajappan47/incident-management-portal-backend/blob/main/index.js): Node.js runtime · Application startup and composition root. · `index.js`

### HTTP boundary

- [API routes](https://github.com/rajappan47/incident-management-portal-backend/blob/main/routes/incidentRoutes.js): route modules · Incident, identity, dashboard, and health endpoints. · `routes/incidentRoutes.js`
- [Request middleware](https://github.com/rajappan47/incident-management-portal-backend/blob/main/middlewares/authMiddleware.js): cross-cutting middleware · Auth, roles, validation, rate limits, uploads, logging, and errors. · `middlewares/authMiddleware.js`
- [Incident validation](https://github.com/rajappan47/incident-management-portal-backend/blob/main/validators/incidentValidator.js): validator · `validators/incidentValidator.js`
- [Incident controller](https://github.com/rajappan47/incident-management-portal-backend/blob/main/controllers/incidentController.js): controller · `controllers/incidentController.js`
- [Identity controllers](https://github.com/rajappan47/incident-management-portal-backend/blob/main/controllers/authController.js): controllers · Authentication and user administration HTTP handling. · `controllers/authController.js`
- [Operational controllers](https://github.com/rajappan47/incident-management-portal-backend/blob/main/controllers/dashboardController.js): controllers · Dashboard and health HTTP handling. · `controllers/dashboardController.js`

### Domain services

- [Incident service](https://github.com/rajappan47/incident-management-portal-backend/blob/main/services/incidentService.js): workflow service · Owns incident lifecycle processing. · `services/incidentService.js`
- [Incident support services](https://github.com/rajappan47/incident-management-portal-backend/blob/main/services/commentService.js): domain services · Comments, categories, and activity operations. · `services/commentService.js`
- [Identity services](https://github.com/rajappan47/incident-management-portal-backend/blob/main/services/authService.js): domain services · Authentication, users, and administration. · `services/authService.js`
- [Dashboard service](https://github.com/rajappan47/incident-management-portal-backend/blob/main/services/dashboardService.js): aggregation service · `services/dashboardService.js`
- [Notification service](https://github.com/rajappan47/incident-management-portal-backend/blob/main/services/notificationService.js): delivery boundary · Abstracts outbound notification providers. · `services/notificationService.js`
- [SLA calculation](https://github.com/rajappan47/incident-management-portal-backend/blob/main/utils/calculateSLA.js): domain utility · `utils/calculateSLA.js`
- [Activity logger](https://github.com/rajappan47/incident-management-portal-backend/blob/main/utils/activityLogger.js): audit utility · `utils/activityLogger.js`

### Persistence & operations

- [Database connection](https://github.com/rajappan47/incident-management-portal-backend/blob/main/config/db.js): database setup · Centralized database connectivity. · `config/db.js`
- [Core models](https://github.com/rajappan47/incident-management-portal-backend/blob/main/models/Incident.js): document models · Incidents, users, categories, comments, attachments, priorities, and audit records. · `models/Incident.js`
- **Upload storage**: filesystem boundary
- [Escalation job](https://github.com/rajappan47/incident-management-portal-backend/blob/main/jobs/escalationJob.js): background job · Asynchronous SLA and escalation processing. · `jobs/escalationJob.js`
- [Application logger](https://github.com/rajappan47/incident-management-portal-backend/blob/main/utils/logger.js): observability utility · `utils/logger.js`

## Connections

- Node application → Database connection: initializes
- Node application → API routes: mounts
- Node application → Request middleware: installs
- Request middleware → API routes: enforces before
- Request middleware → Upload storage: stores uploads
- Request middleware → Application logger: request logging
- API routes → Incident validation: validates incidents
- API routes → Incident controller: dispatches
- API routes → Identity controllers: dispatches
- API routes → Operational controllers: dispatches
- Incident controller → Incident service: delegates
- Identity controllers → Identity services: delegates
- Operational controllers → Dashboard service: delegates
- Incident service → SLA calculation: calculates SLA
- Incident service → Incident support services: uses comments and audit
- Incident service → Core models: persists incidents
- Incident support services → Activity logger: records changes
- Activity logger → Core models: writes audit records
- Incident support services → Core models: persists related entities
- Identity services → Core models: persists users
- Dashboard service → Core models: aggregates
- Notification service → Incident service: supports lifecycle alerts
- Escalation job → Incident service: processes escalation
- Escalation job → Notification service: sends escalation alerts
- Core models → Database connection: uses