# oussema-ghbara/cmms architecture

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

- Interactive diagram: https://gitdiagram.com/oussema-ghbara/cmms
- Repository: https://github.com/oussema-ghbara/cmms

## Overview

1. This is a Turborepo monorepo with two active applications: `apps/backend` (NestJS API) and `apps/web` (Next.js App Router). There is also a planned Expo mobile app, but it is not started, so it does not affect the current runtime architecture.

2. The repository is organized around a clean backend boundary: NestJS follows `Module -> Controller -> Service -> Repository`. Controllers are thin HTTP adapters, services hold business logic, and repositories encapsulate Prisma-backed persistence. This pattern is repeated across the major domains.

3. The backend is split into domain modules that map closely to the product surface: `auth`, `users`, `assets`, `inventory`, `work-orders`, `preventive-plans`, `reports`, `notifications`, `admin`, `mail`, `storage`, `system-config`, `job-logger`, plus infrastructure modules like `prisma` and `redis`. Each module owns its DTOs, controllers, services, and any domain-specific jobs or helper services.

4. PostgreSQL is the primary system of record, accessed through Prisma in `packages/db`. The schema, migrations, and seed data live outside the apps, which makes the database layer a shared package rather than an app-local concern. Backend repositories read/write through the Prisma service, and seed data provides the standard dev accounts and system configuration.

5. Redis is used as the runtime backbone for asynchronous and stateful backend concerns: BullMQ queues, token/session revocation, scheduled jobs, and other background processors. This means request/response paths are separated from long-running work like PDF generation, reminder emails, plan generation, and expiry notifications.

6. File and document handling is delegated to MinIO via the `storage` module. The architecture treats documents as attached assets across several domains: work-order reports, asset documents, preventive-plan documents, part documents, and certificates. The storage layer is a distinct boundary from business logic and persistence.

7. Email is centralized in the `mail` module. The backend uses Nodemailer plus Handlebars templates, but domain code never sends mail directly; it enqueues through the mail service. This is important architecturally because notification delivery is decoupled from the business action that triggered it.

8. Real-time updates are handled by Socket.io through the `notifications` module, with JWT authentication at connect time. The notification subsystem fans out in-app and email alerts to role-based audiences such as admins and supervisors, and the web app consumes those live pushes to update unread badges and navigate to deep-linked entities.

9. Auth is a first-class boundary. It uses JWT with refresh token rotation, Redis-backed revocation, inactivity timeout, and account setup / password recovery flows. Global `JwtAuthGuard` and `RolesGuard` enforce access control across the API, with method-level decorators like `@Public()` and `@Roles()` controlling exceptions and role restrictions.

10. The biggest business domain is work orders. It contains its own state machine, assignment and validation logic, hold management, checklist handling, escalation rules, follow-up generation, reporting, cost calculations, analytics helpers, and several scheduled jobs. This module is not just CRUD; it is the operational core where multiple sub-services coordinate around workflow state transitions.

11. Other major domains have similar but narrower flows: `assets` manages locations, categories, assets, certificates, and documents; `inventory` manages parts, stock movements, and part requests; `preventive-plans` manages plan templates and BullMQ-generated work orders; `reports` handles problem report lifecycle and conversion into work orders; `admin` provides audit/logging/system-health views; `job-logger` records scheduled job execution and failure signals. These are separate bounded contexts, but they exchange data through shared enums and cross-module service calls.

12. `packages/shared` holds the domain enums and shared types used by both backend and web. This keeps role names, status values, notification types, and other cross-app contracts consistent, and avoids duplicating domain vocabulary in two codebases.

13. The web app is a Next.js front end organized by route groups: authentication screens, protected role-based workspaces, and a sandbox area. The protected area is segmented by operational persona (`admin`, `supervisor`, `storekeeper`, `profile`), which mirrors the backend authorization model and the product’s functional separation.

14. The frontend architecture is state-and-data oriented rather than purely presentational. `apps/web/lib` contains API wrappers and domain-specific client utilities; `apps/web/store` uses Zustand for auth and notifications; React Query is used for server state; and `useSocket` / `use-auth-init` wire in session and live notification behavior. UI is composed from reusable shadcn-style components in `components/ui` plus domain boards, tables, dialogs, and detail panels.

15. End-to-end data flow is typically: user action in the web UI -> client API wrapper in `apps/web/lib` -> NestJS controller -> service -> repository/queue/storage/mail/notification subsystem -> PostgreSQL/Redis/MinIO/SMTP/Socket.io -> updated UI state. Most complex operations are intentionally asynchronous when they involve emails, PDFs, scheduled jobs, or fan-out notifications.

