# miguelba18/sideo-backend architecture

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

- Interactive diagram: https://gitdiagram.com/miguelba18/sideo-backend
- Repository: https://github.com/miguelba18/sideo-backend

## Overview

1. This is a NestJS TypeScript backend organized as a modular monolith. The application boots from `src/main.ts`, loads the root `AppModule`, and exposes feature controllers through Nest’s dependency-injection and module system.

2. The top-level architecture is split into shared infrastructure in `src/common`, configuration in `src/config`, persistence/bootstrap data in `src/database`, and business features under `src/modules`. Each feature module follows the same shape: controller, service, DTOs, and entity models.

3. `src/common` contains the cross-cutting security layer. It defines custom decorators for current user, roles, and permissions, plus guards for JWT authentication, role-based access, permission checks, and subscription checks. This is the main enforcement boundary around protected routes.

4. Authentication is handled by `src/modules/auth`. It provides login, registration, profile completion, and password-change flows, backed by a JWT strategy. This module is the entry point for identity and token issuance, and its controller/service likely coordinate with the users and roles modules.

5. User and access control data is separated into `users` and `roles`. The roles module models roles, permissions, and role-permission relations, while the users module manages evaluator/user profiles. The database seeds include initial roles/permissions and a superadmin account, indicating the app expects a preloaded authorization baseline.

6. Business data appears to center on organizational management: `companies`, `employees`, and `subscriptions`. Companies and employees are separate domain modules, while subscriptions track plan/state changes such as creation, renewal, upgrade, and status. The subscription guard suggests plan state directly gates some routes or features.

7. Evaluations are a major domain subsystem. `src/modules/evaluations` stores evaluation records plus a detail entity, and includes a `rosa-calculator` helper, which implies business logic for scoring or assessment computation is encapsulated here rather than in controllers.

8. Reporting and dashboards are read-oriented aggregation layers. `reports` likely produces persisted or generated reports from the core domain data, while `dashboard` likely collects summary metrics for the UI/API consumer. These modules sit on top of the core entities rather than owning primary workflow state.

9. `mailer` is a separate utility module for outbound email workflows. It has its own DTOs, entity, controller, service, and module, so email delivery is treated as an application boundary rather than embedded inside auth or subscriptions.

10. The codebase is entity-driven and DTO-based throughout. DTOs define request/command payloads at the API boundary, entities define persistence models, and services hold the domain/application logic. Controllers are thin adapters that translate HTTP requests into service calls.

11. The persistence layer is configured via `src/config/database.config.ts` and initialized with seed scripts under `src/database/seeds`. Even though the exact ORM is not shown here, the presence of entities and seeds indicates a database-backed architecture with bootstrap data for authorization and admin setup.

12. Testing is built into the structure with unit specs alongside each module and an E2E test suite under `test/`. Deployment artifacts like `Dockerfile` and `procfile` suggest the service is intended to run as a containerized Node/Nest backend in production.

