# deenmj/flexify architecture

> Architecture diagram of the GitHub repository deenmj/flexify, 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/deenmj/flexify
- Repository: https://github.com/deenmj/flexify

## Overview

#### Purpose and entry points
Flexify is a vehicle marketplace/rental platform with user, owner, staff, admin, and super-admin workflows. It supports vehicle listings, bookings, sales listings, reviews, banking details, notifications, verification, and operational settings.

Primary runtime entry points:
- Backend HTTP server: `backend/server.js`
- Frontend application bootstrap and routing shell: `flexify-app/src/main.tsx`, `flexify-app/src/App.tsx`
- Frontend API boundary: `flexify-app/src/api.ts`

#### Client application
The client is a Vite TypeScript React application. `App.tsx` is the page-composition and route boundary; pages implement public discovery, account, dashboard, listing, booking-adjacent vehicle detail, and administration experiences.

Important UI domains:
- Discovery and listing flow: `flexify-app/src/pages/Explore.tsx`, `flexify-app/src/pages/VehicleDetail.tsx`, `flexify-app/src/pages/ListVehicle.tsx`
- Role-specific operational consoles: `flexify-app/src/pages/Dashboard.tsx`, `flexify-app/src/pages/AdminDashboard.tsx`, `flexify-app/src/pages/SuperAdminDashboard.tsx`
- Sale inventory flow: `flexify-app/src/pages/VehicleSalesGallery.tsx`, `flexify-app/src/pages/VehicleSaleDetails.tsx`, `flexify-app/src/components/AddVehicleSale.tsx`

`flexify-app/src/components/ProtectedRoute.tsx` forms the client-side access-control boundary.

#### Identity, authorization, and realtime state
Authentication state is centralized in `flexify-app/src/context/AuthContext.tsx`; socket lifecycle/state is isolated in `flexify-app/src/context/SocketContext.tsx`. The backend authenticates requests through `backend/middleware/authMiddleware.js` and configures passport-based identity integration in `backend/config/passport.js`.

Authentication endpoints are exposed separately from domain routes in `backend/routes/auth.js`. Role-oriented administration is partitioned into admin, subadmin, and super-admin route groups:
- `backend/routes/adminRoutes.js`
- `backend/routes/subadminRoutes.js`
- `backend/routes/superAdminRoutes.js`

#### API and domain orchestration
The backend is a Node.js HTTP API organized as routes → controllers → models. Routes are the public API boundary; controllers coordinate validation, authorization, persistence, and side effects.

Core business areas:
- Vehicle catalog, makes/models, owner management: `backend/routes/vehicleRoutes.js`, `backend/controllers/vehicleController.js`, `backend/models/Vehicle.js`
- Booking lifecycle and availability blackouts: `backend/routes/bookingRoutes.js`, `backend/controllers/bookingController.js`, `backend/models/booking.js`
- Sales inventory: `backend/routes/salesRoutes.js`, `backend/models/VehicleSale.js`
- Reviews and feedback: `backend/routes/reviewRoutes.js`, `backend/controllers/reviewController.js`, `backend/models/Review.js`
- Settings and maintenance controls: `backend/routes/settingsRoutes.js`, `backend/middleware/maintenanceGuard.js`, `backend/models/Settings.js`

#### Persistence and audit boundaries
Persistence configuration is centralized at `backend/config/db.js`. The model layer represents users/staff, vehicles, bookings, payments, notifications, verification-related banking details, and audit records.

Key records:
- Accounts and staff: `backend/models/User.js`, `backend/models/Staff.js`
- Financial and bank data: `backend/models/Payment.js`, `backend/models/BankDetails.js`
- Auditable operational actions: `backend/models/AuditLog.js`, `backend/utils/auditLogger.js`

