# rusertechseguridad-source/rusertechsaas architecture

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

- Interactive diagram: https://gitdiagram.com/rusertechseguridad-source/rusertechsaas
- Repository: https://github.com/rusertechseguridad-source/rusertechsaas

## Overview

1. **Repository shape**
   - This is a two-app monorepo centered on a SaaS fleet-tracking platform.
   - `apps/api` is the backend engine; `apps/web` is the customer-facing UI plus public site.
   - The codebase is organized by business domain rather than by technical layer alone, which is important for drawing the architecture around bounded contexts.

2. **Backend runtime and core framework**
   - `apps/api` is a NestJS 10 application using a modular monolith structure.
   - `main.ts` boots the app, and `app.module.ts` composes the feature modules.
   - Prisma is the main persistence layer via `PrismaModule` / `PrismaService`, so most domain services ultimately go through a single database access boundary.

3. **Multi-tenant and access-control boundary**
   - The backend explicitly enforces tenant context through `TenantInterceptor` and a CLS-backed `tenant.store.ts`.
   - Authentication and authorization are split into several layers: JWT, local login, API key auth, role guards, and permission guards.
   - The README indicates RBAC plus entity-based access restrictions, especially for limited “viewer” users who can only see specific vehicles or locations; that filtering is enforced server-side, not just in the UI.

4. **Identity, admin, and user management**
   - `auth`, `users`, and `admin` form the identity/governance plane.
   - `admin` appears to handle global configuration, roles/permissions, and system-wide user administration.
   - `auth` contains strategies, guards, and decorators, which suggests the API is the authoritative enforcement point for session and privilege checks.

5. **Core fleet and operational domain**
   - The main business entities are split into feature modules: `vehicles`, `drivers`, `carriers`, `routes`, `locations`, `devices`, `sensors`, `trips`, and `avl-users`.
   - These modules likely represent the operational graph of the platform: devices generate data, vehicles/drivers are mapped to trips and routes, and locations/sensors feed monitoring and configuration.
   - `settings`, `operations`, `notifications`, and `alerts` sit around the core fleet entities as configuration and workflow layers.

6. **Telemetry and real-time processing path**
   - `telemetry` is a distinct subsystem with a controller, service, geocoding service, and outbox processor.
   - This indicates an ingestion-and-enrichment flow: telemetry enters the API, is stored/processed, may be geocoded, and then is pushed through an outbox pattern for downstream handling.
   - The README and module set suggest this is where live tracking and map updates originate.

7. **Background jobs and async pipelines**
   - Several modules have processors instead of only controllers/services: `carbon.processor`, `forwarding.processor`, `simulator.processor`, and telemetry’s outbox processor.
   - That points to asynchronous work handled through BullMQ-style queues, with Redis as the supporting infrastructure.
   - These processors likely decouple ingestion from side effects such as forwarding events, generating emissions metrics, or simulating device activity.

8. **Analytics, carbon, and reporting**
   - `analytics` and `carbon` are separate domain slices, implying computed/aggregated data rather than CRUD alone.
   - `carbon` likely transforms trip/telemetry data into sustainability metrics, while `analytics` serves dashboards and summaries.
   - These modules probably depend on telemetry and trips as source data and are read-heavy compared to operational modules.

9. **Simulation and dev/test support**
   - `simulator` is a first-class backend module, not just a test utility, and is matched by a frontend simulator page.
   - The repo also includes many scripts for seeding, inspection, and direct SQL execution: `seed.ts`, `seed-device.ts`, `seed-coords.ts`, `run-sql.ts`, `check_db.ts`, etc.
   - That suggests the platform can generate synthetic telemetry/device data and supports heavy local validation against the database.

10. **Frontend architecture**
   - `apps/web` is a React 18 + Vite application with TailwindCSS.
   - It is split into a public site (`pages/public`) and an authenticated SaaS console (`layouts/AppLayout`, guarded routes, dashboard pages).
   - Route-level feature folders mirror backend domains: admin, alerts, analytics, devices, drivers, locations, map, routes, sensors, trips, vehicles, settings, simulator.

11. **Frontend state and access control**
   - Zustand stores (`authStore`, `alertsStore`, `tripsStore`, `vehiclesStore`, etc.) hold client-side domain state.
   - `PrivateGuard`, `PublicGuard`, and `RequirePermission` enforce route access based on auth and permissions.
   - This means the UI is permission-aware, but it still relies on the backend for actual data filtering and authorization.