Main entry points: [`src/app.module.ts`](https://github.com/miguelba18/sideo-backend/blob/main/src/app.module.ts) (App module), [`src/modules/auth/auth.module.ts`](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/auth/auth.module.ts) (Auth), [`src/modules/evaluations/evaluations.module.ts`](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/evaluations/evaluations.module.ts) (Evaluations), [`src/modules/reports/reports.module.ts`](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/reports/reports.module.ts) (Reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_main(("main<br/>bootstrap<br/>[main.ts]"))
  node_appmodule["App module<br/>nest module<br/>[app.module.ts]"]
end

subgraph group_shared["Shared"]
  node_security{{"Security<br/>guards+decorators"}}
end

subgraph group_data["Data"]
  node_configdb["DB config<br/>[database.config.ts]"]
  node_rolesseed["Auth seed"]
  node_adminseed["Superadmin seed<br/>[superadmin.seed.ts]"]
end

subgraph group_features["Features"]
  node_authmod["Auth<br/>[auth.module.ts]"]
  node_authcontroller["Auth API<br/>controller<br/>[auth.controller.ts]"]
  node_authservice["Auth service<br/>[auth.service.ts]"]
  node_jwtstrategy["JWT strategy<br/>[jwt.strategy.ts]"]
  node_usersmod["Users<br/>[users.module.ts]"]
  node_rolesmod["Roles<br/>[roles.module.ts]"]
  node_companiesmod["Companies<br/>[company.module.ts]"]
  node_employeesmod["Employees"]
  node_subsmod["Subscriptions"]
  node_evalmod["Evaluations"]
  node_rosacalculator["Rosa calc<br/>scoring helper<br/>[rosa-calculator.ts]"]
  node_reportsmod["Reports<br/>[reports.module.ts]"]
  node_dashboardmod["Dashboard"]
  node_mailermod["Mailer<br/>[mailer.module.ts]"]
end

node_main -->|"boots"| node_appmodule
node_appmodule -->|"uses"| node_security
node_appmodule -->|"configures"| node_configdb
node_appmodule -.->|"seeds"| node_rolesseed
node_appmodule -.->|"seeds"| node_adminseed
node_appmodule -->|"imports"| node_authmod
node_appmodule -->|"imports"| node_usersmod
node_appmodule -->|"imports"| node_rolesmod
node_appmodule -->|"imports"| node_companiesmod
node_appmodule -->|"imports"| node_employeesmod
node_appmodule -->|"imports"| node_subsmod
node_appmodule -->|"imports"| node_evalmod
node_appmodule -->|"imports"| node_reportsmod
node_appmodule -->|"imports"| node_dashboardmod
node_appmodule -->|"imports"| node_mailermod
node_authmod -->|"exposes"| node_authcontroller
node_authmod -->|"provides"| node_authservice
node_authmod -->|"uses"| node_jwtstrategy
node_authservice -.->|"depends on"| node_usersmod
node_authservice -.->|"depends on"| node_rolesmod
node_usersmod -.->|"relates to"| node_rolesmod
node_rolesmod -.->|"feeds"| node_security
node_subsmod -.->|"gates"| node_security
node_evalmod -->|"uses"| node_rosacalculator
node_evalmod -.->|"depends on"| node_companiesmod
node_evalmod -.->|"depends on"| node_employeesmod
node_reportsmod -.->|"reads"| node_evalmod
node_reportsmod -.->|"reads"| node_companiesmod
node_dashboardmod -.->|"summarizes"| node_reportsmod
node_mailermod -.->|"supports"| node_authmod
node_mailermod -.->|"supports"| node_subsmod

click node_main "https://github.com/miguelba18/sideo-backend/blob/main/src/main.ts"
click node_appmodule "https://github.com/miguelba18/sideo-backend/blob/main/src/app.module.ts"
click node_security "https://github.com/miguelba18/sideo-backend/tree/main/src/common"
click node_configdb "https://github.com/miguelba18/sideo-backend/blob/main/src/config/database.config.ts"
click node_rolesseed "https://github.com/miguelba18/sideo-backend/blob/main/src/database/seeds/roles-permissions.seed.ts"
click node_adminseed "https://github.com/miguelba18/sideo-backend/blob/main/src/database/seeds/superadmin.seed.ts"
click node_authmod "https://github.com/miguelba18/sideo-backend/blob/main/src/modules/auth/auth.module.ts"
click node_authcontroller "https://github.com/miguelba18/sideo-backend/blob/main/src/modules/auth/auth.controller.ts"
click node_authservice "https://github.com/miguelba18/sideo-backend/blob/main/src/modules/auth/auth.service.ts"
click node_jwtstrategy "https://github.com/miguelba18/sideo-backend/blob/main/src/modules/auth/strategies/jwt.strategy.ts"
click node_usersmod "https://github.com/miguelba18/sideo-backend/blob/main/src/modules/users/users.module.ts"
click node_rolesmod "https://github.com/miguelba18/sideo-backend/blob/main/src/modules/roles/roles.module.ts"
click node_companiesmod "https://github.com/miguelba18/sideo-backend/blob/main/src/modules/companies/company.module.ts"
click node_employeesmod "https://github.com/miguelba18/sideo-backend/blob/main/src/modules/employees/employees.module.ts"
click node_subsmod "https://github.com/miguelba18/sideo-backend/blob/main/src/modules/subscriptions/subscriptions.module.ts"
click node_evalmod "https://github.com/miguelba18/sideo-backend/blob/main/src/modules/evaluations/evaluations.module.ts"
click node_rosacalculator "https://github.com/miguelba18/sideo-backend/blob/main/src/modules/evaluations/rosa/rosa-calculator.ts"
click node_reportsmod "https://github.com/miguelba18/sideo-backend/blob/main/src/modules/reports/reports.module.ts"
click node_dashboardmod "https://github.com/miguelba18/sideo-backend/blob/main/src/modules/dashboard/dashboard.module.ts"
click node_mailermod "https://github.com/miguelba18/sideo-backend/blob/main/src/modules/mailer/mailer.module.ts"

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_appmodule toneBlue
class node_security toneAmber
class node_configdb,node_rolesseed,node_adminseed toneMint
class node_authmod,node_authcontroller,node_authservice,node_jwtstrategy,node_usersmod,node_rolesmod,node_companiesmod,node_employeesmod,node_subsmod,node_evalmod,node_rosacalculator,node_reportsmod,node_dashboardmod,node_mailermod toneRose
```

## Components

### Bootstrap

Application entrypoint and Nest root wiring

- [main](https://github.com/miguelba18/sideo-backend/blob/main/src/main.ts): bootstrap · Starts Nest and loads the app module · `src/main.ts`
- [App module](https://github.com/miguelba18/sideo-backend/blob/main/src/app.module.ts): nest module · Root composition of the monolith · `src/app.module.ts`

### Shared

Cross-cutting guards, decorators, and enums

- [Security](https://github.com/miguelba18/sideo-backend/tree/main/src/common): guards+decorators · Current-user, roles, permissions, JWT, and subscription enforcement · `src/common`

### Data

Configuration, database setup, and seed data

- [DB config](https://github.com/miguelba18/sideo-backend/blob/main/src/config/database.config.ts): config · Database connection settings · `src/config/database.config.ts`
- [Auth seed](https://github.com/miguelba18/sideo-backend/blob/main/src/database/seeds/roles-permissions.seed.ts): seed · Initial roles and permissions bootstrap data · `src/database/seeds/roles-permissions.seed.ts`
- [Superadmin seed](https://github.com/miguelba18/sideo-backend/blob/main/src/database/seeds/superadmin.seed.ts): seed · Bootstrap admin account · `src/database/seeds/superadmin.seed.ts`

### Features

Business modules under Nest DI

- [Auth](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/auth/auth.module.ts): module · Login, registration, profile completion, and password change · `src/modules/auth/auth.module.ts`
- [Auth API](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/auth/auth.controller.ts): controller · HTTP entrypoint for identity flows · `src/modules/auth/auth.controller.ts`
- [Auth service](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/auth/auth.service.ts): service · Authentication and token orchestration · `src/modules/auth/auth.service.ts`
- [JWT strategy](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/auth/strategies/jwt.strategy.ts): strategy · Token validation strategy · `src/modules/auth/strategies/jwt.strategy.ts`
- [Users](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/users/users.module.ts): module · Evaluator and profile management · `src/modules/users/users.module.ts`
- [Roles](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/roles/roles.module.ts): module · Roles, permissions, and role-permission relations · `src/modules/roles/roles.module.ts`
- [Companies](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/companies/company.module.ts): module · Company domain management · `src/modules/companies/company.module.ts`
- [Employees](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/employees/employees.module.ts): module · Employee domain management · `src/modules/employees/employees.module.ts`
- [Subscriptions](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/subscriptions/subscriptions.module.ts): module · Plan lifecycle and status management · `src/modules/subscriptions/subscriptions.module.ts`
- [Evaluations](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/evaluations/evaluations.module.ts): module · Evaluation records and scoring workflows · `src/modules/evaluations/evaluations.module.ts`
- [Rosa calc](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/evaluations/rosa/rosa-calculator.ts): scoring helper · Evaluation scoring logic · `src/modules/evaluations/rosa/rosa-calculator.ts`
- [Reports](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/reports/reports.module.ts): module · Read-oriented report generation · `src/modules/reports/reports.module.ts`
- [Dashboard](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/dashboard/dashboard.module.ts): module · Aggregated summary metrics · `src/modules/dashboard/dashboard.module.ts`
- [Mailer](https://github.com/miguelba18/sideo-backend/blob/main/src/modules/mailer/mailer.module.ts): module · Outbound email workflows · `src/modules/mailer/mailer.module.ts`

## Connections

- main → App module: boots · Nest application starts from the root module
- App module → Security: uses · Shared guards and decorators protect feature routes
- App module → DB config: configures · Wires database connection settings
- App module → Auth seed: seeds · Bootstraps authorization baseline
- App module → Superadmin seed: seeds · Bootstraps the superadmin account
- App module → Auth: imports · Registers auth feature
- App module → Users: imports · Registers users feature
- App module → Roles: imports · Registers roles feature
- App module → Companies: imports · Registers companies feature
- App module → Employees: imports · Registers employees feature
- App module → Subscriptions: imports · Registers subscriptions feature
- App module → Evaluations: imports · Registers evaluations feature
- App module → Reports: imports · Registers reports feature
- App module → Dashboard: imports · Registers dashboard feature
- App module → Mailer: imports · Registers mailer feature
- Auth → Auth API: exposes · HTTP API surface
- Auth → Auth service: provides · Business logic for auth flows
- Auth → JWT strategy: uses · Validates bearer tokens
- Auth service → Users: depends on · Coordinates identity/profile data
- Auth service → Roles: depends on · Uses roles and permissions for access-related flows
- Users → Roles: relates to · User profiles intersect with access control
- Roles → Security: feeds · Role and permission checks are enforced by shared guards
- Subscriptions → Security: gates · Subscription guard protects feature access
- Evaluations → Rosa calc: uses · Encapsulates scoring logic
- Evaluations → Companies: depends on · Evaluations likely reference company context
- Evaluations → Employees: depends on · Evaluations likely reference employee context
- Reports → Evaluations: reads · Reports aggregate evaluation data
- Reports → Companies: reads · Reports aggregate company data
- Dashboard → Reports: summarizes · Dashboard presents higher-level metrics
- Mailer → Auth: supports · Email flows can back auth workflows
- Mailer → Subscriptions: supports · Email flows can back subscription workflows
