LivestockWay — Technical Module Architecture

Complete module-level documentation across Backend API, Web Frontend, and Mobile App

Table of Contents

  1. System Overview Diagram
  2. Backend API Modules — Routes, Services, Middleware
  3. Web Frontend Modules — Pages, Components, API Clients
  4. Mobile App Modules — Screens, Navigation, Redux
  5. Database Schema
  6. Real-Time & Messaging
  7. Payment & Billing Flow

1. System Overview

Client Layer
Mobile AppReact Native 0.82 · Hermes
Redux · Google Maps SDK
Web DashboardReact 18 · Vite · Tailwind
Leaflet · Nominatim (OSM)
Marketing SiteReact · Static
▼ HTTPS / REST + WebSocket (Socket.IO) ▼
Backend Layer
Node.js / Express 5 API — TypeScript26 Route Modules · 15 Services · JWT + RBAC · OSRM Route Engine · Socket.IO · node-cron
▼
Data & External Services
PostgreSQLRelational DB
StripeConnect · Subscriptions
Escrow Payments
FirebaseAuth · FCM Push
NodemailerTransactional Email
OSRMRoute Optimization

2. Backend API Modules

Node.js / Express 5 · TypeScript · 26 route files · 15 service files · PostgreSQL

2.1 Core Routes

Route

authRoutes.ts