16. The repository also reflects strong operational discipline: Docker Compose provides PostgreSQL, Redis, MinIO, and MailHog for local development; Swagger is exposed by the backend; and both apps have extensive unit/integration tests around business rules, controllers, and job processors. This makes the system diagrammatically a modular monolith with asynchronous workers and external service dependencies, not a simple CRUD web app.

Main entry points: [`apps/backend/src/main.ts`](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/main.ts) (Backend API), [`apps/backend/src/work-orders/work-orders.module.ts`](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/work-orders/work-orders.module.ts) (Work orders), [`apps/backend/src/prisma/prisma.module.ts`](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/prisma/prisma.module.ts) (Prisma), [`apps/backend/src/redis/redis.module.ts`](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/redis/redis.module.ts) (Redis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Applications"]
  node_apps_backend["Backend API<br/>NestJS app<br/>[main.ts]"]
  node_apps_web["Web UI<br/>Next.js app<br/>[layout.tsx]"]
end

subgraph group_backend["Backend domains"]
  node_backend_auth["Auth<br/>security module<br/>[auth.module.ts]"]
  node_backend_work_orders["Work orders<br/>workflow module"]
  node_backend_assets["Assets<br/>asset module<br/>[assets.module.ts]"]
  node_backend_inventory["Inventory<br/>stock module"]
  node_backend_preventive["Preventive plans<br/>planning module"]
  node_backend_reports["Reports<br/>reporting module<br/>[reports.module.ts]"]
  node_backend_notifications["Notifications<br/>realtime module"]
  node_backend_mail["Mail<br/>[mail.module.ts]"]
  node_backend_storage["Storage<br/>document module<br/>[storage.module.ts]"]
  node_backend_admin["Admin<br/>ops module<br/>[admin.module.ts]"]
  node_backend_users["Users<br/>profile module<br/>[users.module.ts]"]
  node_backend_job_logger["Job logger<br/>ops module"]
  node_backend_prisma[("Prisma<br/>db adapter<br/>[prisma.module.ts]")]
  node_backend_redis[("Redis<br/>cache/queue module<br/>[redis.module.ts]")]
end

subgraph group_web["Web app"]
  node_web_routes["Route groups<br/>routing layer"]
  node_web_state["State hooks<br/>client state<br/>[use-auth-init.ts]"]
  node_web_api["API layer<br/>client data<br/>[api.ts]"]
  node_web_ui["UI boards<br/>component layer"]
end

subgraph group_packages["Shared packages"]
  node_shared_contracts["Shared contracts<br/>types/enums<br/>[index.ts]"]
  node_db_schema[("DB schema<br/>Prisma schema<br/>[schema.prisma]")]
end

subgraph group_infra["Runtime infra"]
  node_docker_services[("Dev services<br/>local infra<br/>[docker-compose.yml]")]
end

node_apps_backend -->|"loads"| node_backend_auth
node_apps_backend -->|"loads"| node_backend_work_orders
node_apps_backend -->|"loads"| node_backend_assets
node_apps_backend -->|"loads"| node_backend_inventory
node_apps_backend -->|"loads"| node_backend_preventive
node_apps_backend -->|"loads"| node_backend_reports
node_apps_backend -->|"loads"| node_backend_notifications
node_apps_backend -->|"loads"| node_backend_mail
node_apps_backend -->|"loads"| node_backend_storage
node_apps_backend -->|"loads"| node_backend_admin
node_apps_backend -->|"loads"| node_backend_users
node_apps_backend -->|"loads"| node_backend_job_logger
node_backend_auth -->|"uses"| node_backend_redis
node_backend_work_orders -->|"persists via"| node_backend_prisma
node_backend_assets -->|"persists via"| node_backend_prisma
node_backend_inventory -->|"persists via"| node_backend_prisma
node_backend_reports -->|"persists via"| node_backend_prisma
node_backend_preventive -->|"queues"| node_backend_redis
node_backend_work_orders -->|"queues"| node_backend_redis
node_backend_mail -->|"queues"| node_backend_redis
node_backend_notifications -->|"uses"| node_backend_redis
node_backend_storage -->|"stores files in"| node_docker_services
node_backend_prisma -->|"maps to"| node_db_schema
node_web_routes -->|"uses"| node_web_api
node_web_routes -->|"hydrates"| node_web_state
node_web_routes -->|"renders"| node_web_ui
node_web_api -->|"types"| node_shared_contracts
node_backend_auth -->|"shares"| node_shared_contracts
node_backend_notifications -->|"shares"| node_shared_contracts
node_backend_work_orders -->|"emits"| node_backend_notifications
node_backend_work_orders -->|"enqueues"| node_backend_mail
node_backend_reports -->|"converts to"| node_backend_work_orders
node_backend_assets -->|"attaches"| node_backend_storage
node_backend_preventive -->|"creates"| node_backend_work_orders
node_backend_admin -->|"reads"| node_backend_job_logger

click node_apps_backend "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/main.ts"
click node_apps_web "https://github.com/oussema-ghbara/cmms/blob/master/apps/web/app/layout.tsx"
click node_backend_auth "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/auth/auth.module.ts"
click node_backend_work_orders "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/work-orders/work-orders.module.ts"
click node_backend_assets "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/assets/assets.module.ts"
click node_backend_inventory "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/inventory/inventory.module.ts"
click node_backend_preventive "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/preventive-plans/preventive-plans.module.ts"
click node_backend_reports "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/reports/reports.module.ts"
click node_backend_notifications "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/notifications/notifications.module.ts"
click node_backend_mail "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/mail/mail.module.ts"
click node_backend_storage "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/storage/storage.module.ts"
click node_backend_admin "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/admin/admin.module.ts"
click node_backend_users "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/users/users.module.ts"
click node_backend_job_logger "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/job-logger/job-logger.module.ts"
click node_backend_prisma "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/prisma/prisma.module.ts"
click node_backend_redis "https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/redis/redis.module.ts"
click node_web_routes "https://github.com/oussema-ghbara/cmms/tree/master/apps/web/app"
click node_web_state "https://github.com/oussema-ghbara/cmms/blob/master/apps/web/hooks/use-auth-init.ts"
click node_web_api "https://github.com/oussema-ghbara/cmms/blob/master/apps/web/lib/api.ts"
click node_web_ui "https://github.com/oussema-ghbara/cmms/blob/master/apps/web/components/supervisor/work-orders-board.tsx"
click node_shared_contracts "https://github.com/oussema-ghbara/cmms/blob/master/packages/shared/src/index.ts"
click node_db_schema "https://github.com/oussema-ghbara/cmms/blob/master/packages/db/prisma/schema.prisma"
click node_docker_services "https://github.com/oussema-ghbara/cmms/blob/master/docker-compose.yml"

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_apps_backend,node_apps_web toneBlue
class node_backend_auth,node_backend_work_orders,node_backend_assets,node_backend_inventory,node_backend_preventive,node_backend_reports,node_backend_notifications,node_backend_mail,node_backend_storage,node_backend_admin,node_backend_users,node_backend_job_logger,node_backend_prisma,node_backend_redis toneAmber
class node_web_routes,node_web_state,node_web_api,node_web_ui toneMint
class node_shared_contracts,node_db_schema toneRose
class node_docker_services toneIndigo
```

## Components

### Applications

Runtime entrypoints for the backend API and web UI.

- [Backend API](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/main.ts): NestJS app · Main HTTP API and background job host. · `apps/backend/src/main.ts`
- [Web UI](https://github.com/oussema-ghbara/cmms/blob/master/apps/web/app/layout.tsx): Next.js app · App Router frontend for role-based workspaces. · `apps/web/app/layout.tsx`

### Backend domains

NestJS modules organized by bounded context and internal workflow.

- [Auth](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/auth/auth.module.ts): security module · JWT login, refresh rotation, setup, recovery, and access control. · `apps/backend/src/auth/auth.module.ts`
- [Work orders](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/work-orders/work-orders.module.ts): workflow module · Core operational workflow with state machine, assignment, validation, holds, reporting, and jobs. · `apps/backend/src/work-orders/work-orders.module.ts`
- [Assets](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/assets/assets.module.ts): asset module · Assets, locations, categories, certificates, and related documents. · `apps/backend/src/assets/assets.module.ts`
- [Inventory](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/inventory/inventory.module.ts): stock module · Parts, stock movements, and part requests. · `apps/backend/src/inventory/inventory.module.ts`
- [Preventive plans](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/preventive-plans/preventive-plans.module.ts): planning module · Plan templates, checklist items, and generated work orders. · `apps/backend/src/preventive-plans/preventive-plans.module.ts`
- [Reports](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/reports/reports.module.ts): reporting module · Problem report lifecycle and conversion into work orders. · `apps/backend/src/reports/reports.module.ts`
- [Notifications](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/notifications/notifications.module.ts): realtime module · Socket.io gateway and notification fan-out. · `apps/backend/src/notifications/notifications.module.ts`
- [Mail](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/mail/mail.module.ts): email module · Central email delivery with templates and queue processor. · `apps/backend/src/mail/mail.module.ts`
- [Storage](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/storage/storage.module.ts): document module · MinIO-backed file and document handling. · `apps/backend/src/storage/storage.module.ts`
- [Admin](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/admin/admin.module.ts): ops module · System health, audit, analytics, and admin controls. · `apps/backend/src/admin/admin.module.ts`
- [Users](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/users/users.module.ts): profile module · User management and notification preferences. · `apps/backend/src/users/users.module.ts`
- [Job logger](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/job-logger/job-logger.module.ts): ops module · Scheduled job execution logging and failure signals. · `apps/backend/src/job-logger/job-logger.module.ts`
- [Prisma](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/prisma/prisma.module.ts): db adapter · Shared database service used by repositories. · `apps/backend/src/prisma/prisma.module.ts`
- [Redis](https://github.com/oussema-ghbara/cmms/blob/master/apps/backend/src/redis/redis.module.ts): cache/queue module · BullMQ, revocation, and background job coordination. · `apps/backend/src/redis/redis.module.ts`

### Web app

Next.js route groups, client state, and UI composition.

- [Route groups](https://github.com/oussema-ghbara/cmms/tree/master/apps/web/app): routing layer · Auth screens, protected role workspaces, and sandbox routes. · `apps/web/app`
- [State hooks](https://github.com/oussema-ghbara/cmms/blob/master/apps/web/hooks/use-auth-init.ts): client state · Auth bootstrap, idle timeout, and socket wiring. · `apps/web/hooks/use-auth-init.ts`
- [API layer](https://github.com/oussema-ghbara/cmms/blob/master/apps/web/lib/api.ts): client data · Typed API wrappers and domain client utilities. · `apps/web/lib/api.ts`
- [UI boards](https://github.com/oussema-ghbara/cmms/blob/master/apps/web/components/supervisor/work-orders-board.tsx): component layer · Role-specific boards, tables, dialogs, and detail panels. · `apps/web/components/supervisor/work-orders-board.tsx`

### Shared packages

Cross-app schema, types, and domain vocabulary.

- [Shared contracts](https://github.com/oussema-ghbara/cmms/blob/master/packages/shared/src/index.ts): types/enums · Cross-app enums and shared types for roles, statuses, and notifications. · `packages/shared/src/index.ts`
- [DB schema](https://github.com/oussema-ghbara/cmms/blob/master/packages/db/prisma/schema.prisma): Prisma schema · PostgreSQL schema, migrations, and seed data. · `packages/db/prisma/schema.prisma`

### Runtime infra

Datastores, queues, storage, and local dev services.

- [Dev services](https://github.com/oussema-ghbara/cmms/blob/master/docker-compose.yml): local infra · PostgreSQL, Redis, MinIO, and MailHog for development. · `docker-compose.yml`

## Connections

- Backend API → Auth: loads · API composition includes auth as a first-class boundary.
- Backend API → Work orders: loads · Work order domain is the operational core.
- Backend API → Assets: loads · Asset lifecycle and document management.
- Backend API → Inventory: loads · Inventory and part request workflows.
- Backend API → Preventive plans: loads · Preventive plan generation and scheduling.
- Backend API → Reports: loads · Problem reports and conversion flow.
- Backend API → Notifications: loads · Realtime notifications gateway.
- Backend API → Mail: loads · Central email delivery boundary.
- Backend API → Storage: loads · File and document storage boundary.
- Backend API → Admin: loads · Admin and operational views.
- Backend API → Users: loads · User profile and preferences.
- Backend API → Job logger: loads · Job execution logging module.
- Auth → Redis: uses · Refresh revocation and inactivity/session state.
- Work orders → Prisma: persists via · Repositories and services read/write through Prisma.
- Assets → Prisma: persists via · Asset records, certificates, and locations.
- Inventory → Prisma: persists via · Parts, stock, and requests.
- Reports → Prisma: persists via · Problem report lifecycle data.
- Preventive plans → Redis: queues · Plan generation and scheduling jobs.
- Work orders → Redis: queues · Async report generation and scheduled reminders.
- Mail → Redis: queues · Mail processor consumes queued messages.
- Notifications → Redis: uses · Notification delivery and async coordination.
- Storage → Dev services: stores files in · MinIO-backed document storage.
- Prisma → DB schema: maps to · Shared PostgreSQL schema and migrations.
- Route groups → API layer: uses · Routes fetch and mutate through typed API wrappers.
- Route groups → State hooks: hydrates · Auth and socket bootstrap for protected areas.
- Route groups → UI boards: renders · Route pages are built from reusable boards and dialogs.
- API layer → Shared contracts: types · Client contracts follow shared enums and DTO-like shapes.
- Auth → Shared contracts: shares · Roles and auth-related enums/types.
- Notifications → Shared contracts: shares · Notification types and payload vocabulary.
- Work orders → Notifications: emits · Workflow events fan out to live updates.
- Work orders → Mail: enqueues · Business events trigger email delivery asynchronously.
- Reports → Work orders: converts to · Accepted reports can become work orders.
- Assets → Storage: attaches · Documents and certificates are stored separately from records.
- Preventive plans → Work orders: creates · Generated plans materialize as work orders.
- Admin → Job logger: reads · Operational views can surface job execution status.
