How saqibak001/transl works
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: App.jsx App Shell · api.js API Client · cargo.py Domain APIs · main.py FastAPI App
Components 21
Frontend
React single-page app for user flows and API calls
- App Shell · Bootstraps the client app and top-level routing
Documents/TransL/frontend/src/App.jsx - Nav Guards · Navigation and protected-route wrappers
Documents/TransL/frontend/src/components/ProtectedRoutes.jsx - Landing · Public entry screen and marketing flow
Documents/TransL/frontend/src/pages/Landing.jsx - Auth Flow · Login and registration screens
Documents/TransL/frontend/src/pages/Auth.jsx - Dashboard · User overview and primary actions
Documents/TransL/frontend/src/pages/Dashboard.jsx - Matches · Lists available and assigned matches
Documents/TransL/frontend/src/pages/Matches.jsx - Match Details · Expanded view of a single match
Documents/TransL/frontend/src/pages/MatchDetails.jsx - Postload · Cargo posting and load submission
Documents/TransL/frontend/src/pages/Postload.jsx - Profile · User account and profile management
Documents/TransL/frontend/src/pages/Profile.jsx - Register Truck · Truck registration and fleet setup
Documents/TransL/frontend/src/pages/RegisterTruck.jsx - API Client · Single frontend boundary for backend requests
Documents/TransL/frontend/src/services/api.js
Backend
FastAPI application with routes, services, and storage
- FastAPI App · Backend application bootstrap and router assembly
Documents/TransL/backend/app/main.py - Auth API · Login, registration, and protected session endpoints
Documents/TransL/backend/app/api/auth.py - Domain APIs · Cargo, trucks, matching, details, user matches, and history endpoints
Documents/TransL/backend/app/api/cargo.py - Matching Engine · Pairs cargo with trucks and extends shared-load matches
Documents/TransL/backend/app/services/matching_engine.py - Load Optimizer · Improves capacity usage and packing decisions
Documents/TransL/backend/app/services/load_optimizer.py - Route Optimizer · Plans delivery sequence and multi-drop routing
Documents/TransL/backend/app/services/route_optimizer.py - Security · Password hashing and token/session protection
Documents/TransL/backend/app/core/security.py
Data Layer
Persistence and shared state boundaries
- DB Session · Primary relational database session wiring
Documents/TransL/backend/app/db/session.py - Mongo Helper · MongoDB access and supporting persistence utilities
Documents/TransL/backend/app/db/mongodb.py - Mongo Core · Shared MongoDB connection/config helpers
Documents/TransL/backend/app/core/mongo.py
Connections 30
- 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