# zaantoru/p2p-ui architecture

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

- Interactive diagram: https://gitdiagram.com/zaantoru/p2p-ui
- Repository: https://github.com/zaantoru/p2p-ui

## Overview

#### Purpose and entry points
1816 is a peer-to-peer car and motorcycle rental platform. A React/Vite client serves renter and role-specific staff workflows; a Fastify API owns booking, payment, operations, notifications, and telemetry persistence. Client startup is `src/main.jsx` → `src/App.jsx`; API startup is `server/src/index.js`. Vite proxies browser `/api` and `/uploads` traffic to the API.

#### Client application and role workspaces
The SPA provides vehicle discovery, detail, checkout, chat, notifications, and dashboards for renter, host, operations, management, and admin roles. Authentication state is centralized before protected API interactions, while dashboard selection reflects server-issued roles.
- `src/context/AuthContext.jsx`
- `src/pages/Checkout/Checkout.jsx`
- `src/pages/Dashboard/Renter/RenterDashboard.jsx`
- `src/pages/Dashboard/Operations/OperationsDashboard.jsx`
- `src/pages/Dashboard/Admin/AdminDashboard.jsx`

#### API boundary, identity, and authorization
Fastify routes expose the domain API. JWT authentication and role guards form the principal boundary between the SPA and protected booking, operational, financial, and fleet actions. Uploads are served separately for vehicle and workflow evidence.
- `server/src/index.js`
- `server/src/routes/auth.js`
- `server/src/middleware/auth.js`
- `server/src/middleware/roleGuard.js`
- `server/src/routes/uploads.js`

#### Booking lifecycle and availability control
Bookings progress through approval, payment-required, scheduled/booked, ongoing, and completed states. Route handlers coordinate availability, workflow state, and notifications; overlap/hold logic prevents conflicting reservations. Late status and fee calculation are modeled separately from booking status.
- `server/src/routes/bookings.js`
- `server/src/routes/operations.js`
- `server/src/utils/bookingOverlap.js`
- `server/src/utils/lateFees.js`
- `server/src/services/lateReturnMonitor.js`

#### Payments, receipts, and payment policy
The platform supports manually verified GCash/Maya evidence, with a fixed PHP 1 test-reservation policy after approval. It also contains PayMongo checkout/webhook integration, receipt generation, payment-method management, and refund eligibility/policy rules.
- `server/src/routes/payments.js`
- `server/src/routes/paymentMethods.js`
- `server/src/routes/paymongoWebhooks.js`
- `server/src/services/paymongoService.js`
- `server/src/services/receiptService.js`

#### Evidence-led rental operations
Operational routes manage pre-handover and post-return condition checks, required renter sign-off, and completion. Identity and requirements endpoints support renter verification and required booking documentation; stored uploads are an important persistence boundary.
- `server/src/routes/conditionChecks.js`
- `server/src/routes/identity.js`
- `server/src/routes/requirements.js`
- `server/uploads/vehicle-photos`

#### Fleet, telemetry, and communications
Vehicle inventory is managed through the vehicle API and host workflows. MQTT/GNSS telemetry is ingested for registered IoT devices, with a staff-only simulation path outside production. The API also supports direct messages, in-app notifications, booking reminders, and email delivery.
- `server/src/routes/vehicles.js`
- `server/src/routes/telemetry.js`
- `server/src/services/telemetryService.js`
- `server/src/routes/messages.js`
- `server/src/services/mailService.js`

#### Persistence and infrastructure
PostgreSQL is the system of record, accessed through the DB configuration and evolved by ordered SQL migrations tracked in `schema_migrations`. Runtime dependencies include Node.js/Fastify, PostgreSQL, JWT, MQTT broker connectivity, PayMongo, and local upload storage.
- `server/src/config/db.js`
- `server/db/schema.sql`
- `server/db/migrations/001_operations_upgrade.sql`
- `server/db/migrations/004_paymongo_checkout_webhooks.sql`
- `server/scripts/migrate.js`

