# saqibak001/transl architecture

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

- Interactive diagram: https://gitdiagram.com/saqibak001/transl
- Repository: https://github.com/saqibak001/transl

## Overview

1. **Overall shape**
   This is a two-tier product: a React single-page frontend and a FastAPI backend. The backend owns authentication, matching, route/load optimization, and persistence; the frontend handles user flows and calls the backend over HTTP.

2. **User-facing frontend**
   `frontend/src` is organized around pages and reusable components. The main screens are `Landing`, `Auth/Login/Register`, `Dashboard`, `Matches`, `MatchDetails`, `Postload`, `Profile`, and `RegisterTruck`. `Navbar` and the protected-route components wrap the app’s navigation and access control.

3. **Frontend data access**
   The frontend does not appear to embed business logic; it likely uses `src/services/api.js` as the single API client layer. That creates a clean boundary between UI state and backend operations, which is important for diagramming the request flow.

4. **Backend API layer**
   `backend/app/api` is the HTTP boundary. The routes are split by domain: `auth`, `cargo`, `trucks`, `matching`, `match_details`, `my_matches`, and `history`. This suggests the backend exposes both command endpoints (create/register/match) and read endpoints for user-specific views.

5. **Core business logic**
   `backend/app/services` contains the domain engine:
   - `matching_engine.py` handles cargo-to-truck pairing logic
   - `load_optimizer.py` handles bin-packing / capacity utilization
   - `route_optimizer.py` handles delivery sequencing and multi-drop planning  
   These services are the heart of the system and should sit in the middle of any architecture diagram, between API controllers and storage.

6. **Auth and security boundary**
   `backend/app/core/security.py` and `backend/app/api/auth.py` indicate the system has real user accounts and protected resources. The frontend’s protected-route components mirror this, so authentication is enforced on both client and server sides.

7. **Persistence layer**
   The repo shows two persistence-related paths: `backend/app/db/session.py` and `backend/app/db/mongodb.py`, plus `backend/app/core/mongo.py`. The README mentions SQLAlchemy with SQLite/PostgreSQL, while the tree also includes MongoDB helpers. For an architecture diagram, treat persistence as a data layer with potentially mixed or evolving storage support rather than a single fixed database.

8. **Domain data model and flows**
   The main entities implied by the code structure are users, trucks, cargo loads, matches, and history records. The primary flow is: user registers/logs in → registers truck or posts cargo → backend evaluates matching and optimization → user views match results and match history.

9. **Operational features**
   The product supports shared loads and dynamic additions, which means the matching system is not just a one-time assignment engine. It needs to recalculate or extend matches when capacity remains available, especially for mid-route cargo additions.

10. **Bootstrap and test data**
   `backend/add_test_data.py` is a seeding script used to populate the system for demos or development. `backend/runtime.txt` and `requirements.txt` indicate a Python deployment target, while the frontend uses Vite (`vite.config.js`) and standard Node tooling.

11. **How the modules connect**
   The cleanest mental model is: **UI → API client → FastAPI routes → service layer → persistence**. The API layer should stay thin, while the services encapsulate the optimization logic. That separation is central to the repo’s architecture.

12. **Diagram emphasis**
   If you are drawing this system, emphasize three major boundaries: the React presentation layer, the FastAPI application layer, and the optimization/persistence backend. The distinctive part of this repo is that the “AI” is not an external model service; it lives inside the backend service modules as custom heuristic optimization logic.