12. **Map and live-operations UI**
   - `MapPage` and the simulator-related UI indicate the frontend is built around real-time operational visibility.
   - The README calls out MapLibre GL JS, so the map is a major presentation boundary for vehicles, trips, and events.
   - Sensor dashboards and trip detail views suggest the UI consumes both current state and historical series, not just static records.

13. **Internationalization and cross-cutting UI concerns**
   - The frontend has bilingual support via `i18n` with English and Spanish locale files.
   - Shared UI utilities like toast handling, export helpers, and label mapping indicate a reusable application shell around the domain pages.
   - This matters architecturally because localization is not isolated to marketing pages; it covers admin and operational workflows too.

14. **Data and infrastructure boundary**
   - The system is built around PostgreSQL with PostGIS plus Redis, matching spatial fleet tracking and queue/cache needs.
   - Prisma migrations include telemetry partitioning and cron-related SQL, which implies the telemetry table is large, time-series-like, and operationally optimized.
   - The README references Supabase for PostgreSQL and Upstash for Redis, so external managed services are part of the deployment boundary.

15. **Where to draw the main boxes in a diagram**
   - A clear architecture diagram should show: public web UI, authenticated SaaS UI, NestJS API, authentication/authorization layer, tenant context layer, domain services, telemetry ingestion/processing, async workers/queues, and the PostgreSQL/Redis data tier.
   - The most important data flow is from device/telemetry input into the backend, through enrichment and persistence, then out to dashboards, map views, alerts, analytics, and carbon/reporting features.

Main entry points: [`apps/api/src/main.ts`](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/main.ts) (API bootstrap), [`apps/web/src/layouts/AppLayout.tsx`](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/web/src/layouts/AppLayout.tsx) (SaaS console), [`apps/api/src/auth/auth.module.ts`](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/auth/auth.module.ts) (Identity & auth), [`apps/api/src/vehicles/vehicles.module.ts`](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/vehicles/vehicles.module.ts) (Fleet domains)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["apps/web"]
  node_web_public["Public site<br/>React marketing<br/>[HomePage.tsx]"]
  node_web_app["SaaS console<br/>React app<br/>[AppLayout.tsx]"]
  node_web_access{{"Route guards<br/>Auth/perm UI<br/>[PrivateGuard.tsx]"}}
  node_web_domain["Domain pages<br/>Feature views<br/>[MapPage.tsx]"]
  node_web_state["Zustand state<br/>Client stores<br/>[authStore.ts]"]
  node_web_map(("Map & live ops<br/>MapLibre UI<br/>[MapPage.tsx]"))
end

subgraph group_api["apps/api"]
  node_api_bootstrap["API bootstrap<br/>NestJS entry<br/>[main.ts]"]
  node_api_auth{{"Identity & auth<br/>AuthN/Z<br/>[auth.module.ts]"}}
  node_api_tenant{{"Tenant context<br/>Multi-tenant boundary"}}
  node_api_admin["Admin plane<br/>Governance<br/>[admin.module.ts]"]
  node_api_users["Users & AVL<br/>User domain<br/>[users.module.ts]"]
  node_api_fleet["Fleet domains<br/>Operational core<br/>[vehicles.module.ts]"]
  node_api_telemetry["Telemetry ingestion<br/>Ingest/enrich"]
  node_api_workers["Async workers<br/>Queue processors"]
  node_api_analytics["Analytics & carbon<br/>Read models"]
  node_api_comms["Alerts & comms<br/>Workflow layer<br/>[alerts.module.ts]"]
end

subgraph group_infra["Data & runtime"]
  node_api_prisma[("Prisma boundary<br/>Persistence<br/>[prisma.module.ts]")]
  node_infra_db[("PostgreSQL<br/>PostGIS DB<br/>[schema.prisma]")]
  node_infra_redis[("Redis<br/>Cache/queue<br/>[redis.module.ts]")]
end

