# rayan569916/fleetflow architecture

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

- Interactive diagram: https://gitdiagram.com/rayan569916/fleetflow
- Repository: https://github.com/rayan569916/fleetflow

## Overview

1. This repo is a monorepo with two main runtime surfaces: a Flask-based backend API under `backend/`, and an Angular 21 dashboard frontend under `fleetflow-dashboard/`. The frontend is the primary operator UI; the backend is the data/API layer that serves it.

2. The backend entrypoint is `backend/app.py`, with environment-specific configuration in `config.py`, `config_local.py`, and `config_development.py`. `extensions.py` centralizes shared Flask extensions, and the rest of the backend is organized as Blueprints/routes by domain.

3. Backend persistence is model-driven. `backend/models/` contains the core domain entities for logistics and finance: users, customers, shipments, tracking, invoices, fleet/drivers, cargo requests, item lists, unit prices, reports, balance sharing, featured offers, push subscriptions, and finance-related objects. The presence of `db_bundle/bundle.sql` and maintenance scripts like `fix_db.py`, `check_schema.py`, and `seed.py` indicates a relational schema with scripted migration/repair workflows.

4. The backend API boundary is split by functional area in `backend/routes/`: auth, dashboard, shipments, tracking, invoices, finance, fleet, reports, unit price, featured offers, balance share, cargo mobile/dashboard, loading list, general utilities, and customer support details. There are also mobile-specific routes (`auth_mobile.py`, `cargo_mobile.py`), which suggests the same backend serves both browser and mobile clients.

5. Business logic that is not just request/response handling lives in `backend/services/`. These include dashboard aggregation, password recovery, push notifications, and WhatsApp messaging. That means the API layer delegates outward-facing side effects and composite workflows to service modules rather than embedding them in routes.

6. Cross-cutting concerns are isolated in `backend/utils/`, especially authentication helpers and report-generation utilities. This separation is important because auth and reporting are used across multiple route groups rather than being tied to one domain.

7. The frontend uses Angular standalone components with a clear shell-and-feature split. `src/app/layout/` defines the global chrome (`dashboard-layout`, `header`, `sidebar`, plus a login/signup layout and transaction layout), while `src/app/dashboard/` contains feature pages for cargo requests, shipments, tracking, invoices, drivers, reports, settings, notifications, offices, and related widgets.

8. The Angular app’s state/data boundary is service-centric. `src/app/services/` holds domain services that call the backend API (`auth`, `shipment`, `invoice`, `report`, `unit-price`, `featured-offers`, `balance-share`, `cargo-request`, `dashboard-data`, `transaction`, `user`, etc.). Shared UI state such as sidebar expansion is kept in `UiStateService`, and `DashboardDataService` provides centralized dashboard streams.

9. Frontend request flow is guarded and intercepted. `auth.interceptor.ts` attaches auth context to outbound requests, `error.interceptor.ts` normalizes API failures, and route guards (`role.guard.ts`, `pending-changes.guard.ts`) enforce access control and prevent accidental navigation away from edited forms. This makes auth and permissions a first-class architecture boundary in the UI.

10. The dashboard UI is composed from reusable widgets under `src/app/shared/` and `src/app/core/`. Shared components include confirmation dialogs, toast notifications, card/status/transaction primitives, and mobile navigation. Core constants and typed models centralize dashboard-specific contracts so feature components stay thin.

11. Deployment is containerized and production-oriented. The root contains a `Dockerfile`, `docker-compose.yml`, and Nginx configuration under `deployment/nginx/`, while the Angular app has its own `Dockerfile`, `nginx.conf`, and service worker config. That implies the frontend is built as static assets and served behind Nginx, with the backend exposed separately or proxied.

12. The main runtime data flow is: user interacts with the Angular dashboard, Angular services call Flask API routes, Flask routes validate/authenticate and delegate to domain services, services read/write the underlying database models, and side-effect services may send push notifications or WhatsApp messages. File uploads are also part of the backend boundary, with `backend/uploads/offers/` indicating persisted media tied to featured offers.

