# astlejoe789/transitops-smart-fleet-platform architecture

> Architecture diagram of the GitHub repository astlejoe789/transitops-smart-fleet-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/astlejoe789/transitops-smart-fleet-platform
- Repository: https://github.com/astlejoe789/transitops-smart-fleet-platform

## Overview

#### Purpose and deployable entry points
TransitOps is a modular-monolith fleet and transport-operations platform: dispatch/trips, fleet and drivers, fuel/maintenance/expenses, vendors/customers, billing/payments, reporting, analytics, notifications, and administration. The React SPA starts at `apps/web/src/main.tsx` and routes through `apps/web/src/router/AppRouter.tsx`. The Express REST API is bootstrapped by `apps/api/src/server.ts` and composed in `apps/api/src/app.ts`.

#### Web application shell and access boundary
The Vite/React 18 client provides public, auth, and operational layouts; route access is gated by authentication and role checks. Global providers establish auth, theme, and application-level data context before feature pages render.
- `apps/web/src/providers/AppProviders.tsx`
- `apps/web/src/guards/AuthGuard.tsx`
- `apps/web/src/layouts/MainLayout.tsx`

#### Client-to-API data flow
Feature pages and modals call a centralized API client and domain API wrappers, then render dashboard, operational records, and reports. This creates the frontend/backend boundary at HTTP rather than sharing backend services directly.
- `apps/web/src/api/client.ts`
- `apps/web/src/api/trips.api.ts`
- `apps/web/src/modules/fleet/pages/VehiclesPage.tsx`

#### API composition, security, and request pipeline
Express mounts the module route surface centrally. Requests cross CORS, rate limiting, JWT authentication, permission/role authorization, validation, and shared error handling before reaching controllers. JWT/password utilities and standardized exceptions/responses form the common security and API-contract layer.
- `apps/api/src/routes/index.ts`
- `apps/api/src/middlewares/auth.middleware.ts`
- `apps/api/src/middlewares/permission.middleware.ts`

#### Domain-module architecture
Backend capabilities follow a repeated vertical slice: routes → controller → service → repository, with DTOs and validation at the input boundary. Core operational modules include trips/dispatch, fleet, drivers, fuel, maintenance, and expenses; commercial and administration modules cover customers, vendors, billing, payments, settings, users/administration, notifications, reports, dashboard, and analytics.
- `apps/api/src/modules/trips/routes.ts`
- `apps/api/src/modules/fleet/service.ts`
- `apps/api/src/modules/billing/repository.ts`

#### AI and derived operational insights
The AI module is isolated behind a provider interface, allowing OpenAI, Gemini, or local implementations without leaking provider choices across other business modules. Dashboard, analytics, and reports are separate read/aggregation-oriented API domains.
- `apps/api/src/modules/ai/providers/ai-provider.interface.ts`
- `apps/api/src/modules/ai/providers/openai.provider.ts`
- `apps/api/src/modules/analytics/service.ts`

#### Persistence and infrastructure
PostgreSQL is the system of record, accessed through Prisma and a shared client. The schema, versioned initial migration, and seed script define database lifecycle. Local containers are coordinated with Docker Compose; production targets are Vercel for the SPA and Railway for API/PostgreSQL, with per-app Docker/deployment manifests.
- `database/prisma/schema.prisma`
- `apps/api/src/database/prisma.ts`
- `docker-compose.yml`