node_web_public -->|"public routes"| node_web_access
node_web_access -->|"enter app"| node_web_app
node_web_app -->|"renders"| node_web_domain
node_web_domain -->|"reads/writes"| node_web_state
node_web_domain -->|"map views"| node_web_map
node_web_app -->|"API calls"| node_api_auth
node_web_app -->|"fleet data"| node_api_fleet
node_web_app -->|"live data"| node_api_telemetry
node_api_bootstrap -->|"composes"| node_api_auth
node_api_bootstrap -->|"composes"| node_api_tenant
node_api_bootstrap -->|"composes"| node_api_admin
node_api_bootstrap -->|"composes"| node_api_fleet
node_api_bootstrap -->|"composes"| node_api_telemetry
node_api_bootstrap -->|"composes"| node_api_workers
node_api_bootstrap -->|"composes"| node_api_analytics
node_api_auth -->|"scopes access"| node_api_tenant
node_api_auth -->|"manages users"| node_api_users
node_api_admin -->|"policy"| node_api_auth
node_api_fleet -->|"persists via"| node_api_prisma
node_api_telemetry -->|"outbox"| node_api_workers
node_api_workers -->|"queues"| node_infra_redis
node_api_prisma -->|"SQL"| node_infra_db
node_api_analytics -->|"derives from"| node_api_telemetry
node_api_comms -->|"reacts to"| node_api_fleet