Main entry points: [`backend/routes`](https://github.com/rayan569916/fleetflow/tree/main/backend/routes) (Routes), [`backend/app.py`](https://github.com/rayan569916/fleetflow/blob/main/backend/app.py) (App entry), [`fleetflow-dashboard/src/app/layout`](https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/layout) (Shell layout), [`fleetflow-dashboard/src/app/dashboard`](https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/dashboard) (Dashboard pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Flask backend"]
  node_backend_app["App entry<br/>flask entrypoint<br/>[app.py]"]
  node_backend_config["Config<br/>[config.py]"]
  node_backend_extensions["Extensions<br/>flask shared deps<br/>[extensions.py]"]
  node_backend_routes{{"Routes<br/>api blueprints"}}
  node_backend_services["Services<br/>workflow layer"]
  node_backend_models[("Models<br/>domain schema")]
  node_backend_utils["Utils<br/>cross-cutting helpers"]
  node_backend_db["DB bundle<br/>schema scripts<br/>[bundle.sql]"]
  node_backend_uploads[("Offer media<br/>asset storage")]
end

subgraph group_frontend["Angular dashboard"]
  node_frontend_shell["Shell layout<br/>ui chrome"]
  node_frontend_features["Dashboard pages<br/>feature screens"]
  node_frontend_services["API services<br/>data access"]
  node_frontend_core["Core<br/>contracts"]
  node_frontend_guards{{"Guards<br/>route control"}}
  node_frontend_interceptors{{"Interceptors<br/>request pipeline"}}
  node_frontend_shared["Shared UI<br/>reusable components"]
  node_frontend_build["Angular build<br/>spa packaging"]
end

subgraph group_deployment["Deployment"]
  node_deployment_root["Container build<br/>deployment"]
  node_deployment_nginx["Nginx config<br/>edge proxy<br/>[captaincargo.conf]"]
end

node_backend_app -->|"loads"| node_backend_config
node_backend_app -->|"initializes"| node_backend_extensions
node_backend_app -->|"registers"| node_backend_routes
node_backend_routes -->|"delegates"| node_backend_services
node_backend_routes -->|"uses"| node_backend_utils
node_backend_services -->|"reads/writes"| node_backend_models
node_backend_utils -.->|"supports"| node_backend_models
node_backend_models -.->|"backed by"| node_backend_db
node_backend_routes -.->|"stores media"| node_backend_uploads
node_frontend_shell -->|"hosts"| node_frontend_features
node_frontend_features -->|"calls"| node_frontend_services
node_frontend_services -->|"requests"| node_backend_routes
node_frontend_services -.->|"types"| node_frontend_core
node_frontend_shell -->|"composes"| node_frontend_shared
node_frontend_features -->|"composes"| node_frontend_shared
node_frontend_interceptors -->|"wraps"| node_frontend_services
node_frontend_guards -->|"protects"| node_frontend_shell
node_frontend_guards -->|"protects"| node_frontend_features
node_frontend_build -->|"packages"| node_frontend_shell
node_deployment_root -->|"ships"| node_backend_app
node_deployment_root -->|"ships"| node_frontend_build
node_deployment_nginx -->|"serves"| node_frontend_build
node_deployment_nginx -.->|"proxies"| node_backend_routes

click node_backend_app "https://github.com/rayan569916/fleetflow/blob/main/backend/app.py"
click node_backend_config "https://github.com/rayan569916/fleetflow/blob/main/backend/config.py"
click node_backend_extensions "https://github.com/rayan569916/fleetflow/blob/main/backend/extensions.py"
click node_backend_routes "https://github.com/rayan569916/fleetflow/tree/main/backend/routes"
click node_backend_services "https://github.com/rayan569916/fleetflow/tree/main/backend/services"
click node_backend_models "https://github.com/rayan569916/fleetflow/tree/main/backend/models"
click node_backend_utils "https://github.com/rayan569916/fleetflow/tree/main/backend/utils"
click node_backend_db "https://github.com/rayan569916/fleetflow/blob/main/backend/models/db_bundle/bundle.sql"
click node_backend_uploads "https://github.com/rayan569916/fleetflow/tree/main/backend/uploads/offers"
click node_frontend_shell "https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/layout"
click node_frontend_features "https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/dashboard"
click node_frontend_services "https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/services"
click node_frontend_core "https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/core"
click node_frontend_guards "https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/guards"
click node_frontend_interceptors "https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/core/interceptors"
click node_frontend_shared "https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/shared"
click node_deployment_root "https://github.com/rayan569916/fleetflow/tree/main/Dockerfile"
click node_deployment_nginx "https://github.com/rayan569916/fleetflow/blob/main/deployment/nginx/captaincargo.conf"
click node_frontend_build "https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/Dockerfile"

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_backend_app,node_backend_config,node_backend_extensions,node_backend_routes,node_backend_services,node_backend_models,node_backend_utils,node_backend_db,node_backend_uploads toneBlue
class node_frontend_shell,node_frontend_features,node_frontend_services,node_frontend_core,node_frontend_guards,node_frontend_interceptors,node_frontend_shared,node_frontend_build toneAmber
class node_deployment_root,node_deployment_nginx toneMint
```

## Components

### Flask backend

API server, domain models, services, and persistence workflows.

- [App entry](https://github.com/rayan569916/fleetflow/blob/main/backend/app.py): flask entrypoint · Creates and wires the Flask application. · `backend/app.py`
- [Config](https://github.com/rayan569916/fleetflow/blob/main/backend/config.py): env config · Environment-specific Flask configuration. · `backend/config.py`
- [Extensions](https://github.com/rayan569916/fleetflow/blob/main/backend/extensions.py): flask shared deps · Centralized Flask extensions and shared integrations. · `backend/extensions.py`
- [Routes](https://github.com/rayan569916/fleetflow/tree/main/backend/routes): api blueprints · HTTP boundary split into feature-specific Blueprints. · `backend/routes`
- [Services](https://github.com/rayan569916/fleetflow/tree/main/backend/services): workflow layer · Composite business logic and outbound side effects. · `backend/services`
- [Models](https://github.com/rayan569916/fleetflow/tree/main/backend/models): domain schema · Relational domain entities for logistics and finance. · `backend/models`
- [Utils](https://github.com/rayan569916/fleetflow/tree/main/backend/utils): cross-cutting helpers · Authentication and reporting helpers reused across routes. · `backend/utils`
- [DB bundle](https://github.com/rayan569916/fleetflow/blob/main/backend/models/db_bundle/bundle.sql): schema scripts · Bundle SQL and repair scripts for schema maintenance. · `backend/models/db_bundle/bundle.sql`
- [Offer media](https://github.com/rayan569916/fleetflow/tree/main/backend/uploads/offers): asset storage · Persisted upload area for featured offer media. · `backend/uploads/offers`

### Angular dashboard

Operator UI, client services, layouts, and reusable components.

- [Shell layout](https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/layout): ui chrome · Global dashboard layout, header, sidebar, and auth shells. · `fleetflow-dashboard/src/app/layout`
- [Dashboard pages](https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/dashboard): feature screens · Operator-facing feature pages and widgets. · `fleetflow-dashboard/src/app/dashboard`
- [API services](https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/services): data access · Client-side services that call backend API routes. · `fleetflow-dashboard/src/app/services`
- [Core](https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/core): contracts · Typed models, constants, and client-wide shared definitions. · `fleetflow-dashboard/src/app/core`
- [Guards](https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/guards): route control · Route access and navigation protection for the UI. · `fleetflow-dashboard/src/app/guards`
- [Interceptors](https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/core/interceptors): request pipeline · Auth attachment and API error normalization for requests. · `fleetflow-dashboard/src/app/core/interceptors`
- [Shared UI](https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/src/app/shared): reusable components · Common dialogs, toasts, and dashboard primitives. · `fleetflow-dashboard/src/app/shared`
- [Angular build](https://github.com/rayan569916/fleetflow/tree/main/fleetflow-dashboard/Dockerfile): spa packaging · Frontend build, service worker, and Nginx runtime config. · `fleetflow-dashboard/Dockerfile`

### Deployment

Container and Nginx packaging for backend and frontend.

- [Container build](https://github.com/rayan569916/fleetflow/tree/main/Dockerfile): deployment · Root Docker and compose setup for the monorepo. · `Dockerfile`
- [Nginx config](https://github.com/rayan569916/fleetflow/blob/main/deployment/nginx/captaincargo.conf): edge proxy · Nginx configuration for serving or proxying the app. · `deployment/nginx/captaincargo.conf`

## Connections

- App entry → Config: loads · App startup reads environment configuration.
- App entry → Extensions: initializes · Application wiring installs shared extensions.
- App entry → Routes: registers · The entrypoint mounts domain blueprints.
- Routes → Services: delegates · Request handlers call into business workflows.
- Routes → Utils: uses · Routes reuse auth and reporting helpers.
- Services → Models: reads/writes · Services persist and query domain entities.
- Utils → Models: supports · Helpers operate across model-backed features.
- Models → DB bundle: backed by · Models are reflected in bundled schema scripts.
- Routes → Offer media: stores media · Feature routes persist uploaded offer assets.
- Shell layout → Dashboard pages: hosts · Layout shells render the main dashboard pages.
- Dashboard pages → API services: calls · Feature components fetch and mutate via services.
- API services → Routes: requests · Client services consume the Flask API boundary.
- API services → Core: types · Services share client contracts and constants.
- Shell layout → Shared UI: composes · Layouts use reusable shared UI primitives.
- Dashboard pages → Shared UI: composes · Pages build from shared widgets and controls.
- Interceptors → API services: wraps · Interceptors sit in the HTTP request pipeline.
- Guards → Shell layout: protects · Route guards constrain access to dashboard areas.
- Guards → Dashboard pages: protects · Feature routes are gated by role and pending-changes checks.
- Angular build → Shell layout: packages · Angular app is built and served as static assets.
- Container build → App entry: ships · Container build includes the Flask backend runtime.
- Container build → Angular build: ships · Container build includes the frontend runtime image.
- Nginx config → Angular build: serves · Nginx serves the compiled Angular dashboard.
- Nginx config → Routes: proxies · Proxy configuration can forward API traffic to Flask.