Main entry points: [`server/src/routes/bookings.js`](https://github.com/zaantoru/p2p-ui/blob/main/server/src/routes/bookings.js) (Booking lifecycle), [`server/src/index.js`](https://github.com/zaantoru/p2p-ui/blob/main/server/src/index.js) (API server), [`server/src/middleware/auth.js`](https://github.com/zaantoru/p2p-ui/blob/main/server/src/middleware/auth.js) (Auth and access control), [`src/main.jsx`](https://github.com/zaantoru/p2p-ui/blob/main/src/main.jsx) (SPA entry and router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React SPA"]
  node_spa_entry["SPA entry and router<br/>React/Vite<br/>[main.jsx]"]
  node_auth_state["Authentication state<br/>React context<br/>[AuthContext.jsx]"]
  node_role_workspaces["Role workspaces<br/>React pages"]
  node_checkout["Checkout<br/>React page<br/>[Checkout.jsx]"]
end

subgraph group_api["Fastify API"]
  node_api_entry["API server<br/>Fastify<br/>[index.js]"]
  node_auth_routes["Auth and access control<br/>JWT middleware<br/>[auth.js]"]
  node_booking_lifecycle["Booking lifecycle<br/>Booking routes<br/>[bookings.js]"]
  node_availability["Availability control<br/>Overlap logic<br/>[bookingOverlap.js]"]
  node_operations["Rental operations<br/>Operations routes<br/>[operations.js]"]
  node_late_returns["Late return monitoring<br/>Background service"]
  node_payments["Payments and policy<br/>Payment routes<br/>[payments.js]"]
  node_paymongo["PayMongo integration<br/>Payment service<br/>[paymongoService.js]"]
  node_evidence["Identity and condition evidence<br/>Workflow routes<br/>[conditionChecks.js]"]
  node_fleet["Fleet inventory<br/>Vehicle routes<br/>[vehicles.js]"]
  node_telemetry["Telemetry ingestion<br/>Telemetry service"]
  node_communications["Messaging and notifications<br/>Communication services<br/>[messages.js]"]
end

subgraph group_persistence["Persistence"]
  node_postgres[("PostgreSQL<br/>System of record<br/>[db.js]")]
  node_migrations["Schema migrations<br/>SQL migration pipeline<br/>[migrate.js]"]
  node_uploads[("Local upload storage<br/>File storage")]
end

subgraph group_external["External services"]
  node_mqtt["MQTT broker<br/>IoT connectivity"]
  node_paymongo_provider["PayMongo<br/>Payment provider"]
end

node_spa_entry --> node_auth_state
node_spa_entry --> node_role_workspaces
node_spa_entry --> node_checkout
node_auth_state -->|"protected API requests"| node_api_entry
node_role_workspaces -->|"staff and renter workflows"| node_api_entry
node_checkout -->|"booking and payment"| node_api_entry
node_api_entry -->|"authenticates and authorizes"| node_auth_routes
node_auth_routes -->|"guards access"| node_booking_lifecycle
node_auth_routes -->|"guards access"| node_operations
node_auth_routes -->|"guards access"| node_payments
node_booking_lifecycle -->|"checks overlap and holds"| node_availability
node_booking_lifecycle -->|"requires payment after approval"| node_payments
node_booking_lifecycle -->|"drives rental workflow"| node_operations
node_booking_lifecycle -->|"monitors active rentals"| node_late_returns
node_operations -->|"requires condition evidence"| node_evidence
node_evidence -->|"stores evidence"| node_uploads
node_fleet -->|"stores vehicle photos"| node_uploads
node_payments -->|"checkout and webhook processing"| node_paymongo
node_paymongo -->|"payment API"| node_paymongo_provider
node_telemetry -->|"ingests device telemetry"| node_mqtt
node_booking_lifecycle -->|"booking notifications"| node_communications
node_api_entry -->|"domain persistence"| node_postgres
node_migrations -->|"evolves schema"| node_postgres

click node_spa_entry "https://github.com/zaantoru/p2p-ui/blob/main/src/main.jsx"
click node_auth_state "https://github.com/zaantoru/p2p-ui/blob/main/src/context/AuthContext.jsx"
click node_role_workspaces "https://github.com/zaantoru/p2p-ui/blob/main/src/pages/Dashboard/Renter/RenterDashboard.jsx"
click node_checkout "https://github.com/zaantoru/p2p-ui/blob/main/src/pages/Checkout/Checkout.jsx"
click node_api_entry "https://github.com/zaantoru/p2p-ui/blob/main/server/src/index.js"
click node_auth_routes "https://github.com/zaantoru/p2p-ui/blob/main/server/src/middleware/auth.js"
click node_booking_lifecycle "https://github.com/zaantoru/p2p-ui/blob/main/server/src/routes/bookings.js"
click node_availability "https://github.com/zaantoru/p2p-ui/blob/main/server/src/utils/bookingOverlap.js"
click node_operations "https://github.com/zaantoru/p2p-ui/blob/main/server/src/routes/operations.js"
click node_late_returns "https://github.com/zaantoru/p2p-ui/blob/main/server/src/services/lateReturnMonitor.js"
click node_payments "https://github.com/zaantoru/p2p-ui/blob/main/server/src/routes/payments.js"
click node_paymongo "https://github.com/zaantoru/p2p-ui/blob/main/server/src/services/paymongoService.js"
click node_evidence "https://github.com/zaantoru/p2p-ui/blob/main/server/src/routes/conditionChecks.js"
click node_fleet "https://github.com/zaantoru/p2p-ui/blob/main/server/src/routes/vehicles.js"
click node_telemetry "https://github.com/zaantoru/p2p-ui/blob/main/server/src/services/telemetryService.js"
click node_communications "https://github.com/zaantoru/p2p-ui/blob/main/server/src/routes/messages.js"
click node_postgres "https://github.com/zaantoru/p2p-ui/blob/main/server/src/config/db.js"
click node_migrations "https://github.com/zaantoru/p2p-ui/blob/main/server/scripts/migrate.js"
click node_uploads "https://github.com/zaantoru/p2p-ui/tree/main/server/uploads/vehicle-photos"

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_spa_entry,node_auth_state,node_role_workspaces,node_checkout toneBlue
class node_api_entry,node_auth_routes,node_booking_lifecycle,node_availability,node_operations,node_late_returns,node_payments,node_paymongo,node_evidence,node_fleet,node_telemetry,node_communications toneAmber
class node_postgres,node_migrations,node_uploads toneMint
class node_mqtt,node_paymongo_provider toneRose
```

## Components

### React SPA

- [SPA entry and router](https://github.com/zaantoru/p2p-ui/blob/main/src/main.jsx): React/Vite · `src/main.jsx`
- [Authentication state](https://github.com/zaantoru/p2p-ui/blob/main/src/context/AuthContext.jsx): React context · Centralizes identity before protected API calls. · `src/context/AuthContext.jsx`
- [Role workspaces](https://github.com/zaantoru/p2p-ui/blob/main/src/pages/Dashboard/Renter/RenterDashboard.jsx): React pages · Renter, operations, and admin dashboards select server-issued roles. · `src/pages/Dashboard/Renter/RenterDashboard.jsx`
- [Checkout](https://github.com/zaantoru/p2p-ui/blob/main/src/pages/Checkout/Checkout.jsx): React page · `src/pages/Checkout/Checkout.jsx`

### Fastify API

- [API server](https://github.com/zaantoru/p2p-ui/blob/main/server/src/index.js): Fastify · Serves domain routes and proxied uploads. · `server/src/index.js`
- [Auth and access control](https://github.com/zaantoru/p2p-ui/blob/main/server/src/middleware/auth.js): JWT middleware · JWT authentication and role guards protect domain actions. · `server/src/middleware/auth.js`
- [Booking lifecycle](https://github.com/zaantoru/p2p-ui/blob/main/server/src/routes/bookings.js): Booking routes · Coordinates approval, payment, scheduling, ongoing, and completion states. · `server/src/routes/bookings.js`
- [Availability control](https://github.com/zaantoru/p2p-ui/blob/main/server/src/utils/bookingOverlap.js): Overlap logic · Prevents conflicting reservations and holds. · `server/src/utils/bookingOverlap.js`
- [Rental operations](https://github.com/zaantoru/p2p-ui/blob/main/server/src/routes/operations.js): Operations routes · Manages handover, return workflow, and completion. · `server/src/routes/operations.js`
- [Late return monitoring](https://github.com/zaantoru/p2p-ui/blob/main/server/src/services/lateReturnMonitor.js): Background service · Separates late status and fee calculation from booking state. · `server/src/services/lateReturnMonitor.js`
- [Payments and policy](https://github.com/zaantoru/p2p-ui/blob/main/server/src/routes/payments.js): Payment routes · Handles manual evidence, test-reservation policy, refunds, and methods. · `server/src/routes/payments.js`
- [PayMongo integration](https://github.com/zaantoru/p2p-ui/blob/main/server/src/services/paymongoService.js): Payment service · Creates checkout sessions and processes webhooks. · `server/src/services/paymongoService.js`
- [Identity and condition evidence](https://github.com/zaantoru/p2p-ui/blob/main/server/src/routes/conditionChecks.js): Workflow routes · Captures verification, requirements, condition checks, and sign-off. · `server/src/routes/conditionChecks.js`
- [Fleet inventory](https://github.com/zaantoru/p2p-ui/blob/main/server/src/routes/vehicles.js): Vehicle routes · `server/src/routes/vehicles.js`
- [Telemetry ingestion](https://github.com/zaantoru/p2p-ui/blob/main/server/src/services/telemetryService.js): Telemetry service · Ingests GNSS data for registered IoT devices. · `server/src/services/telemetryService.js`
- [Messaging and notifications](https://github.com/zaantoru/p2p-ui/blob/main/server/src/routes/messages.js): Communication services · Supports direct messages, reminders, in-app notifications, and email. · `server/src/routes/messages.js`

### Persistence

- [PostgreSQL](https://github.com/zaantoru/p2p-ui/blob/main/server/src/config/db.js): System of record · `server/src/config/db.js`
- [Schema migrations](https://github.com/zaantoru/p2p-ui/blob/main/server/scripts/migrate.js): SQL migration pipeline · Ordered migrations are tracked in schema_migrations. · `server/scripts/migrate.js`
- [Local upload storage](https://github.com/zaantoru/p2p-ui/tree/main/server/uploads/vehicle-photos): File storage · Stores vehicle photos and workflow evidence. · `server/uploads/vehicle-photos`

### External services

- **MQTT broker**: IoT connectivity
- **PayMongo**: Payment provider

## Connections

- SPA entry and router → Authentication state
- SPA entry and router → Role workspaces
- SPA entry and router → Checkout
- Authentication state → API server: protected API requests
- Role workspaces → API server: staff and renter workflows
- Checkout → API server: booking and payment
- API server → Auth and access control: authenticates and authorizes
- Auth and access control → Booking lifecycle: guards access
- Auth and access control → Rental operations: guards access
- Auth and access control → Payments and policy: guards access
- Booking lifecycle → Availability control: checks overlap and holds
- Booking lifecycle → Payments and policy: requires payment after approval
- Booking lifecycle → Rental operations: drives rental workflow
- Booking lifecycle → Late return monitoring: monitors active rentals
- Rental operations → Identity and condition evidence: requires condition evidence
- Identity and condition evidence → Local upload storage: stores evidence
- Fleet inventory → Local upload storage: stores vehicle photos
- Payments and policy → PayMongo integration: checkout and webhook processing
- PayMongo integration → PayMongo: payment API
- Telemetry ingestion → MQTT broker: ingests device telemetry
- Booking lifecycle → Messaging and notifications: booking notifications
- API server → PostgreSQL: domain persistence
- Schema migrations → PostgreSQL: evolves schema