Main entry points: [`Documents/TransL/frontend/src/App.jsx`](https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/App.jsx) (App Shell), [`Documents/TransL/frontend/src/services/api.js`](https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/services/api.js) (API Client), [`Documents/TransL/backend/app/api/cargo.py`](https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/api/cargo.py) (Domain APIs), [`Documents/TransL/backend/app/main.py`](https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/main.py) (FastAPI App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_shell["App Shell<br/>React SPA<br/>[App.jsx]"]
  node_ui_nav["Nav Guards<br/>route UI"]
  node_ui_pages_home["Landing<br/>page<br/>[Landing.jsx]"]
  node_ui_pages_auth["Auth Flow<br/>page set<br/>[Auth.jsx]"]
  node_ui_pages_dashboard["Dashboard<br/>page<br/>[Dashboard.jsx]"]
  node_ui_pages_matchs["Matches<br/>page<br/>[Matches.jsx]"]
  node_ui_pages_match_detail["Match Details<br/>page<br/>[MatchDetails.jsx]"]
  node_ui_pages_postload["Postload<br/>page<br/>[Postload.jsx]"]
  node_ui_pages_profile["Profile<br/>page<br/>[Profile.jsx]"]
  node_ui_pages_truck["Register Truck<br/>page<br/>[RegisterTruck.jsx]"]
  node_ui_api["API Client<br/>HTTP client<br/>[api.js]"]
end

subgraph group_backend["Backend"]
  node_api_main["FastAPI App<br/>app entry<br/>[main.py]"]
  node_api_auth["Auth API<br/>route<br/>[auth.py]"]
  node_api_domain["Domain APIs<br/>routes<br/>[cargo.py]"]
  node_svc_match{{"Matching Engine<br/>heuristic service<br/>[matching_engine.py]"}}
  node_svc_load{{"Load Optimizer<br/>optimization<br/>[load_optimizer.py]"}}
  node_svc_route{{"Route Optimizer<br/>optimization<br/>[route_optimizer.py]"}}
  node_core_sec["Security<br/>auth core<br/>[security.py]"]
end

subgraph group_data["Data Layer"]
  node_db_session[("DB Session<br/>SQL session<br/>[session.py]")]
  node_db_mongo[("Mongo Helper<br/>document store<br/>[mongodb.py]")]
  node_core_mongo[("Mongo Core<br/>connection core<br/>[mongo.py]")]
end

node_ui_shell -->|"wraps"| node_ui_nav
node_ui_shell -->|"routes to"| node_ui_pages_home
node_ui_shell -->|"routes to"| node_ui_pages_auth
node_ui_shell -->|"routes to"| node_ui_pages_dashboard
node_ui_shell -->|"routes to"| node_ui_pages_matchs
node_ui_shell -->|"routes to"| node_ui_pages_match_detail
node_ui_shell -->|"routes to"| node_ui_pages_postload
node_ui_shell -->|"routes to"| node_ui_pages_profile
node_ui_shell -->|"routes to"| node_ui_pages_truck
node_ui_pages_home -->|"calls"| node_ui_api
node_ui_pages_auth -->|"calls"| node_ui_api
node_ui_pages_dashboard -->|"calls"| node_ui_api
node_ui_pages_matchs -->|"calls"| node_ui_api
node_ui_pages_match_detail -->|"calls"| node_ui_api
node_ui_pages_postload -->|"calls"| node_ui_api
node_ui_pages_profile -->|"calls"| node_ui_api
node_ui_pages_truck -->|"calls"| node_ui_api
node_ui_api -->|"requests"| node_api_main
node_api_main -->|"mounts"| node_api_auth
node_api_main -->|"mounts"| node_api_domain
node_api_auth -->|"uses"| node_core_sec
node_api_domain -->|"delegates"| node_svc_match
node_api_domain -->|"delegates"| node_svc_load
node_api_domain -->|"delegates"| node_svc_route
node_svc_match -->|"consults"| node_svc_load
node_svc_match -->|"consults"| node_svc_route
node_api_auth -->|"persists"| node_db_session
node_api_domain -->|"persists"| node_db_session
node_api_domain -->|"persists"| node_db_mongo
node_db_mongo -->|"uses"| node_core_mongo

click node_ui_shell "https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/App.jsx"
click node_ui_nav "https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/components/ProtectedRoutes.jsx"
click node_ui_pages_home "https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/Landing.jsx"
click node_ui_pages_auth "https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/Auth.jsx"
click node_ui_pages_dashboard "https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/Dashboard.jsx"
click node_ui_pages_matchs "https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/Matches.jsx"
click node_ui_pages_match_detail "https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/MatchDetails.jsx"
click node_ui_pages_postload "https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/Postload.jsx"
click node_ui_pages_profile "https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/Profile.jsx"
click node_ui_pages_truck "https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/RegisterTruck.jsx"
click node_ui_api "https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/services/api.js"
click node_api_main "https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/main.py"
click node_api_auth "https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/api/auth.py"
click node_api_domain "https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/api/cargo.py"
click node_svc_match "https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/services/matching_engine.py"
click node_svc_load "https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/services/load_optimizer.py"
click node_svc_route "https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/services/route_optimizer.py"
click node_core_sec "https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/core/security.py"
click node_db_session "https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/db/session.py"
click node_db_mongo "https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/db/mongodb.py"
click node_core_mongo "https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/core/mongo.py"

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_ui_shell,node_ui_nav,node_ui_pages_home,node_ui_pages_auth,node_ui_pages_dashboard,node_ui_pages_matchs,node_ui_pages_match_detail,node_ui_pages_postload,node_ui_pages_profile,node_ui_pages_truck,node_ui_api toneBlue
class node_api_main,node_api_auth,node_api_domain,node_svc_match,node_svc_load,node_svc_route,node_core_sec toneAmber
class node_db_session,node_db_mongo,node_core_mongo toneMint
```

## Components

### Frontend

React single-page app for user flows and API calls

- [App Shell](https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/App.jsx): React SPA · Bootstraps the client app and top-level routing · `Documents/TransL/frontend/src/App.jsx`
- [Nav Guards](https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/components/ProtectedRoutes.jsx): route UI · Navigation and protected-route wrappers · `Documents/TransL/frontend/src/components/ProtectedRoutes.jsx`
- [Landing](https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/Landing.jsx): page · Public entry screen and marketing flow · `Documents/TransL/frontend/src/pages/Landing.jsx`
- [Auth Flow](https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/Auth.jsx): page set · Login and registration screens · `Documents/TransL/frontend/src/pages/Auth.jsx`
- [Dashboard](https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/Dashboard.jsx): page · User overview and primary actions · `Documents/TransL/frontend/src/pages/Dashboard.jsx`
- [Matches](https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/Matches.jsx): page · Lists available and assigned matches · `Documents/TransL/frontend/src/pages/Matches.jsx`
- [Match Details](https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/MatchDetails.jsx): page · Expanded view of a single match · `Documents/TransL/frontend/src/pages/MatchDetails.jsx`
- [Postload](https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/Postload.jsx): page · Cargo posting and load submission · `Documents/TransL/frontend/src/pages/Postload.jsx`
- [Profile](https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/Profile.jsx): page · User account and profile management · `Documents/TransL/frontend/src/pages/Profile.jsx`
- [Register Truck](https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/pages/RegisterTruck.jsx): page · Truck registration and fleet setup · `Documents/TransL/frontend/src/pages/RegisterTruck.jsx`
- [API Client](https://github.com/saqibak001/transl/blob/main/Documents/TransL/frontend/src/services/api.js): HTTP client · Single frontend boundary for backend requests · `Documents/TransL/frontend/src/services/api.js`

### Backend

FastAPI application with routes, services, and storage

- [FastAPI App](https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/main.py): app entry · Backend application bootstrap and router assembly · `Documents/TransL/backend/app/main.py`
- [Auth API](https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/api/auth.py): route · Login, registration, and protected session endpoints · `Documents/TransL/backend/app/api/auth.py`
- [Domain APIs](https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/api/cargo.py): routes · Cargo, trucks, matching, details, user matches, and history endpoints · `Documents/TransL/backend/app/api/cargo.py`
- [Matching Engine](https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/services/matching_engine.py): heuristic service · Pairs cargo with trucks and extends shared-load matches · `Documents/TransL/backend/app/services/matching_engine.py`
- [Load Optimizer](https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/services/load_optimizer.py): optimization · Improves capacity usage and packing decisions · `Documents/TransL/backend/app/services/load_optimizer.py`
- [Route Optimizer](https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/services/route_optimizer.py): optimization · Plans delivery sequence and multi-drop routing · `Documents/TransL/backend/app/services/route_optimizer.py`
- [Security](https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/core/security.py): auth core · Password hashing and token/session protection · `Documents/TransL/backend/app/core/security.py`

### Data Layer

Persistence and shared state boundaries

- [DB Session](https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/db/session.py): SQL session · Primary relational database session wiring · `Documents/TransL/backend/app/db/session.py`
- [Mongo Helper](https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/db/mongodb.py): document store · MongoDB access and supporting persistence utilities · `Documents/TransL/backend/app/db/mongodb.py`
- [Mongo Core](https://github.com/saqibak001/transl/blob/main/Documents/TransL/backend/app/core/mongo.py): connection core · Shared MongoDB connection/config helpers · `Documents/TransL/backend/app/core/mongo.py`

## Connections

- App Shell → Nav Guards: wraps · Application shell composes guarded navigation
- App Shell → Landing: routes to · Public landing screen is part of the client flow
- App Shell → Auth Flow: routes to · Authentication pages are mounted in the app
- App Shell → Dashboard: routes to · Dashboard is a main authenticated view
- App Shell → Matches: routes to · Match listing is a primary user screen
- App Shell → Match Details: routes to · Single match inspection view
- App Shell → Postload: routes to · Cargo posting flow
- App Shell → Profile: routes to · Profile management flow
- App Shell → Register Truck: routes to · Truck registration flow
- Landing → API Client: calls · Frontend fetches backend data through one client layer
- Auth Flow → API Client: calls · Login and registration requests use the shared API client
- Dashboard → API Client: calls · Dashboard loads user-specific backend state
- Matches → API Client: calls · Match lists are fetched from the backend
- Match Details → API Client: calls · Detailed match data is requested over HTTP
- Postload → API Client: calls · Cargo posting submits commands to the backend
- Profile → API Client: calls · Profile updates go through the API client
- Register Truck → API Client: calls · Truck registration submits to backend routes
- API Client → FastAPI App: requests · HTTP client targets the FastAPI application
- FastAPI App → Auth API: mounts · Application exposes auth routes
- FastAPI App → Domain APIs: mounts · Application exposes domain-specific routes
- Auth API → Security: uses · Auth routes depend on security primitives
- Domain APIs → Matching Engine: delegates · Matching endpoints invoke the pairing engine
- Domain APIs → Load Optimizer: delegates · Cargo and capacity decisions use load optimization
- Domain APIs → Route Optimizer: delegates · Match detail and planning endpoints use route optimization
- Matching Engine → Load Optimizer: consults · Matching uses capacity-aware optimization
- Matching Engine → Route Optimizer: consults · Matching can incorporate route feasibility
- Auth API → DB Session: persists · User accounts and sessions are stored in the relational layer
- Domain APIs → DB Session: persists · Core domain records are saved via the primary DB session
- Domain APIs → Mongo Helper: persists · Some domain data may use document-store support
- Mongo Helper → Mongo Core: uses · Mongo helper relies on shared connection setup
