astlejoe789/transitops-smart-fleet-platform

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