/api/auth/*

  • POST /register, /login, /verify-email
  • POST /forgot-password, /reset-password
  • POST /change-password, /onboarding-complete
  • GETPATCH /notification-preferences
Route

loadRoutes.ts

/api/loads/*

  • GET / (list), /:id (detail)
  • POST / (create — shipper)
  • POST /:id/assign, /start, /complete
  • PATCH /:id/status
  • DELETE /:id
Route

tripRoutes.ts

/api/trips/*

  • POST / (create), /create-from-listing
  • GET /, /:id, /:id/route-plan, /:id/location/latest
  • POST /:id/route-plan/generate (OSRM)
  • POST /:id/pre-trip-check, /epod, /expenses
  • POST /:id/location (GPS tracking)
  • PATCH /:id/status
Route

truckRoutes.ts

/api/trucks/*

  • POST / (create — hauler)
  • GET /, /:id
  • PATCH /:id (update)
  • DELETE /:id
Route

driverRoutes.ts

/api/drivers/*

  • POST / (add driver to fleet)
  • GET /, /:id
  • PATCH /:id/status
  • DELETE /:id
Route

loadboardRoutes.ts

/api/loadboard/*

  • GET / (browse — hauler/driver only)

2.2 Marketplace & Commercial Routes

Route

marketplaceRoutes.ts

/api/marketplace/*

  • Truck Board: CRUD, bookings, chat
  • Load Offers: create, accept, reject, withdraw
  • Contracts: CRUD, send, accept, reject
  • Trips: create-manual, pickup, delivery, payments
  • Disputes: CRUD, messages, admin resolution
  • Escrow: payment-intent, breakdown, payout
  • Profiles: hauler, shipper, stakeholder
Route

stripeRoutes.ts

/api/stripe/*

  • POST /connect/onboard (hauler)
  • GET /connect/status
  • POST /subscription/checkout
  • POST /escrow/contract-intent
  • POST /webhooks (raw body)
Route

paymentRoutes.ts

/api/payments/*

  • GET / (by user/role), /by-trip/:tripId
  • POST /:id/fund (shipper escrow)
Route

haulerRoutes.ts

/api/hauler/*

  • GETPATCH /profile
  • GET /subscription
  • POST /subscription/subscribe
Route

pricingRoutes.ts

/api/pricing/*

  • GET /individual-packages (public)

2.3 Marketplace Listings & Messaging

Route

jobRoutes.ts

/api/jobs/*

  • GET /, /mine, /:id
  • POST /, /:id/applications
  • PATCH /:id, /applications/:id/status
  • DELETE /:id
Route

buyAndSellRoutes.ts

/api/buy-and-sell/*

  • GET /, /my-listings, /:id
  • POST /, /:id/applications
  • PUT /:id, /applications/:id/status
  • DELETE /:id
Route

resourcesRoutes.ts

/api/resources/*

  • GET /, /my-listings, /:id
  • POST /, /:id/applications
  • PUT /:id, /applications/:id/status
  • DELETE /:id
Route

5× Messaging Routes

/api/job-messages, /buy-sell-messages, /resources-messages, /load-offer-messages, /truck-booking-messages

  • GET /threads, /threads/:id, /threads/:id/messages
  • POST /threads/:id/messages
  • Thread auto-creation by listing/offer/booking ID

2.4 Admin & Support Routes

Route

adminRoutes.ts

/api/admin/* (super-admin only)

  • GET /stats, /subscriptions, /earnings
  • GETPUT /pricing/* (hauler plans)
  • GETPATCH /users, /users/:id/status
  • GETPATCH /support-tickets/*
Route

supportRoutes.ts

/api/support/*

  • GETPOST / (tickets)
  • GETPOST /:ticketId/messages
Route

kycRoutes.ts + blogRoutes.ts

/api/kyc/*, /api/blogs/*

  • KYC: submit, review (admin), status
  • Blog: public list/detail, admin CRUD + cover upload
Route

serviceRoutes.ts + uploadRoutes.ts

/api/services/*, /api/uploads/*

  • Services: CRUD, book, accept/reject/complete/pay
  • Uploads: ePOD, KYC, images, resumes

2.5 Services Layer

Service

marketplaceService.ts

  • Core business logic: trips, contracts, bookings, truck availability, payments integration, dispute handling
Service

stripeService.ts

  • Stripe Connect onboarding, Checkout sessions, PaymentIntents, webhook event processing
Service

paymentsService.ts

  • Payment records, fund/release/refund flows, escrow lifecycle
Service

emailService.ts + notificationEmailService.ts

  • Verification emails, password reset, welcome messages, trip/offer/message notifications via Nodemailer
Service

5× Listing Services

  • jobListingsService, buyAndSellService, resourcesService, serviceListingsService — CRUD + applications
Service

5× Messaging Services

  • jobMessages, buySellMessages, resourcesMessages, loadOfferMessages, truckBookingMessages — thread/message CRUD

2.6 Middleware

Middleware

auth.ts

  • JWT Bearer token verification → req.user
Middleware

rbac.ts

  • requireRoles(["hauler", "super-admin"]) — role gate with normalization
Middleware

auditLogger.ts

  • auditRequest(action, resourceFn) — writes to audit_logs table on mutations

3. Web Frontend Modules

React 18 · Vite · TypeScript · Tailwind CSS · Radix UI · Leaflet.js + OpenStreetMap

3.1 Dashboards

Page

HaulerDashboard.tsx

  • Stats, active trips, quick actions, revenue charts
Page

ShipperDashboard.tsx

  • Load stats, PostLoadDialog integration, active shipments
Page

DriverDashboard.tsx

  • Assigned trips, role switcher, activity feed
Page

StakeholderDashboard.tsx

  • Service provider home, bookings overview
Page

SuperAdminDashboard.tsx

  • Platform-wide stats, user management, pricing

3.2 Trip Management

Page

TripsTab.tsx

  • Trip list by role with status filters
Page

TripDetail.tsx

  • Full trip lifecycle: pre-trip check, pickup/delivery, ePOD, expenses
Page

TripRoutePlan.tsx

  • OSRM route visualization, polyline decoding, Leaflet map
Page

TripTracking.tsx

  • Live GPS tracking, driver location, route overlay
Page

TripChat.tsx

  • Trip thread messaging UI

3.3 Loads & Truck Board

Page

Loadboard.tsx

  • Browse available loads with filters
Page

TruckBoard.tsx

  • Browse available trucks/capacity
Page

PostLoadDialog.tsx

  • Multi-step load creation form with AddressSearch
Page

PostTruckDialog.tsx

  • 3-step truck availability posting: vehicle, route, capacity, schedule

3.4 Fleet Management

Page

FleetManagement.tsx

  • 3-tab view: Vehicles (3-step add/edit form), Drivers (add/deactivate/remove), Maintenance scheduling

3.5 Marketplace Listings

Page

JobBoard + PostJob + MyJobsTab

  • Job listings: browse, create multi-step form, manage own listings with applications
Page

BuyAndSellBoard + PostBuyAndSell + MyBuyAndSellTab

  • Buy/sell marketplace: browse, post, manage with application handling
Page

ResourcesBoard + PostResource + MyResourcesTab

  • Resources marketplace: browse, post, manage
Page

JobMessages.tsx

  • Unified messaging across 5 thread types: job, buy-sell, resources, load-offer, truck-booking

3.6 Commercial & Contracts

Page

HaulerOffersTab / ShipperOffersTab

  • Load offer negotiation from both perspectives
Page

HaulerContractsTab / ShipperContractsTab

  • Contract management: under negotiation, awaiting, confirmed
Page

HaulerBookingsTab

  • Truck booking requests: accept/reject
Page

HaulerTruckListings.tsx

  • Combined view: truck listings + jobs + buy-sell + resources tabs

3.7 Payments & Subscriptions

Page

WalletTab.tsx

  • Earnings/payments view per role
Page

HaulerSubscription + HaulerPayment

  • Subscription plans, billing, payment checkout
Page

StripeConnectSetup.tsx

  • Stripe Connect onboarding + return/refresh URLs

3.8 Admin Pages

Page

AdminPricing.tsx

  • Configure hauler pricing tiers
Page

AdminSubscriptions.tsx

  • View/manage all subscriptions
Page

AdminBlogManagement.tsx

  • Blog CMS: create, edit, delete, cover upload

3.9 Key Shared Components

Component

AppLayout.tsx

  • Shell with role-based sidebar, header, notifications, Stripe banners, "Post a" dropdowns
Component

AppRouter.tsx

  • All routing: ProtectedRoute, AuthRoute, role-based path guards
Component

AuthWrapper.tsx

  • Full auth flow: sign-in, sign-up, OTP, pricing, payment, profile setup
Component

RouteMap.tsx

  • Leaflet.js + OSM tiles: polyline route, custom markers, driver tracking
Component

AddressSearch.tsx

  • Nominatim geocoding autocomplete with debounce
Component

48× UI Primitives (shadcn/Radix)

  • button, dialog, tabs, select, calendar, input, switch, table, badge, card, sheet, drawer, tooltip…

3.10 Frontend API Clients

FileBackend Area
lib/api.tsLoads, trips, payments, support, uploads, route plans
api/marketplace.tsBookings, contracts, offers, Stripe, subscriptions, profiles
api/fleet.tsTrucks CRUD, drivers CRUD
api/jobs.tsJob listings CRUD + applications
api/buyAndSell.tsBuy/sell listings
api/resources.tsResources listings
api/services.tsService listings + bookings
api/disputes.tsDispute management
api/kyc.tsKYC verification
api/payments.tsPayment queries
api/admin.tsAdmin dashboard stats
5× *Messages.tsThread/message APIs for each listing type

4. Mobile App Modules

React Native 0.82 · Hermes · Redux Toolkit · React Navigation · Google Maps SDK

4.1 Navigation Architecture

RootNavigatorSplash → Auth screens → MainTabs
▼ Role Switch (RoleBasedTabs) ▼
Hauler → MainTabsHome (HaulerStack) · LoadTables
Messages · Trips
Shipper → ShipperStackDashboard · MyLoads · Offers
Contracts · Trips · Payments
Driver → DriverTabsHome (Dashboard) · Trips

4.2 Auth Screens

Screen

Loginscreen.tsx

  • Email/password + Google Sign-In (Firebase)
Screen

Signupscreen.tsx

  • Registration with role + plan selection
Screen

ProfileSetupScreen.tsx

  • Multi-step onboarding: company, contact, preferences
Screen

VerifyEmailScreen.tsx

  • Email OTP verification

4.3 Hauler Screens (14 screens)

Screen

HaulerDashboardScreen

  • Stats cards, active trips, quick actions, activity feed
Screen

HaulerContractsScreen

  • Under negotiation, awaiting, confirmed contracts
Screen

HaulerOffersScreen

  • Load offers with accept/reject actions
Screen

HaulerFleetScreen + AddVehicleScreen

  • Fleet list with edit/delete + 3-step vehicle add/edit form
Screen

HaulerMyListingsScreen

  • Tabbed: Jobs, Buy/Sell, Resources, Trucks
Screen

PostJobScreen / PostBuySellScreen / PostResourceScreen

  • Multi-step forms for each listing type
Screen

PostTruckRouteScreen

  • 3-step: Vehicle & Route → Capacity & Schedule → Options
Screen

HaulerEarningsScreen + StripeConnectScreen

  • Revenue tracking + Stripe Connect WebView onboarding

4.4 Shipper Screens (9 screens)

Screen

ShipperDashboardScreen

  • Load stats, active shipments, quick actions
Screen

ShipperMyLoadsScreen + PostLoadScreen

  • My loads list + multi-step load creation
Screen

ShipperOffersHubScreen + ShipperLoadOffersScreen

  • Offers received on loads, per-load offer management
Screen

ShipperContractsScreen

  • Contract management from shipper perspective
Screen

ShipperTripsScreen + ShipperTripDetailScreen

  • Trip list and detail views
Screen

ShipperPaymentsScreen

  • Payment history and pending actions

4.5 Shared Screens

Screen

MessagesScreen

  • All 5 thread types: job, buy-sell, resources, load-offer, truck-booking
Screen

TripsScreen + TripDetailScreen

  • Trip list (1662 lines) with full lifecycle management, GPS, ePOD
Screen

AllLoadsScreen + AllTrucksScreen

  • Browse loadboard and truck board
Screen

LoadRequestsScreen + TruckRequestsScreen

  • Incoming load/truck requests management
Screen

ChatScreen

  • Individual chat thread view

4.6 Mobile API Clients (16 files)

FileCoverage
client.tsAxios instance with auth interceptor + base URL
loads.tsLoad CRUD + assignment
loadboard.tsBrowse loadboard
trucks.tsFleet CRUD (create, update, delete, list)
drivers.tsDriver management
marketplace.tsOffers, contracts, truck board, hauler vehicles
jobs.tsJob listings + applications
buySell.tsBuy/sell listings
resources.tsResources listings
stripe.tsStripe Connect + subscriptions
payments.tsPayment queries
5× *Messages.tsThread/message APIs per listing type

4.7 Redux Store

Redux

authSlice.ts

  • User authentication state, token, user profile, login/logout/register
Redux

tripSlice.ts

  • Trip list, detail, GPS tracking, status updates, pre-trip checks
Redux

loadSlice.ts

  • Load browsing, filtering, assignment

5. Database Schema (PostgreSQL)

Core tables from DDL files — enums define role and status constraints

TablePurpose
app_usersAll users: hauler, shipper, driver, stakeholder, super-admin
loadsLivestock loads: species, quantity, pickup/dropoff, pricing, status
tripsTrip lifecycle: planned → en_route → completed, GPS, route plans
trip_route_plansOSRM-generated route data, polyline, tolls, compliance
trip_location_logsGPS breadcrumbs per trip for live tracking
trucksFleet vehicles: type, dimensions, capacity, hazmat, species
driversHauler team drivers with license tracking
load_offersBidding: hauler offers on shipper loads
contractsHauler-shipper contracts with terms and status
truck_board_entriesTruck availability listings for the truck board
truck_bookingsShipper booking requests on truck listings
paymentsEscrow/direct payments with Stripe references
disputes / dispute_messagesPayment dispute management with messaging
job_listings / job_applicationsJob marketplace
buy_sell_listings / buy_sell_applicationsBuy/sell marketplace
resources_listings / resources_applicationsResources marketplace
*_message_threads / *_messages5 messaging systems (job, buy-sell, resources, load-offer, truck-booking)
service_listings / service_bookingsStakeholder services marketplace
support_tickets / support_ticket_messagesCustomer support system
kyc_requestsKnow-Your-Customer verification
subscriptionsHauler subscription plans (Stripe)
audit_logsImmutable audit trail for all mutations
pre_trip_checks / epod_recordsPre-trip inspections and electronic proof of delivery
trip_expensesDriver/trip expense tracking with receipts

6. Real-Time & Messaging Architecture

Socket.IO Events
Trip Updatesstatus changes, GPS location
pickup/delivery events
Chat Messages5 thread types: job, buy-sell
resources, load-offer, truck-booking
NotificationsNew offers, booking requests
contract updates, payments
▼
socket.ts (Backend)Room-based: user:{id}, trip:{id}, thread:{id} — authenticated via JWT handshake

7. Payment & Billing Flow

Stripe Integration
1. Hauler OnboardingStripe Connect → /connect/onboard
Bank account, identity verification
→
2. SubscriptionStripe Checkout → tiered plans
Free / Individual / Company
→
3. Load PaymentEscrow: shipper funds →
platform holds → hauler payout
→
4. DisputeShipper/hauler dispute →
admin resolution → refund/release

LivestockWay Technical Architecture Documentation · Generated March 2026