How oussema-ghbara/cmms works
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: main.ts Backend API · work-orders.module.ts Work orders · prisma.module.ts Prisma · redis.module.ts Redis
Components 23
Applications
Runtime entrypoints for the backend API and web UI.
- Backend API · Main HTTP API and background job host.
apps/backend/src/main.ts - Web UI · App Router frontend for role-based workspaces.
apps/web/app/layout.tsx
Backend domains
NestJS modules organized by bounded context and internal workflow.
- Auth · JWT login, refresh rotation, setup, recovery, and access control.
apps/backend/src/auth/auth.module.ts - Work orders · Core operational workflow with state machine, assignment, validation, holds, reporting, and jobs.
apps/backend/src/work-orders/work-orders.module.ts - Assets · Assets, locations, categories, certificates, and related documents.
apps/backend/src/assets/assets.module.ts - Inventory · Parts, stock movements, and part requests.
apps/backend/src/inventory/inventory.module.ts - Preventive plans · Plan templates, checklist items, and generated work orders.
apps/backend/src/preventive-plans/preventive-plans.module.ts - Reports · Problem report lifecycle and conversion into work orders.
apps/backend/src/reports/reports.module.ts - Notifications · Socket.io gateway and notification fan-out.
apps/backend/src/notifications/notifications.module.ts - Mail · Central email delivery with templates and queue processor.
apps/backend/src/mail/mail.module.ts - Storage · MinIO-backed file and document handling.
apps/backend/src/storage/storage.module.ts - Admin · System health, audit, analytics, and admin controls.
apps/backend/src/admin/admin.module.ts - Users · User management and notification preferences.
apps/backend/src/users/users.module.ts - Job logger · Scheduled job execution logging and failure signals.
apps/backend/src/job-logger/job-logger.module.ts - Prisma · Shared database service used by repositories.
apps/backend/src/prisma/prisma.module.ts - Redis · 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 · Auth screens, protected role workspaces, and sandbox routes.
apps/web/app - State hooks · Auth bootstrap, idle timeout, and socket wiring.
apps/web/hooks/use-auth-init.ts - API layer · Typed API wrappers and domain client utilities.
apps/web/lib/api.ts - UI boards · 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 · Cross-app enums and shared types for roles, statuses, and notifications.
packages/shared/src/index.ts - DB schema · PostgreSQL schema, migrations, and seed data.
packages/db/prisma/schema.prisma
Runtime infra
Datastores, queues, storage, and local dev services.
- Dev services · PostgreSQL, Redis, MinIO, and MailHog for development.
docker-compose.yml
Connections 35
- 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.