How rusertechseguridad-source/rusertechsaas works
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: main.ts API bootstrap · AppLayout.tsx SaaS console · auth.module.ts Identity & auth · vehicles.module.ts Fleet domains
Components 19
apps/web
React front-end split between public site and authenticated SaaS console.
- Public site · Public-facing pages and content area.
apps/web/src/pages/public/HomePage.tsx - SaaS console · Authenticated operational UI for fleet management.
apps/web/src/layouts/AppLayout.tsx - Route guards · Client-side access control for public, private, and permissioned routes.
apps/web/src/components/PrivateGuard.tsx - Domain pages · Route-level pages for admin, fleet, telemetry, map, and reporting workflows.
apps/web/src/pages/map/MapPage.tsx - Zustand state · Shared UI state for auth, fleets, alerts, trips, devices, and simulator.
apps/web/src/store/authStore.ts - Map & live ops · 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 · Application startup and module composition.
apps/api/src/main.ts - Identity & auth · JWT, local login, API key auth, roles, permissions, and decorators.
apps/api/src/auth/auth.module.ts - Tenant context · CLS-backed tenant storage and request interceptor for tenant scoping.
apps/api/src/common/interceptors/tenant.interceptor.ts - Admin plane · Global configuration, roles/permissions, and system administration.
apps/api/src/admin/admin.module.ts - Users & AVL · User management plus AVL-specific user and event dictionary features.
apps/api/src/users/users.module.ts - Fleet domains · Vehicles, drivers, carriers, routes, locations, devices, sensors, trips, and settings.
apps/api/src/vehicles/vehicles.module.ts - Telemetry ingestion · Telemetry entrypoint with geocoding and outbox processing.
apps/api/src/telemetry/telemetry.module.ts - Async workers · Background processors for telemetry outbox, forwarding, carbon, and simulator flows.
apps/api/src/forwarding/forwarding.processor.ts - Analytics & carbon · Aggregations and sustainability reporting derived from trips and telemetry.
apps/api/src/analytics/analytics.module.ts - Alerts & comms · 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 · Single database access layer for domain services.
apps/api/src/prisma/prisma.module.ts - PostgreSQL · Primary relational datastore with spatial support and partitioned telemetry tables.
apps/api/prisma/schema.prisma - Redis · Supporting infrastructure for caching and background jobs.
apps/api/src/common/redis/redis.module.ts
Connections 24
- 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.