Backend API Architecture

The Backend API is structured into independent functional modules, each responsible for a specific set of business requirements. This structure ensures that changes in one area (e.g., trips) don't inadvertently impact another (e.g., cars).

Functional Modules

🗺️ Operational Modules

• trips: Manages the lifecycle of a transport service (scheduling, status, assignment).
• routes: Pre-defined paths and destination details.
• car-handovers: Tracks vehicle status and responsibility during driver shifts.
• car-snapshots: Photographic records of vehicle condition.

🚗 Resource Modules

• cars: Full management of the vehicle fleet, including compliance and types.
• drivers: Driver profile management, license monitoring, and identity.
• maintenances: Tracks car service history and scheduled maintenance.

🏢 Organizational Modules

• companies: Manages partner and subcontractor entities.
• users: General identity management for all personnel.
• auth: Handles sessions, organizations, and security via Better Auth.

🛠️ Supporting Modules

• attachments / upload: Handles file storage (S3) for photos and documents.
• notifications / push-tokens: Manages system alerts and mobile push notifications.
• reports / analytics: Business intelligence and operational reporting.
• trip-charges: Financial tracking for costs associated with specific trips.

---

Technical Design Patterns

OpenAPI & Documentation

The API automatically generates a living specification. Every endpoint, its required inputs, and expected outputs are documented and can be viewed via the /docs route on the running API.

Type Safety

Every module uses Zod schemas shared across the entire monorepo. This means that a requirement defined in the "Admin Panel" for a specific field (like a phone number format) is automatically enforced by the Backend API.

Real-Time Capabilities

The ws (WebSocket) module allows for real-time updates, ensuring that dispatchers and drivers see changes immediately without needing to refresh their screens.