# kanishjebamathewm/truxify architecture

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

- Interactive diagram: https://gitdiagram.com/kanishjebamathewm/truxify
- Repository: https://github.com/kanishjebamathewm/truxify

## Overview

Truxify is a broker-free freight marketplace connecting manufacturers directly with drivers. Its principal workflow is load discovery and matching, booking, in-trip tracking, delivery verification, and payment; the README identifies the API as the orchestrator for apps, persistence, ML, and blockchain. The graph also preserves documented voice, document-integrity, reputation, and automation capabilities. The tree and excerpts support the major subsystem paths, but do not establish all internal call wiring, so uncertain links are omitted; the Flutter app directories are represented at their available enclosing paths.

Main entry points: [`backend/api/src/index.js`](https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/index.js) (Main API), [`backend/ml/app/main.py`](https://github.com/kanishjebamathewm/truxify/blob/main/backend/ml/app/main.py) (ML engine), [`backend/api/src/services/order`](https://github.com/kanishjebamathewm/truxify/tree/main/backend/api/src/services/order) (Order lifecycle), [`backend/api/src/sockets/locationServer.js`](https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/sockets/locationServer.js) (Live tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Marketplace clients"]
  node_customer_app["Customer app"]
  node_driver_app["Driver app"]
end

subgraph group_api["API and operations"]
  node_api_server["Main API<br/>[index.js]"]
  node_policy["Authorization<br/>[policyEngine.js]"]
end

subgraph group_freight["Freight workflow"]
  node_order_routes["Order routes<br/>[orderRoutes.js]"]
  node_order_services["Order lifecycle"]
  node_routing["Routing services<br/>[routingService.js]"]
  node_tracking["Live tracking<br/>[locationServer.js]"]
  node_delivery["Delivery proof"]
end

subgraph group_intelligence["ML and assistance"]
  node_ml_engine["ML engine<br/>[main.py]"]
  node_matching["Load matching"]
  node_profit_eta["Profit and ETA<br/>[driver_profit.py]"]
  node_voice_ai["Voice assistant<br/>[llm_service.py]"]
end

subgraph group_trust["Trust and integrations"]
  node_database[("Supabase data")]
  node_escrow["Escrow services<br/>[escrowService.js]"]
  node_blockchain{{"Polygon contracts"}}
  node_documents["Document integrity<br/>[documentService.js]"]
  node_reputation["Driver reputation<br/>[reputation.js]"]
  node_automation["Workflow automation"]
end

node_manufacturer(("Manufacturer"))
node_driver(("Truck driver"))
node_osrm{{"OSRM routing"}}

node_manufacturer -->|"places loads"| node_customer_app
node_driver -->|"finds loads"| node_driver_app
node_customer_app -->|"REST and sockets"| node_api_server
node_driver_app -->|"REST and sockets"| node_api_server
node_api_server -->|"dispatches requests"| node_order_routes
node_order_routes -->|"handles lifecycle"| node_order_services
node_order_services -->|"reads and writes"| node_database
node_api_server -->|"requests inference"| node_ml_engine
node_ml_engine -->|"runs matching"| node_matching
node_ml_engine -->|"predicts cost and ETA"| node_profit_eta
node_api_server -->|"requests routes"| node_routing
node_routing -->|"gets route estimates"| node_osrm
node_api_server -->|"serves live updates"| node_tracking
node_tracking -->|"streams location"| node_driver_app
node_tracking -->|"streams location"| node_customer_app
node_order_services -->|"verifies delivery"| node_delivery
node_api_server -->|"coordinates payment"| node_escrow
node_escrow -->|"locks and releases funds"| node_blockchain
node_api_server -->|"handles documents"| node_documents
node_documents -->|"anchors integrity"| node_blockchain
node_api_server -->|"supports reputation"| node_reputation
node_reputation -->|"records reputation"| node_blockchain
node_api_server -->|"serves voice queries"| node_voice_ai
node_api_server -->|"checks permissions"| node_policy
node_automation -.->|"triggers retraining"| node_ml_engine

click node_customer_app "https://github.com/kanishjebamathewm/truxify/tree/main/apps/customer"
click node_driver_app "https://github.com/kanishjebamathewm/truxify/tree/main/apps/driver"
click node_api_server "https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/index.js"
click node_order_routes "https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/routes/orderRoutes.js"
click node_order_services "https://github.com/kanishjebamathewm/truxify/tree/main/backend/api/src/services/order"
click node_routing "https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/services/routingService.js"
click node_tracking "https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/sockets/locationServer.js"
click node_delivery "https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/services/order/deliveryVerificationService.js"
click node_ml_engine "https://github.com/kanishjebamathewm/truxify/blob/main/backend/ml/app/main.py"
click node_matching "https://github.com/kanishjebamathewm/truxify/blob/main/backend/ml/app/models/bilateral_matcher.py"
click node_profit_eta "https://github.com/kanishjebamathewm/truxify/blob/main/backend/ml/app/models/driver_profit.py"
click node_voice_ai "https://github.com/kanishjebamathewm/truxify/blob/main/backend/llm/llm_service.py"
click node_escrow "https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/services/escrowService.js"
click node_documents "https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/services/documentService.js"
click node_reputation "https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/services/reputation.js"
click node_automation "https://github.com/kanishjebamathewm/truxify/tree/main/automation/n8n"
click node_policy "https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/security/policyEngine.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_customer_app,node_driver_app toneBlue
class node_api_server,node_policy toneAmber
class node_order_routes,node_order_services,node_routing,node_tracking,node_delivery toneMint
class node_ml_engine,node_matching,node_profit_eta,node_voice_ai toneRose
class node_database,node_escrow,node_blockchain,node_documents,node_reputation,node_automation,node_manufacturer,node_driver,node_osrm toneIndigo
```

## Components

### Marketplace clients

- [Customer app](https://github.com/kanishjebamathewm/truxify/tree/main/apps/customer): `apps/customer`
- [Driver app](https://github.com/kanishjebamathewm/truxify/tree/main/apps/driver): `apps/driver`

### API and operations

- [Main API](https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/index.js): `backend/api/src/index.js`
- [Authorization](https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/security/policyEngine.js): `backend/api/src/security/policyEngine.js`

### Freight workflow

- [Order routes](https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/routes/orderRoutes.js): `backend/api/src/routes/orderRoutes.js`
- [Order lifecycle](https://github.com/kanishjebamathewm/truxify/tree/main/backend/api/src/services/order): `backend/api/src/services/order`
- [Routing services](https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/services/routingService.js): `backend/api/src/services/routingService.js`
- [Live tracking](https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/sockets/locationServer.js): `backend/api/src/sockets/locationServer.js`
- [Delivery proof](https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/services/order/deliveryVerificationService.js): `backend/api/src/services/order/deliveryVerificationService.js`

### ML and assistance

- [ML engine](https://github.com/kanishjebamathewm/truxify/blob/main/backend/ml/app/main.py): `backend/ml/app/main.py`
- [Load matching](https://github.com/kanishjebamathewm/truxify/blob/main/backend/ml/app/models/bilateral_matcher.py): `backend/ml/app/models/bilateral_matcher.py`
- [Profit and ETA](https://github.com/kanishjebamathewm/truxify/blob/main/backend/ml/app/models/driver_profit.py): `backend/ml/app/models/driver_profit.py`
- [Voice assistant](https://github.com/kanishjebamathewm/truxify/blob/main/backend/llm/llm_service.py): `backend/llm/llm_service.py`

### Trust and integrations

- **Supabase data**
- [Escrow services](https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/services/escrowService.js): `backend/api/src/services/escrowService.js`
- **Polygon contracts**
- [Document integrity](https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/services/documentService.js): `backend/api/src/services/documentService.js`
- [Driver reputation](https://github.com/kanishjebamathewm/truxify/blob/main/backend/api/src/services/reputation.js): `backend/api/src/services/reputation.js`
- [Workflow automation](https://github.com/kanishjebamathewm/truxify/tree/main/automation/n8n): `automation/n8n`

### Other components

- **Manufacturer**
- **Truck driver**
- **OSRM routing**

## Connections

- Manufacturer → Customer app: places loads
- Truck driver → Driver app: finds loads
- Customer app → Main API: REST and sockets
- Driver app → Main API: REST and sockets
- Main API → Order routes: dispatches requests
- Order routes → Order lifecycle: handles lifecycle
- Order lifecycle → Supabase data: reads and writes
- Main API → ML engine: requests inference
- ML engine → Load matching: runs matching
- ML engine → Profit and ETA: predicts cost and ETA
- Main API → Routing services: requests routes
- Routing services → OSRM routing: gets route estimates
- Main API → Live tracking: serves live updates
- Live tracking → Driver app: streams location
- Live tracking → Customer app: streams location
- Order lifecycle → Delivery proof: verifies delivery
- Main API → Escrow services: coordinates payment
- Escrow services → Polygon contracts: locks and releases funds
- Main API → Document integrity: handles documents
- Document integrity → Polygon contracts: anchors integrity
- Main API → Driver reputation: supports reputation
- Driver reputation → Polygon contracts: records reputation
- Main API → Voice assistant: serves voice queries
- Main API → Authorization: checks permissions
- Workflow automation → ML engine: triggers retraining