nazim1971/node-vms

1. Overall shape: a modular NestJS backend monolith

- This repository is a single NestJS application organized as feature modules, not separate services.

- Each domain area has its own *.module.ts, *.controller.ts, and *.service.ts, with shared cross-cutting concerns under src/common.

- The app exposes HTTP APIs, a WebSocket gateway, and background jobs from the same codebase.

2. Runtime and infrastructure dependencies

- Primary state is in PostgreSQL via Prisma.

- Redis is used for JWT blacklisting, caching, and job/real-time support.

- BullMQ powers scheduled background jobs.

- Socket.IO provides real-time GPS/event broadcasting.

- Logging uses Winston, and the service is configured for standard NestJS production hardening.

3. Bootstrap and request pipeline

- src/main.ts bootstraps the Nest app.

- Requests flow through global concerns before reaching controllers: validation, exception filtering, logging, response shaping, sensitive-field stripping, and auditing.

- The repository strongly suggests a consistent API envelope for successful and error responses, which is important for diagramming the edge of the system.

4. Multi-tenancy is a core architectural boundary

- Every business operation is tenant-scoped; tenant isolation is a first-class rule, not just a data convention.

- Guards such as tenant.guard.ts, plus auth/role/feature guards, enforce access before a controller reaches its service.

- The SUPER_ADMIN role is explicitly exempt from most tenant/feature restrictions, which is an important exception path in the architecture.

5. Identity, authorization, and approval workflow

- The auth module handles login, refresh tokens, tenant registration, and initial super-admin seeding.

- JWT access/refresh tokens and bcrypt are the core identity mechanisms.

- New admin tenants go through an approval flow: pending registration, review in admin-applications, then activation or rejection by SUPER_ADMIN.

- Authorization is layered: authentication, tenant scoping, role checks, and feature access checks.

6. Feature-flag boundary for modules

- feature-access is a platform-level control plane for enabling/disabling tenant modules.

- Feature guards gate entire subsystems such as vehicles, workshop, maintenance, tracking, bookings, fuel, accounting, and reports.

- This means some domain modules are optional per tenant; in a diagram, this should be shown as a policy layer between the API and those feature modules.

7. Core operational domains

- The main business modules are vehicles, drivers, branches, users, tenants, contracts, bookings, trips, assignments, and scheduling.

- These modules model fleet operations and resource allocation.

- contracts and bookings appear to connect the commercial side to vehicle availability, while assignments, scheduling, and trips manage operational execution.

8. Maintenance, workshop, and document lifecycle

- maintenance, documents, workshop, and fuel form the vehicle health and servicing side of the system.

- workshop includes jobs, parts/labor breakdown, and cost tracking.

- documents and maintenance are tied to expiry/overdue alerting, which links this domain to the alert subsystem.

9. Accounting and reporting layer

- expenses, income, and accounting provide financial tracking and reporting inputs.

- reports and accounting generate aggregate views such as profit/loss, mileage, fuel, and usage reports.

- These modules are downstream consumers of operational data from bookings, trips, fuel, and maintenance.

10. Tracking and real-time telemetry

- tracking handles GPS location ingestion from drivers/vehicles.

- The readme indicates a Redis-backed cache plus WebSocket broadcast path, so this is a hybrid flow: write location data, update cache, then push updates to connected clients.

- gateways/app.gateway.ts is the real-time edge of the system and should be drawn as parallel to HTTP controllers, not inside them.

11. Background jobs and alerting

- jobs and alerts form the asynchronous subsystem.

- Scheduled jobs scan for document expiry, contract expiry, maintenance due, and offline vehicles.

- Alerts are likely persisted and then queried via API, while the job runners are the producers.

- This subsystem depends on PostgreSQL for state and Redis/BullMQ for scheduling/execution.

12. Audit and observability

- audit records immutable state-changing activity through an interceptor, not by manual logging in each service.

- logging.interceptor.ts and the Winston logger provide request-level observability.

- sensitive-fields.interceptor.ts removes credentials from output, which is important for showing the response path in diagrams.

13. Shared infrastructure and utilities

- src/database wraps Prisma access; this is the main persistence boundary for all feature modules.

- src/shared and src/common hold reusable guards, decorators, pipes, helpers, filters, Redis integration, and logger config.

- These shared pieces are what keep the feature modules thin and consistent.

14. Data model and migration history

- The repository includes a full Prisma migration history plus SQL backups and migration dumps.

- That suggests the schema is central to the design and likely stable enough to treat as a formal contract.

- docker-compose.yml and the Supabase-oriented environment variables indicate the system is intended to run against managed PostgreSQL and Redis in production-like environments.

15. How to draw the architecture

- Draw the app as a single NestJS backend with three primary entry points: HTTP controllers, WebSocket gateway, and BullMQ jobs.

- Place auth/tenant/role/feature guards in front of all business modules.

- Show Prisma/PostgreSQL as the authoritative data store, Redis as the support layer for blacklisting/cache/jobs, and WebSocket as the live telemetry channel.

- Group the domain modules into functional clusters: fleet operations, maintenance/workshop, finance/reporting, admin/control-plane, and async alerts/jobs.