rayan569916/fleetflow

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.