click node_web_public "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/web/src/pages/public/HomePage.tsx"
click node_web_app "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/web/src/layouts/AppLayout.tsx"
click node_web_access "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/web/src/components/PrivateGuard.tsx"
click node_web_domain "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/web/src/pages/map/MapPage.tsx"
click node_web_state "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/web/src/store/authStore.ts"
click node_web_map "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/web/src/pages/map/MapPage.tsx"
click node_api_bootstrap "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/main.ts"
click node_api_auth "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/auth/auth.module.ts"
click node_api_tenant "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/common/interceptors/tenant.interceptor.ts"
click node_api_admin "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/admin/admin.module.ts"
click node_api_users "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/users/users.module.ts"
click node_api_fleet "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/vehicles/vehicles.module.ts"
click node_api_telemetry "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/telemetry/telemetry.module.ts"
click node_api_workers "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/forwarding/forwarding.processor.ts"
click node_api_analytics "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/analytics/analytics.module.ts"
click node_api_comms "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/alerts/alerts.module.ts"
click node_api_prisma "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/prisma/prisma.module.ts"
click node_infra_db "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/prisma/schema.prisma"
click node_infra_redis "https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/common/redis/redis.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_web_public,node_web_app,node_web_access,node_web_domain,node_web_state,node_web_map toneBlue
class node_api_bootstrap,node_api_auth,node_api_tenant,node_api_admin,node_api_users,node_api_fleet,node_api_telemetry,node_api_workers,node_api_analytics,node_api_comms toneAmber
class node_api_prisma,node_infra_db,node_infra_redis toneMint
```

## Components

### apps/web

React front-end split between public site and authenticated SaaS console.

- [Public site](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/web/src/pages/public/HomePage.tsx): React marketing · Public-facing pages and content area. · `apps/web/src/pages/public/HomePage.tsx`
- [SaaS console](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/web/src/layouts/AppLayout.tsx): React app · Authenticated operational UI for fleet management. · `apps/web/src/layouts/AppLayout.tsx`
- [Route guards](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/web/src/components/PrivateGuard.tsx): Auth/perm UI · Client-side access control for public, private, and permissioned routes. · `apps/web/src/components/PrivateGuard.tsx`
- [Domain pages](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/web/src/pages/map/MapPage.tsx): Feature views · Route-level pages for admin, fleet, telemetry, map, and reporting workflows. · `apps/web/src/pages/map/MapPage.tsx`
- [Zustand state](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/web/src/store/authStore.ts): Client stores · Shared UI state for auth, fleets, alerts, trips, devices, and simulator. · `apps/web/src/store/authStore.ts`
- [Map & live ops](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/web/src/pages/map/MapPage.tsx): MapLibre UI · Real-time map and simulator-centric operational views. · `apps/web/src/pages/map/MapPage.tsx`

### apps/api

NestJS modular monolith handling identity, fleet operations, telemetry, and async processing.

- [API bootstrap](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/main.ts): NestJS entry · Application startup and module composition. · `apps/api/src/main.ts`
- [Identity & auth](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/auth/auth.module.ts): AuthN/Z · JWT, local login, API key auth, roles, permissions, and decorators. · `apps/api/src/auth/auth.module.ts`
- [Tenant context](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/common/interceptors/tenant.interceptor.ts): Multi-tenant boundary · CLS-backed tenant storage and request interceptor for tenant scoping. · `apps/api/src/common/interceptors/tenant.interceptor.ts`
- [Admin plane](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/admin/admin.module.ts): Governance · Global configuration, roles/permissions, and system administration. · `apps/api/src/admin/admin.module.ts`
- [Users & AVL](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/users/users.module.ts): User domain · User management plus AVL-specific user and event dictionary features. · `apps/api/src/users/users.module.ts`
- [Fleet domains](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/vehicles/vehicles.module.ts): Operational core · Vehicles, drivers, carriers, routes, locations, devices, sensors, trips, and settings. · `apps/api/src/vehicles/vehicles.module.ts`
- [Telemetry ingestion](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/telemetry/telemetry.module.ts): Ingest/enrich · Telemetry entrypoint with geocoding and outbox processing. · `apps/api/src/telemetry/telemetry.module.ts`
- [Async workers](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/forwarding/forwarding.processor.ts): Queue processors · Background processors for telemetry outbox, forwarding, carbon, and simulator flows. · `apps/api/src/forwarding/forwarding.processor.ts`
- [Analytics & carbon](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/analytics/analytics.module.ts): Read models · Aggregations and sustainability reporting derived from trips and telemetry. · `apps/api/src/analytics/analytics.module.ts`
- [Alerts & comms](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/alerts/alerts.module.ts): Workflow layer · Alerts, notifications, operations, and mail-oriented workflows. · `apps/api/src/alerts/alerts.module.ts`

### Data & runtime

Shared persistence and background infrastructure for the platform.

- [Prisma boundary](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/prisma/prisma.module.ts): Persistence · Single database access layer for domain services. · `apps/api/src/prisma/prisma.module.ts`
- [PostgreSQL](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/prisma/schema.prisma): PostGIS DB · Primary relational datastore with spatial support and partitioned telemetry tables. · `apps/api/prisma/schema.prisma`
- [Redis](https://github.com/rusertechseguridad-source/rusertechsaas/blob/main/apps/api/src/common/redis/redis.module.ts): Cache/queue · Supporting infrastructure for caching and background jobs. · `apps/api/src/common/redis/redis.module.ts`

## Connections

- Public site → Route guards: public routes · Public pages are separated from authenticated access.
- Route guards → SaaS console: enter app · Guards gate the authenticated console.
- SaaS console → Domain pages: renders · The app shell hosts domain route pages.
- Domain pages → Zustand state: reads/writes · Pages consume shared client state and caches.
- Domain pages → Map & live ops: map views · Fleet pages feed the live map and simulator views.
- SaaS console → Identity & auth: API calls · Frontend auth flows depend on backend identity services.
- SaaS console → Fleet domains: fleet data · Operational pages load core fleet entities from the API.
- SaaS console → Telemetry ingestion: live data · Map and sensor views consume telemetry streams.
- API bootstrap → Identity & auth: composes · The NestJS app wires auth as a core module.
- API bootstrap → Tenant context: composes · Tenant scoping is applied at the application boundary.
- API bootstrap → Admin plane: composes · Admin capabilities are part of the main API composition.
- API bootstrap → Fleet domains: composes · Core fleet modules are loaded into the monolith.
- API bootstrap → Telemetry ingestion: composes · Telemetry is a first-class backend subsystem.
- API bootstrap → Async workers: composes · Async processors run alongside the API runtime.
- API bootstrap → Analytics & carbon: composes · Analytics and carbon are separate backend slices.
- Identity & auth → Tenant context: scopes access · Authorization operates within tenant context.
- Identity & auth → Users & AVL: manages users · Identity flows connect to user administration.
- Admin plane → Identity & auth: policy · Admin controls roles, permissions, and access policy.
- Fleet domains → Prisma boundary: persists via · Domain services use Prisma as the database boundary.
- Telemetry ingestion → Async workers: outbox · Telemetry emits downstream work through processors.
- Async workers → Redis: queues · Background jobs are supported by Redis-backed infrastructure.
- Prisma boundary → PostgreSQL: SQL · Prisma talks to the PostgreSQL/PostGIS datastore.
- Analytics & carbon → Telemetry ingestion: derives from · Analytics and carbon consume telemetry and trip data.
- Alerts & comms → Fleet domains: reacts to · Alerts and notifications are driven by operational entities and events.