#### External services and asset handling
The service integrates external infrastructure behind utility boundaries:
- Cloud-hosted media: `backend/utils/cloudinary.js`
- File upload handling and local verification uploads: `backend/utils/upload.js`, `backend/uploads/verification`
- Email delivery: `backend/utils/sendEmail.js`
- Notification dispatch: `backend/utils/notifier.js`

Frontend deployment is configured for Vercel through `flexify-app/vercel.json`. Environment-specific backend configuration is expected through `backend/.env.development` and `backend/.env.example`.

Main entry points: [`flexify-app/src/App.tsx`](https://github.com/deenmj/flexify/blob/main/flexify-app/src/App.tsx) (App bootstrap & routes), [`backend/controllers/vehicleController.js`](https://github.com/deenmj/flexify/blob/main/backend/controllers/vehicleController.js) (Domain controllers), [`backend/server.js`](https://github.com/deenmj/flexify/blob/main/backend/server.js) (HTTP server), [`backend/routes/vehicleRoutes.js`](https://github.com/deenmj/flexify/blob/main/backend/routes/vehicleRoutes.js) (Marketplace API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_client_bootstrap["App bootstrap &amp; routes<br/>React application<br/>[App.tsx]"]
  node_client_api["API client<br/>HTTP boundary<br/>[api.ts]"]
  node_auth_state["Auth state<br/>React context<br/>[AuthContext.tsx]"]
  node_socket_state["Socket state<br/>React context<br/>[SocketContext.tsx]"]
  node_protected_route["Protected routes<br/>access boundary<br/>[ProtectedRoute.tsx]"]
  node_marketplace_ui["Marketplace &amp; listings<br/>page flow<br/>[Explore.tsx]"]
  node_operations_ui["Role dashboards<br/>page flow<br/>[Dashboard.tsx]"]
  node_sales_ui["Sales inventory UI<br/>page flow"]
end

subgraph group_api["Node API"]
  node_server["HTTP server<br/>Node entry point<br/>[server.js]"]
  node_auth_routes["Authentication API<br/>route group<br/>[auth.js]"]
  node_domain_routes["Marketplace API<br/>route group<br/>[vehicleRoutes.js]"]
  node_admin_routes["Admin APIs<br/>route groups<br/>[adminRoutes.js]"]
  node_auth_middleware["Auth &amp; roles<br/>middleware<br/>[authMiddleware.js]"]
  node_controllers["Domain controllers<br/>orchestration layer"]
  node_maintenance_guard["Maintenance guard<br/>middleware"]
end

subgraph group_data["Persistence &amp; integrations"]
  node_models[("Business records<br/>model layer<br/>[Vehicle.js]")]
  node_database[("Database connection<br/>persistence config<br/>[db.js]")]
  node_audit["Audit logging<br/>audit boundary<br/>[auditLogger.js]"]
  node_integrations["Media, uploads &amp; messaging<br/>service utilities<br/>[cloudinary.js]"]
end

node_client_bootstrap -->|"uses"| node_auth_state
node_client_bootstrap -->|"uses"| node_socket_state
node_client_bootstrap -->|"gates console routes"| node_protected_route
node_client_bootstrap -->|"renders"| node_marketplace_ui
node_client_bootstrap -->|"renders"| node_operations_ui
node_client_bootstrap -->|"renders"| node_sales_ui
node_marketplace_ui -->|"catalog &amp; booking calls"| node_client_api
node_operations_ui -->|"operational calls"| node_client_api
node_sales_ui -->|"sales calls"| node_client_api
node_client_api -->|"HTTP requests"| node_server
node_server -->|"mounts"| node_auth_routes
node_server -->|"mounts"| node_domain_routes
node_server -->|"mounts"| node_admin_routes
node_auth_routes -->|"authenticates"| node_auth_middleware
node_domain_routes -->|"protects endpoints"| node_auth_middleware
node_admin_routes -->|"enforces roles"| node_auth_middleware
node_domain_routes -->|"checks maintenance"| node_maintenance_guard
node_auth_routes -->|"dispatches"| node_controllers
node_domain_routes -->|"dispatches"| node_controllers
node_admin_routes -->|"dispatches"| node_controllers
node_controllers -->|"reads and writes"| node_models
node_models -->|"persists through"| node_database
node_controllers -.->|"records actions"| node_audit
node_controllers -->|"uploads and notifies"| node_integrations

click node_client_bootstrap "https://github.com/deenmj/flexify/blob/main/flexify-app/src/App.tsx"
click node_client_api "https://github.com/deenmj/flexify/blob/main/flexify-app/src/api.ts"
click node_auth_state "https://github.com/deenmj/flexify/blob/main/flexify-app/src/context/AuthContext.tsx"
click node_socket_state "https://github.com/deenmj/flexify/blob/main/flexify-app/src/context/SocketContext.tsx"
click node_protected_route "https://github.com/deenmj/flexify/blob/main/flexify-app/src/components/ProtectedRoute.tsx"
click node_marketplace_ui "https://github.com/deenmj/flexify/blob/main/flexify-app/src/pages/Explore.tsx"
click node_operations_ui "https://github.com/deenmj/flexify/blob/main/flexify-app/src/pages/Dashboard.tsx"
click node_sales_ui "https://github.com/deenmj/flexify/blob/main/flexify-app/src/pages/VehicleSalesGallery.tsx"
click node_server "https://github.com/deenmj/flexify/blob/main/backend/server.js"
click node_auth_routes "https://github.com/deenmj/flexify/blob/main/backend/routes/auth.js"
click node_domain_routes "https://github.com/deenmj/flexify/blob/main/backend/routes/vehicleRoutes.js"
click node_admin_routes "https://github.com/deenmj/flexify/blob/main/backend/routes/adminRoutes.js"
click node_auth_middleware "https://github.com/deenmj/flexify/blob/main/backend/middleware/authMiddleware.js"
click node_controllers "https://github.com/deenmj/flexify/blob/main/backend/controllers/vehicleController.js"
click node_maintenance_guard "https://github.com/deenmj/flexify/blob/main/backend/middleware/maintenanceGuard.js"
click node_models "https://github.com/deenmj/flexify/blob/main/backend/models/Vehicle.js"
click node_database "https://github.com/deenmj/flexify/blob/main/backend/config/db.js"
click node_audit "https://github.com/deenmj/flexify/blob/main/backend/utils/auditLogger.js"
click node_integrations "https://github.com/deenmj/flexify/blob/main/backend/utils/cloudinary.js"

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_client_bootstrap,node_client_api,node_auth_state,node_socket_state,node_protected_route,node_marketplace_ui,node_operations_ui,node_sales_ui toneBlue
class node_server,node_auth_routes,node_domain_routes,node_admin_routes,node_auth_middleware,node_controllers,node_maintenance_guard toneAmber
class node_models,node_database,node_audit,node_integrations toneMint
```

## Components

### React client

- [App bootstrap & routes](https://github.com/deenmj/flexify/blob/main/flexify-app/src/App.tsx): React application · Composes pages and routing. · `flexify-app/src/App.tsx`
- [API client](https://github.com/deenmj/flexify/blob/main/flexify-app/src/api.ts): HTTP boundary · `flexify-app/src/api.ts`
- [Auth state](https://github.com/deenmj/flexify/blob/main/flexify-app/src/context/AuthContext.tsx): React context · `flexify-app/src/context/AuthContext.tsx`
- [Socket state](https://github.com/deenmj/flexify/blob/main/flexify-app/src/context/SocketContext.tsx): React context · `flexify-app/src/context/SocketContext.tsx`
- [Protected routes](https://github.com/deenmj/flexify/blob/main/flexify-app/src/components/ProtectedRoute.tsx): access boundary · `flexify-app/src/components/ProtectedRoute.tsx`
- [Marketplace & listings](https://github.com/deenmj/flexify/blob/main/flexify-app/src/pages/Explore.tsx): page flow · Discovery, vehicle detail, and owner listing flow. · `flexify-app/src/pages/Explore.tsx`
- [Role dashboards](https://github.com/deenmj/flexify/blob/main/flexify-app/src/pages/Dashboard.tsx): page flow · User, admin, and super-admin operations. · `flexify-app/src/pages/Dashboard.tsx`
- [Sales inventory UI](https://github.com/deenmj/flexify/blob/main/flexify-app/src/pages/VehicleSalesGallery.tsx): page flow · `flexify-app/src/pages/VehicleSalesGallery.tsx`

### Node API

- [HTTP server](https://github.com/deenmj/flexify/blob/main/backend/server.js): Node entry point · `backend/server.js`
- [Authentication API](https://github.com/deenmj/flexify/blob/main/backend/routes/auth.js): route group · `backend/routes/auth.js`
- [Marketplace API](https://github.com/deenmj/flexify/blob/main/backend/routes/vehicleRoutes.js): route group · Vehicle, booking, sales, review, and settings endpoints. · `backend/routes/vehicleRoutes.js`
- [Admin APIs](https://github.com/deenmj/flexify/blob/main/backend/routes/adminRoutes.js): route groups · Admin, subadmin, and super-admin endpoints. · `backend/routes/adminRoutes.js`
- [Auth & roles](https://github.com/deenmj/flexify/blob/main/backend/middleware/authMiddleware.js): middleware · Authenticates requests and applies role access. · `backend/middleware/authMiddleware.js`
- [Domain controllers](https://github.com/deenmj/flexify/blob/main/backend/controllers/vehicleController.js): orchestration layer · Coordinates validation, authorization, persistence, and side effects. · `backend/controllers/vehicleController.js`
- [Maintenance guard](https://github.com/deenmj/flexify/blob/main/backend/middleware/maintenanceGuard.js): middleware · `backend/middleware/maintenanceGuard.js`

### Persistence & integrations

- [Business records](https://github.com/deenmj/flexify/blob/main/backend/models/Vehicle.js): model layer · Users, vehicles, bookings, payments, notifications, and settings. · `backend/models/Vehicle.js`
- [Database connection](https://github.com/deenmj/flexify/blob/main/backend/config/db.js): persistence config · `backend/config/db.js`
- [Audit logging](https://github.com/deenmj/flexify/blob/main/backend/utils/auditLogger.js): audit boundary · `backend/utils/auditLogger.js`
- [Media, uploads & messaging](https://github.com/deenmj/flexify/blob/main/backend/utils/cloudinary.js): service utilities · Cloud media, verification uploads, email, and notifications. · `backend/utils/cloudinary.js`

## Connections

- App bootstrap & routes → Auth state: uses
- App bootstrap & routes → Socket state: uses
- App bootstrap & routes → Protected routes: gates console routes
- App bootstrap & routes → Marketplace & listings: renders
- App bootstrap & routes → Role dashboards: renders
- App bootstrap & routes → Sales inventory UI: renders
- Marketplace & listings → API client: catalog & booking calls
- Role dashboards → API client: operational calls
- Sales inventory UI → API client: sales calls
- API client → HTTP server: HTTP requests
- HTTP server → Authentication API: mounts
- HTTP server → Marketplace API: mounts
- HTTP server → Admin APIs: mounts
- Authentication API → Auth & roles: authenticates
- Marketplace API → Auth & roles: protects endpoints
- Admin APIs → Auth & roles: enforces roles
- Marketplace API → Maintenance guard: checks maintenance
- Authentication API → Domain controllers: dispatches
- Marketplace API → Domain controllers: dispatches
- Admin APIs → Domain controllers: dispatches
- Domain controllers → Business records: reads and writes
- Business records → Database connection: persists through
- Domain controllers → Audit logging: records actions
- Domain controllers → Media, uploads & messaging: uploads and notifies