# ricardoalvim/biga-fleet-manager architecture

> Architecture diagram of the GitHub repository ricardoalvim/biga-fleet-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ricardoalvim/biga-fleet-manager
- Repository: https://github.com/ricardoalvim/biga-fleet-manager

## Overview

Biga Fleet Manager is a multi-tenant fleet operations platform with a React portal and NestJS API. Users manage vehicles, trips and routes, maintenance, fuel reconciliation and toll/incident records; operators also monitor live telemetry, while tenant administrators manage onboarding, users, billing, branding and integrations. The graph shows the portal-to-API boundary, telemetry ingestion and streaming, and representative domain services and stores. Several subsystem links reflect README-described capabilities; sampled source confirms the specific controller-to-service and ingestion calls shown, but not all internal wiring.

Main entry points: [`src/main.ts`](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/main.ts) (NestJS API), [`frontend/src/services/api.ts`](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/frontend/src/services/api.ts) (API client), [`src/fleet/fuel/controllers/fuel.controller.ts`](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/fleet/fuel/controllers/fuel.controller.ts) (Fuel reconciliation), [`src/fleet/incident-toll/controllers/incident-toll.controller.ts`](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/fleet/incident-toll/controllers/incident-toll.controller.ts) (Tolls and incidents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Tenant portal"]
  node_app["Portal application<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_fleet_views["Fleet views"]
  node_maintenance_view["Maintenance view"]
  node_live_map["Live fleet map<br/>[LiveFleetMap.tsx]"]
  node_tenant_admin["Tenant admin"]
end

subgraph group_fleet["Fleet operations"]
  node_vehicles["Vehicles and trips"]
  node_routing["Route planning"]
  node_maintenance["Maintenance orders"]
  node_fuel["Fuel reconciliation<br/>[fuel.controller.ts]"]
  node_tolls["Tolls and incidents"]
end

subgraph group_realtime["Telemetry and streaming"]
  node_ingestion["Telemetry ingestion"]
  node_publisher["Ingestion publisher"]
  node_processor["Telemetry processor"]
  node_streaming["Realtime streaming"]
end

subgraph group_platform["Platform services"]
  node_backend["NestJS API<br/>[main.ts]"]
  node_tenancy["Tenant context"]
  node_portal_api["Portal services"]
  node_auth["Authentication"]
  node_ecosystem["Tenant ecosystem"]
end

subgraph group_data["Persistence"]
  node_postgres[("Relational store<br/>[prisma.service.ts]")]
  node_mongodb[("Document store<br/>[mongo.module.ts]")]
  node_redis[("Redis event bus<br/>[redis.module.ts]")]
end

node_operator(("Fleet user"))
node_external_system(("Fleet integrations"))

node_operator -->|"uses"| node_app
node_app -->|"requests"| node_api_client
node_api_client -->|"REST calls"| node_backend
node_backend -->|"resolves tenant"| node_tenancy
node_backend -->|"authenticates"| node_auth
node_backend -->|"dispatches portal"| node_portal_api
node_backend -->|"dispatches platform"| node_ecosystem
node_backend -->|"dispatches fleet"| node_vehicles
node_backend -->|"dispatches routes"| node_routing
node_backend -->|"dispatches maintenance"| node_maintenance
node_backend -->|"dispatches fuel"| node_fuel
node_backend -->|"dispatches tolls"| node_tolls
node_backend -->|"dispatches ingest"| node_ingestion
node_vehicles -->|"persists records"| node_postgres
node_fuel -->|"stores audits"| node_mongodb
node_maintenance -->|"stores orders"| node_mongodb
node_tolls -->|"stores events"| node_mongodb
node_ingestion -->|"publishes envelope"| node_publisher
node_publisher -->|"forwards telemetry"| node_processor
node_processor -->|"emits events"| node_streaming
node_streaming -->|"broadcasts events"| node_redis
node_live_map -->|"requests live data"| node_api_client
node_fleet_views -->|"requests fleet data"| node_api_client
node_maintenance_view -->|"requests orders"| node_api_client
node_tenant_admin -->|"requests portal data"| node_api_client
node_external_system -->|"sends telemetry"| node_ingestion
node_external_system -->|"submits transactions"| node_fuel
node_external_system -->|"submits toll events"| node_tolls
node_ecosystem -.->|"dispatches webhooks"| node_external_system

click node_app "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/frontend/src/services/api.ts"
click node_fleet_views "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/frontend/src/fleet/FleetManagementView.tsx"
click node_maintenance_view "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/frontend/src/maintenance/MaintenanceManagementView.tsx"
click node_live_map "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/frontend/src/realtime/LiveFleetMap.tsx"
click node_tenant_admin "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/frontend/src/app/TenantDashboard.tsx"
click node_backend "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/main.ts"
click node_tenancy "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/tenancy/tenant.middleware.ts"
click node_portal_api "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/platform/portal/services/portal.internal.service.ts"
click node_auth "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/platform/auth/services/auth.internal.service.ts"
click node_ecosystem "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/platform/ecosystem/services/platform-ecosystem.internal.service.ts"
click node_vehicles "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/fleet/vehicle/controllers/vehicle.controller.ts"
click node_routing "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/fleet/route-planning/controllers/route-planning.controller.ts"
click node_maintenance "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/fleet/maintenance/controllers/maintenance.controller.ts"
click node_fuel "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/fleet/fuel/controllers/fuel.controller.ts"
click node_tolls "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/fleet/incident-toll/controllers/incident-toll.controller.ts"
click node_ingestion "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/ingestion/ingestion.controller.ts"
click node_publisher "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/ingestion/ingestion.publisher.ts"
click node_processor "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/telemetry/telemetry-processor.service.ts"
click node_streaming "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/platform/streaming/services/realtime-streaming.internal.service.ts"
click node_postgres "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/platform/persistence/prisma.service.ts"
click node_mongodb "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/platform/mongo/mongo.module.ts"
click node_redis "https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/platform/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_app,node_api_client,node_fleet_views,node_maintenance_view,node_live_map,node_tenant_admin,node_operator toneBlue
class node_vehicles,node_routing,node_maintenance,node_fuel,node_tolls toneAmber
class node_ingestion,node_publisher,node_processor,node_streaming toneMint
class node_backend,node_tenancy,node_portal_api,node_auth,node_ecosystem toneRose
class node_postgres,node_mongodb,node_redis,node_external_system toneIndigo
```

## Components

### Tenant portal

- [Portal application](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Fleet views](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/frontend/src/fleet/FleetManagementView.tsx): `frontend/src/fleet/FleetManagementView.tsx`
- [Maintenance view](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/frontend/src/maintenance/MaintenanceManagementView.tsx): `frontend/src/maintenance/MaintenanceManagementView.tsx`
- [Live fleet map](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/frontend/src/realtime/LiveFleetMap.tsx): `frontend/src/realtime/LiveFleetMap.tsx`
- [Tenant admin](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/frontend/src/app/TenantDashboard.tsx): `frontend/src/app/TenantDashboard.tsx`

### Fleet operations

- [Vehicles and trips](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/fleet/vehicle/controllers/vehicle.controller.ts): `src/fleet/vehicle/controllers/vehicle.controller.ts`
- [Route planning](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/fleet/route-planning/controllers/route-planning.controller.ts): `src/fleet/route-planning/controllers/route-planning.controller.ts`
- [Maintenance orders](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/fleet/maintenance/controllers/maintenance.controller.ts): `src/fleet/maintenance/controllers/maintenance.controller.ts`
- [Fuel reconciliation](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/fleet/fuel/controllers/fuel.controller.ts): `src/fleet/fuel/controllers/fuel.controller.ts`
- [Tolls and incidents](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/fleet/incident-toll/controllers/incident-toll.controller.ts): `src/fleet/incident-toll/controllers/incident-toll.controller.ts`

### Telemetry and streaming

- [Telemetry ingestion](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/ingestion/ingestion.controller.ts): `src/ingestion/ingestion.controller.ts`
- [Ingestion publisher](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/ingestion/ingestion.publisher.ts): `src/ingestion/ingestion.publisher.ts`
- [Telemetry processor](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/telemetry/telemetry-processor.service.ts): `src/telemetry/telemetry-processor.service.ts`
- [Realtime streaming](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/platform/streaming/services/realtime-streaming.internal.service.ts): `src/platform/streaming/services/realtime-streaming.internal.service.ts`

### Platform services

- [NestJS API](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/main.ts): `src/main.ts`
- [Tenant context](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/tenancy/tenant.middleware.ts): `src/tenancy/tenant.middleware.ts`
- [Portal services](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/platform/portal/services/portal.internal.service.ts): `src/platform/portal/services/portal.internal.service.ts`
- [Authentication](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/platform/auth/services/auth.internal.service.ts): `src/platform/auth/services/auth.internal.service.ts`
- [Tenant ecosystem](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/platform/ecosystem/services/platform-ecosystem.internal.service.ts): `src/platform/ecosystem/services/platform-ecosystem.internal.service.ts`

### Persistence

- [Relational store](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/platform/persistence/prisma.service.ts): `src/platform/persistence/prisma.service.ts`
- [Document store](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/platform/mongo/mongo.module.ts): `src/platform/mongo/mongo.module.ts`
- [Redis event bus](https://github.com/ricardoalvim/biga-fleet-manager/blob/main/src/platform/redis/redis.module.ts): `src/platform/redis/redis.module.ts`

### Other components

- **Fleet user**
- **Fleet integrations**

## Connections

- Fleet user → Portal application: uses
- Portal application → API client: requests
- API client → NestJS API: REST calls
- NestJS API → Tenant context: resolves tenant
- NestJS API → Authentication: authenticates
- NestJS API → Portal services: dispatches portal
- NestJS API → Tenant ecosystem: dispatches platform
- NestJS API → Vehicles and trips: dispatches fleet
- NestJS API → Route planning: dispatches routes
- NestJS API → Maintenance orders: dispatches maintenance
- NestJS API → Fuel reconciliation: dispatches fuel
- NestJS API → Tolls and incidents: dispatches tolls
- NestJS API → Telemetry ingestion: dispatches ingest
- Vehicles and trips → Relational store: persists records
- Fuel reconciliation → Document store: stores audits
- Maintenance orders → Document store: stores orders
- Tolls and incidents → Document store: stores events
- Telemetry ingestion → Ingestion publisher: publishes envelope
- Ingestion publisher → Telemetry processor: forwards telemetry
- Telemetry processor → Realtime streaming: emits events
- Realtime streaming → Redis event bus: broadcasts events
- Live fleet map → API client: requests live data
- Fleet views → API client: requests fleet data
- Maintenance view → API client: requests orders
- Tenant admin → API client: requests portal data
- Fleet integrations → Telemetry ingestion: sends telemetry
- Fleet integrations → Fuel reconciliation: submits transactions
- Fleet integrations → Tolls and incidents: submits toll events
- Tenant ecosystem → Fleet integrations: dispatches webhooks