TruxFlow - Architecture

API Controllers

Frontend Pages

20+

Data Models

DB Migrations

High-Level Architecture

🌐

Cloudflare

DNS + CDN

→

🔒

Nginx

SSL + Proxy

→

⚛️
React App
Static Files

↔

🚀
Express API
Port 4000

→

🗄️

PostgreSQL

Port 5432

↔

☁️

Linode S3

File Storage

Request Flow

staging.truxflow.app

HTTPS :443

↓

/api/*

→ Backend :4000

/webhook

→ Webhook :9000

→ Static Files

Backend Structure

Tech Stack

🚀

Express.js v5

API Framework

💎

Prisma v6.17

ORM

🐘

PostgreSQL 16

Database

🔄

PM2

Process Manager

Directory Structure

backend/ ├── prisma/ │ ├── schema.prisma # Data models │ ├── seed.js │ └── migrations/ # 44 migrations ├── controllers/ # 15 controllers ├── routes/ # API endpoints ├── middleware/ │ ├── auth.js # JWT │ ├── requirePermission.js # RBAC │ └── carrierScope.js # Multi-tenant └── utils/ ├── s3.js, prismaFilters.js, logActivity.js

API Controllers

Controller	Base Route	Purpose
authController	/api/auth/*	Login, signup, token refresh
carrierController	/api/carriers/*	Carrier CRUD, profiles
driverController	/api/drivers/*	Driver management, assignments
trucksController	/api/trucks/*	Truck/unit management
trailersController	/api/trailers/*	Trailer management
devicesController	/api/devices/*	ELD/GPS device tracking
documentsController	/api/documents/*	File uploads, document management
dashboardController	/api/dashboard/*	Stats, aggregations, reports
userController	/api/users/*	User management
rolesController	/api/roles/*	RBAC roles & permissions
brokerController	/api/brokers/*	Freight broker management
factoringController	/api/factoring/*	Factoring company management
contractorsController	/api/contractors/*	Service provider management
fuelCardController	/api/fuel-cards/*	Fuel card management

Data Models (Prisma)

Core Entities

🏢

Organization

Multi-tenant root

👤

User

System users

🎭

Role

RBAC roles

🔑

Permission

Granular access

Safety Module Entities

🚛

Carrier

DOT#, MC#, insurance

🧑‍✈️

Driver

CDL, TWIC, endorsements

🚚

Truck

Units, specs, status

📦

Trailer

Type, size, assignments

📱

Device

ELD, GPS, Tablet

🔧

Contractor

Service providers

🔐

Credentials

⛽

FuelCard

Fuel management

Assignment Models (Relationships)

🔗

TruckAssignment

Driver ↔ Truck

🔗

TrailerAssignment

Trailer ↔ Truck

🔗

DeviceAssignment

Device ↔ Truck

🔗

FuelCardAssignment

FuelCard ↔ Truck

Key Enums

Enum	Values
DepartmentType	ACCOUNTING, DISPATCH, SAFETY, OPERATIONS, RECRUITING
DriverStatus	ONBOARDING, ACTIVE, TERMINATED, ...
CarrierStatus	ACTIVE, INACTIVE, ...

Enum	Values
unitsSafetyStatus	PENDING, APPROVED, ...
unitsOperationStatus	NOT_OPERATING, OPERATING, ...
availabilityStatus	VACANT, ASSIGNED, ...

Frontend Structure

Tech Stack

⚛️

React

UI Framework

⚡

Vite

Build Tool

🎨

Tailwind CSS

Styling

🛣️

React Router

Navigation

Directory Structure

frontend/src/ ├── pages/ # 31 page components ├── components/ │ ├── forms/ # Entity forms │ ├── rows/ # Table rows │ └── layout/ # TopBar, Sidebar ├── hooks/ # Data fetching ├── api/ # API client ├── routes/ # AppRoutes.jsx ├── context/ # Auth context └── layout/ # Mainlayout.jsx

Frontend Modules & Routes

🛡️ Safety Active

Core module - compliance, documents, assets

Dashboard/safety/dashboard
Carriers/safety/carriers
Drivers/safety/drivers
Contractors/safety/contractors
Trucks/safety/trucks
Trailers/safety/trailers
Devices/safety/devices
Fuel Cards/safety/fuel-card
Credentials/safety/credentials

👑 Admin Partial

User management, roles, activity logs

Dashboard/admin/dashboard
Users/admin/users
Roles/admin/roles
Activity Logs/admin/logs

🚚 Dispatch Partial

Brokers, factoring, load board

Dashboard/dispatch/dashboard
Brokers/dispatch/brokers
Factoring/dispatch/factoring
Load Board/dispatch/board

💰 Accounting Planned

QuickBooks, invoicing, settlements

All routes/accounting/*

⚙️ Operations Planned

Daily operations management

All routes/operations/*

📋 Tasks Planned

Task management, calendar

All routes/tasks/*

Quick Reference

Local Paths

Backend: /root/truxflow-hosting/app/backend/ Frontend: /root/truxflow-hosting/app/frontend/ Scripts: /root/truxflow-hosting/scripts/

Deploy Commands

./scripts/deploy-all.sh ./scripts/deploy-all.sh backend ./scripts/deploy-all.sh frontend

PM2 Processes

pm2 logs truxflow-staging pm2 restart truxflow-staging pm2 restart truxflow-webhook

Database

cd backend && npx prisma studio npx prisma migrate deploy npx prisma migrate status

GitHub Repos

weLinkCargoEnterprise/TruxFlow weLinkCargoEnterprise/TruxFlow-Front

Auto-deploy on push to main branch

Current Data

Carriers: 18 | Drivers: 235 Trucks: 199 | Trailers: 74 Documents: 1,900 total