Main entry points: [`apps/api/src/routes/index.ts`](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/routes/index.ts) (Central route surface), [`apps/api/src/database/prisma.ts`](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/database/prisma.ts) (Prisma data access), [`apps/api/src/server.ts`](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/server.ts) (API bootstrap), [`apps/api/src/modules/analytics/service.ts`](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/modules/analytics/service.ts) (Dashboard, reports & analytics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["React SPA"]
  node_web_entry["Web entry &amp; router<br/>React bootstrap<br/>[main.tsx]"]
  node_web_providers["Global providers<br/>React providers<br/>[AppProviders.tsx]"]
  node_web_access["Access guards &amp; layout<br/>route boundary<br/>[AuthGuard.tsx]"]
  node_web_features["Operational feature pages<br/>React features<br/>[VehiclesPage.tsx]"]
  node_web_api["API client &amp; domain wrappers<br/>HTTP client<br/>[client.ts]"]
end

subgraph group_api["Express API"]
  node_api_server["API bootstrap<br/>Express server<br/>[server.ts]"]
  node_api_app["Express application<br/>API composition<br/>[app.ts]"]
  node_api_routes["Central route surface<br/>route registry<br/>[index.ts]"]
  node_api_security["Security &amp; request pipeline<br/>Express middleware<br/>[auth.middleware.ts]"]
end

subgraph group_domains["Domain modules"]
  node_trip_slice["Trips &amp; dispatch slice<br/>vertical module<br/>[routes.ts]"]
  node_fleet_slice["Fleet &amp; drivers slice<br/>vertical module<br/>[service.ts]"]
  node_operations_slice["Fuel, maintenance &amp; expenses<br/>vertical modules"]
  node_commercial_slice["Customers, vendors, billing &amp; payments<br/>vertical modules<br/>[repository.ts]"]
  node_admin_slice["Users, settings &amp; notifications<br/>vertical modules"]
  node_insights["Dashboard, reports &amp; analytics<br/>read domains<br/>[service.ts]"]
  node_ai{{"AI provider boundary<br/>provider interface"}}
end

subgraph group_data["Data &amp; deployment"]
  node_prisma["Prisma data access<br/>database client<br/>[prisma.ts]"]
  node_postgres[("PostgreSQL system of record<br/>database<br/>[schema.prisma]")]
  node_compose["Local container stack<br/>Docker Compose<br/>[docker-compose.yml]"]
  node_production["Production hosting<br/>deployment targets"]
end

node_web_entry -->|"wraps"| node_web_providers
node_web_providers -->|"provides context to"| node_web_access
node_web_access -->|"authorizes"| node_web_features
node_web_features -->|"requests data through"| node_web_api
node_web_api -->|"HTTPS REST"| node_api_server
node_api_server -->|"starts"| node_api_app
node_api_app -->|"applies"| node_api_security
node_api_security -->|"permits requests to"| node_api_routes
node_api_routes -->|"mounts"| node_trip_slice
node_api_routes -->|"mounts"| node_fleet_slice
node_api_routes -->|"mounts"| node_operations_slice
node_api_routes -->|"mounts"| node_commercial_slice
node_api_routes -->|"mounts"| node_admin_slice
node_api_routes -->|"mounts"| node_insights
node_api_routes -->|"mounts"| node_ai
node_trip_slice -->|"repositories use"| node_prisma
node_fleet_slice -->|"repositories use"| node_prisma
node_operations_slice -->|"repositories use"| node_prisma
node_commercial_slice -->|"repositories use"| node_prisma
node_admin_slice -->|"repositories use"| node_prisma
node_insights -->|"reads aggregates via"| node_prisma
node_ai -.->|"provides derived insights"| node_insights
node_prisma -->|"persists to"| node_postgres
node_compose -.->|"runs locally"| node_api_server
node_compose -.->|"runs locally"| node_postgres
node_production -.->|"deploys SPA"| node_web_entry
node_production -.->|"deploys API"| node_api_server
node_production -.->|"hosts database"| node_postgres

click node_web_entry "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/web/src/main.tsx"
click node_web_providers "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/web/src/providers/AppProviders.tsx"
click node_web_access "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/web/src/guards/AuthGuard.tsx"
click node_web_features "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/web/src/modules/fleet/pages/VehiclesPage.tsx"
click node_web_api "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/web/src/api/client.ts"
click node_api_server "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/server.ts"
click node_api_app "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/app.ts"
click node_api_routes "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/routes/index.ts"
click node_api_security "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/middlewares/auth.middleware.ts"
click node_trip_slice "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/modules/trips/routes.ts"
click node_fleet_slice "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/modules/fleet/service.ts"
click node_commercial_slice "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/modules/billing/repository.ts"
click node_insights "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/modules/analytics/service.ts"
click node_ai "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/modules/ai/providers/ai-provider.interface.ts"
click node_prisma "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/database/prisma.ts"
click node_postgres "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/database/prisma/schema.prisma"
click node_compose "https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/docker-compose.yml"

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_entry,node_web_providers,node_web_access,node_web_features,node_web_api toneBlue
class node_api_server,node_api_app,node_api_routes,node_api_security toneAmber
class node_trip_slice,node_fleet_slice,node_operations_slice,node_commercial_slice,node_admin_slice,node_insights,node_ai toneMint
class node_prisma,node_postgres,node_compose,node_production toneRose
```

## Components

### React SPA

- [Web entry & router](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/web/src/main.tsx): React bootstrap · Starts the SPA and selects public, auth, and operational routes. · `apps/web/src/main.tsx`
- [Global providers](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/web/src/providers/AppProviders.tsx): React providers · Establishes auth, theme, and application data context. · `apps/web/src/providers/AppProviders.tsx`
- [Access guards & layout](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/web/src/guards/AuthGuard.tsx): route boundary · Applies authentication and role access before operational screens. · `apps/web/src/guards/AuthGuard.tsx`
- [Operational feature pages](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/web/src/modules/fleet/pages/VehiclesPage.tsx): React features · Fleet, trip, dashboard, record, and report screens. · `apps/web/src/modules/fleet/pages/VehiclesPage.tsx`
- [API client & domain wrappers](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/web/src/api/client.ts): HTTP client · Centralizes browser requests to REST domain endpoints. · `apps/web/src/api/client.ts`

### Express API

- [API bootstrap](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/server.ts): Express server · Starts the REST API application. · `apps/api/src/server.ts`
- [Express application](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/app.ts): API composition · Composes shared middleware and route surface. · `apps/api/src/app.ts`
- [Central route surface](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/routes/index.ts): route registry · Mounts module REST routes. · `apps/api/src/routes/index.ts`
- [Security & request pipeline](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/middlewares/auth.middleware.ts): Express middleware · CORS, rate limiting, JWT, permissions, validation, and errors. · `apps/api/src/middlewares/auth.middleware.ts`

### Domain modules

- [Trips & dispatch slice](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/modules/trips/routes.ts): vertical module · Routes, controllers, services, repositories, DTOs, and validation. · `apps/api/src/modules/trips/routes.ts`
- [Fleet & drivers slice](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/modules/fleet/service.ts): vertical module · Vehicle and driver operational workflows. · `apps/api/src/modules/fleet/service.ts`
- **Fuel, maintenance & expenses**: vertical modules · Operational cost and upkeep workflows.
- [Customers, vendors, billing & payments](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/modules/billing/repository.ts): vertical modules · Commercial records and financial workflows. · `apps/api/src/modules/billing/repository.ts`
- **Users, settings & notifications**: vertical modules · Administration and notification capabilities.
- [Dashboard, reports & analytics](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/modules/analytics/service.ts): read domains · Aggregation-oriented operational insights. · `apps/api/src/modules/analytics/service.ts`
- [AI provider boundary](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/modules/ai/providers/ai-provider.interface.ts): provider interface · Swaps OpenAI, Gemini, or local implementations. · `apps/api/src/modules/ai/providers/ai-provider.interface.ts`

### Data & deployment

- [Prisma data access](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/apps/api/src/database/prisma.ts): database client · Shared ORM client used by repositories. · `apps/api/src/database/prisma.ts`
- [PostgreSQL system of record](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/database/prisma/schema.prisma): database · Schema, migrations, and seed define database lifecycle. · `database/prisma/schema.prisma`
- [Local container stack](https://github.com/astlejoe789/transitops-smart-fleet-platform/blob/main/docker-compose.yml): Docker Compose · Coordinates local application and database containers. · `docker-compose.yml`
- **Production hosting**: deployment targets · Vercel hosts the SPA; Railway hosts API and PostgreSQL.

## Connections

- Web entry & router → Global providers: wraps
- Global providers → Access guards & layout: provides context to
- Access guards & layout → Operational feature pages: authorizes
- Operational feature pages → API client & domain wrappers: requests data through
- API client & domain wrappers → API bootstrap: HTTPS REST
- API bootstrap → Express application: starts
- Express application → Security & request pipeline: applies
- Security & request pipeline → Central route surface: permits requests to
- Central route surface → Trips & dispatch slice: mounts
- Central route surface → Fleet & drivers slice: mounts
- Central route surface → Fuel, maintenance & expenses: mounts
- Central route surface → Customers, vendors, billing & payments: mounts
- Central route surface → Users, settings & notifications: mounts
- Central route surface → Dashboard, reports & analytics: mounts
- Central route surface → AI provider boundary: mounts
- Trips & dispatch slice → Prisma data access: repositories use
- Fleet & drivers slice → Prisma data access: repositories use
- Fuel, maintenance & expenses → Prisma data access: repositories use
- Customers, vendors, billing & payments → Prisma data access: repositories use
- Users, settings & notifications → Prisma data access: repositories use
- Dashboard, reports & analytics → Prisma data access: reads aggregates via
- AI provider boundary → Dashboard, reports & analytics: provides derived insights
- Prisma data access → PostgreSQL system of record: persists to
- Local container stack → API bootstrap: runs locally
- Local container stack → PostgreSQL system of record: runs locally
- Production hosting → Web entry & router: deploys SPA
- Production hosting → API bootstrap: deploys API
- Production hosting → PostgreSQL system of record: hosts database