GoMyTruck — Building a Full-Stack Digital Freight Marketplace
Executive Summary
Parther Technologies engineered GoMyTruck from first principles — a production-grade, multi-sided digital freight marketplace built to disrupt the cartelized trucking industry in West Bengal, India.
The platform is not a booking tool. It is a full logistics operating system: a dual-mode booking engine (instant dispatch + private bidding), a four-wallet payment infrastructure with automated bank payouts, three dedicated Flutter mobile applications, a React-based admin control center, real-time WebSocket gateways for tracking and live bidding, and deep integration with Indian government verification systems (ULIP SARATHI, VAHAN, DigiLocker).
Every claim in this document is backed by verified source code, database schema, API contracts, and architecture documentation.
Client / Product Overview
| Attribute | Detail | |:---|:---| | Product | GoMyTruck | | Builder | Parther Technologies | | Domain | Intra-city and inter-city commercial freight logistics | | Geography | West Bengal, India — Kolkata metro, Haldia port corridors | | User Types | Customers (shippers), Drivers (independent), Fleet Owners, Gig Workers, Platform Admins | | Architecture Pattern | Modular Monolith | | Backend | Node.js + TypeScript + Express v5 | | Database | PostgreSQL via Prisma ORM | | Mobile | Flutter (Customer app, Driver app, Workforce app) | | Admin Panel | React + Vite + TanStack Router |
Industry Background & Market Dynamics
Commercial freight logistics in India suffers from a structural inefficiency problem rooted in intermediary dependency. Brokers and local truck unions sit between shippers and carriers, extracting fees with no service accountability.
In West Bengal specifically, truck unions operating in Kolkata and the Haldia port networks have historically enforced prices that run 40-50% above open market rates through cartelization. Shippers pay inflated fees; drivers spend hours idle at truck stands waiting for loads; and the entire transaction happens over phone calls with no tracking, no documentation, and no recourse.
The broader Indian digital freight sector has begun to address this. Porter, Lalamove, and BlackBuck have demonstrated viable models:
- Porter uses a structured base fare + per-km model with 10-15% commission, enabling Tata Ace drivers to complete 3-5 trips daily vs. 1-2 from traditional stands.
- BlackBuck combines 10-20% commission with recurring telematics subscription revenue.
- The Full Truck Alliance (FTA) reduced empty hauling rates from 38.97% to 34.88% using AI matching, saving an estimated 149 million tonnes of CO2 equivalent.
GoMyTruck was designed to operate in this space with a differentiated approach: enter below cartel prices, protect driver earnings through a Minimum Payout Protection (MPP) floor, and build out a two-sided marketplace that allows competitive price discovery.
Business Challenges
1. Opaque, Phone-Based Booking
Traditional logistics operated via phone calls to brokers, with no transparency on pricing, availability, or delivery status. Customers had no way to compare rates or track their shipment.
2. Pricing Cartelization
Truck unions in Kolkata enforced above-market pricing. Any digital platform needed to undercut cartel rates while still ensuring driver profitability -- a pricing problem requiring precise unit-economic modeling.
3. Commission and Payment Reconciliation
Cash trips are the dominant payment mode in Indian logistics. When a customer pays the driver in cash, the platform must still collect its commission. Managing this "float" -- tracking negative driver wallet balances -- without blocking operations required a new financial model.
4. Driver and Vehicle Verification at Scale
Getting unverified drivers on the road creates platform and legal liability. India's SARATHI (Driving License) and VAHAN (Vehicle Registration) government databases exist but have no consumer-facing SDK. The platform needed a custom ULIP integration to verify documents automatically.
5. Multi-Sided Ecosystem Complexity
The platform had to serve five distinct user types -- customers, independent drivers, fleet owners, gig workers, and admins -- all with different workflows, permissions, and financial relationships.
6. Real-Time Operational Visibility
Logistics operations require live GPS tracking, live ETA updates, and live bidding simultaneously. Building three separate WebSocket gateways that could operate under production load required deliberate architecture.
Product Goals
- Transparent Pricing -- Build a configurable, auditable fare engine that eliminates broker opacity.
- Dual Booking Modes -- Support instant auto-dispatch for standard trips and private bidding for negotiated freight.
- Automated Financial Operations -- Automate driver/worker earnings, commission collection, and bank payouts via Razorpay + RazorpayX.
- Verified Onboarding -- Integrate government APIs for DL, RC, Aadhaar, and PAN verification.
- Live Operational Intelligence -- Real-time GPS, live ETA updates, and a multi-truck dispatch view for admins.
- B2B Enterprise Layer -- Lay the architectural groundwork for an Organization domain supporting companies with branches, departments, and teams.
- Workforce Ecosystem -- Build a parallel marketplace for on-demand loading/unloading labor.
Solution Strategy
Modular Monolith Architecture
Parther Technologies chose a modular monolith pattern deliberately. The codebase is organized into 31 independent domain modules under server/src/modules/, each containing its own router, controller, service, repository, and DTOs. The modules communicate via an internal event bus rather than direct coupling.
This approach avoided the operational complexity of microservices while still maintaining clean separation of concerns and enabling future extraction if specific modules need independent scaling.
Three-App Mobile Strategy
Rather than one universal app with role switching, the team built three dedicated Flutter applications:
- Customer App -- Booking, tracking, wallet, rewards
- Driver + Fleet App -- Trip execution, GPS, driver wallet, fleet management
- Workforce App -- Gig job management, training, gamification
This separation keeps each app's complexity bounded, allows independent release cycles, and ensures the driver's interface stays operationally simple.
Product Architecture
Backend Structure
server/src/
├── app.ts — Express app factory, middleware, rate limiters, route registration
├── server.ts — Bootstrap: DB, Redis, Socket.io gateways, BullMQ workers, event bus
├── workers.ts — BullMQ worker definitions
├── config/ — Environment, Redis, Sentry configuration
├── modules/ — 31 domain modules
└── shared/
├── db/ — Prisma client singleton
├── errors/ — Global error handler
├── eventbus/ — Internal event system (listeners.ts)
├── jobs/ — cleanup.job.ts, engagement.job.ts
├── logger/ — Winston logger
└── socket/ — socket.instance.ts singleton
The 31 Backend Modules
| Module | Purpose |
|:---|:---|
| auth | OTP generation/verification, JWT issuance, refresh tokens, admin password reset |
| user | Profile management, saved addresses, GST details, team members |
| booking | Booking lifecycle, dispatch, POD, rating |
| pricing | Fare estimation, vehicle pricing config, pricing audit log |
| marketplace | Private bid engine, bid windows, bid revisions, bid awards |
| tracking | Driver GPS ingestion, location history, ETA calculation |
| fleet | Fleet truck management, truck assignments, compliance docs |
| fleet-owner | Fleet owner onboarding, earnings, analytics |
| driver-wallet | Driver wallet ledger, commission tracking, negative balance management |
| fleet-wallet | Fleet wallet ledger, fleet earnings, driver salary transfers |
| wallet | Customer wallet, top-up, booking payment, cashback |
| payment | Razorpay order creation, payment verification, webhook handling |
| webhooks | RazorpayX payout webhook handler |
| subscription | Driver subscription plans (BASIC/STANDARD/PRO/PREMIUM) |
| notifications | FCM push dispatch, announcement routing |
| workforce | Worker job assignment, workforce gateway, job completion OTP |
| gig | Standalone gig job creation, assignment, pricing |
| organization | Enterprise B2B org management (feature-flagged) |
| ulip | ULIP SARATHI (DL) and VAHAN (RC) verification |
| upload | AWS S3 presigned URL generation, multi-file upload |
| maps | Google Maps autocomplete, place details, reverse geocode, recent searches |
| admin | Admin auth, admin-only data operations |
| announcement | Platform-wide announcements (customer/driver/worker targeted) |
| support | Support ticketing, message threads |
| dispatch | Manual dispatch operations |
| rewards | Coin balance, scratch cards, coin transactions |
| gamification | Worker badges, tiers, progress tracking |
| training | Training courses, worker progress |
| leads | Sales lead management |
| contact | Web contact message management |
| form-driver-leads | Driver acquisition lead forms with document uploads |
WebSocket Gateways (Socket.io v4.8)
Three independent gateways run on the same Socket.io server instance:
| Gateway | File | Purpose |
|:---|:---|:---|
| Tracking | tracking.gateway.ts | Live driver GPS broadcast to customer tracking screens |
| Workforce | workforce.gateway.ts | Real-time job dispatch events to worker apps |
| Marketplace | marketplace.gateway.ts | Live bid updates, revision notifications, award confirmations |
Background Job System
- BullMQ Workers (
startAllWorkers()) -- Queue-backed jobs with retry semantics - node-cron Jobs (
startCleanupJobs()) -- Periodic housekeeping: location history TTL, expired token pruning - Engagement Jobs (
startEngagementJobs()) -- Scheduled push notifications - Marketplace Jobs (
startMarketplaceJobs()) -- Bid window expiry, auto-close, status transitions
Database Design
The schema spans 2,382 lines and 60+ models across the entire platform.
Full-Text Search with GIN Indexes
The users table has composite GIN trigram indexes on name, phone, and email via PostgreSQL's pg_trgm extension, enabling fast partial-match search across the admin panel without full table scans.
Polymorphic Wallet Design
Four separate wallet models with independent ledgers, each with a *Transaction model storing balanceAfter snapshots:
Wallet-- Customer walletDriverWallet-- Can go negative (cash commission float model)FleetWallet-- Fleet business earningsWorkerWallet-- Gig worker earnings
Immutable Audit Tables
Three tables are designated permanent (never deleted):
VerificationLog-- Raw government API responses (legal compliance)ProcessedWebhook-- Idempotency guard for Razorpay webhooksPricingAuditLog-- Every fare calculation (5-year retention requirement in schema)
Booking Model Depth
The Booking model contains 60+ fields covering multi-stop delivery, full goods declaration (type, weight, dimensions, declared value, restricted goods flag), dynamic fare components (base, distance, time/congestion, fuel surcharge, loading, surge multiplier, toll, waiting), GST tracking, live ETA fields, full GPS location history, pickup OTP, completion OTP, insurance, and workforce/labor fields.
Vehicle Taxonomy
19 vehicle types encoded as a PostgreSQL enum: BIKE, THREE_WHEELER, TATA_ACE, MINI_TRUCK, TRUCK_14FT, TRUCK_17FT, TRUCK_20FT, CONTAINER_32FT, MAHINDRA_JEETO, ASHOK_LEYLAND_DOST, BOLERO_PICKUP, TATA_INTRA, MINI_OPEN_PICKUP, MINI_CLOSED_VAN, LCV_BOX_TRUCK, TRUCK_14FT_OPEN, TRUCK_14FT_CLOSED, TRUCK_17FT_CLOSED, TRUCK_19FT.
Key Features
Dual-Mode Booking Engine
INSTANT Mode: Customer selects vehicle, enters locations, sees real-time fare estimate, confirms. Backend auto-dispatches to the nearest available, verified driver.
PRIVATE_BID Mode: Booking enters a BidWindow with configurable open/close time. Drivers and fleet owners submit competing MarketplaceBid entries with quoted prices, pickup commitments, transit time estimates, vehicle type, and inclusions/exclusions. Customer awards to preferred provider.
Marketplace Bidding Engine
The bidding system uses an immutable linked-list revision model. Each MarketplaceBid has a chain of BidRevision records, each storing a complete pricing snapshot. Revisions are append-only. BidMessage supports real-time negotiation messaging. BidAward captures the confirmed bid with a payment deadline. Both independent drivers and fleet owners participate.
Real-Time GPS Tracking
The tracking gateway stores BookingLocationHistory records including speedKmh, headingDeg, accuracyM, and tripPhase. Live ETA is recalculated every 60 seconds by a background worker, updating etaMinutes on the booking record.
Four-Wallet Payment Infrastructure
Customer Wallet: Top-up via Razorpay, booking payment deduction, cashback.
Driver Wallet (Float Model):
- Online trips: Net earnings credited immediately
- Cash trips: Commission debited (wallet may go negative)
- Debt management: notification at >500, admin escalation + BREAK status at >2000 + 24hrs
- Debt cleared via: online payment, office cash (admin records), or next online trip offset
Fleet Wallet: Trip earnings credited, atomic digital driver salary transfers.
Worker Wallet: Gig job earnings, RazorpayX payouts.
Automated Bank Payouts (RazorpayX)
Full RazorpayX payout flow: Contact creation (cached) -> Penny Drop bank validation -> Payout (IMPS under 2L, RTGS over 2L) -> Webhook confirmation -> UTR capture. Admin manual fallback if auto fails. Schedule: Instant (IMPS, 5 fee), Daily (NEFT, free), Weekly (free).
Dynamic Pricing Engine
Per-vehicle pricing via VehicleTypePricing model with: baseFare, baseIncludesKm (3km default), pricePerKm, minFare, timeFreeMinutes (30 default), timeChargePerMin (1.50), waitingFreeMinutes (30), waitingChargePerBlock (100), loadingChargePerHelper (400, max 2), tcoPerKm (West Bengal 2026 actuals), surgeHardCap (1.5x). All config admin-managed, never hardcoded. Every calculation logged in PricingAuditLog (immutable, 5yr retention). MPP floor subsidies tracked in DriverPayoutSubsidy.
Fleet Ecosystem
Fleet trucks (FleetTruck) are separate from personal driver vehicles (Vehicle). Fleet trucks have real-time GPS, compliance docs with expiry dates, maintenance history, and fuel logs. Dispatch chain: Booking -> FleetOwner -> FleetTruck -> FleetDriver -> TruckAssignment.
Workforce Management
Workers have configurable profiles: max weight capacity, preferred labor types (LOADING/UNLOADING/BOTH), vehicle access, availability hours, preferred distance, languages, acceptance rate.
Gamification: Badge-based progression (TOTAL_JOBS, RATING, ACCEPTANCE_RATE, ON_TIME_RATE, TOTAL_EARNINGS metrics) across BRONZE/SILVER/GOLD/PLATINUM/DIAMOND tiers.
Training: Courses with BEGINNER/INTERMEDIATE/ADVANCED levels, module-by-module progress tracking, certificate generation.
Government Compliance Integration
ULIP SARATHI (DL): Driver submits DL + DOB. Government returns match with permit types. Raw JSON response stored immutably in VerificationLog.
ULIP VAHAN (RC): RC number + chassis/engine cross-check against government database.
DigiLocker KYC: Full PKCE OAuth 2.0 flow for Aadhaar and PAN. Only last 4 digits of Aadhaar stored. All ephemeral session fields cleared post-verification.
Enterprise Organization Domain
Feature-flagged (ORGANIZATION_DOMAIN_ENABLED, default: false). Full organizational hierarchy: Organization -> Branch -> Department -> Team -> Member. Roles: PRIMARY_OWNER, ORG_ADMIN, HR, SUPERVISOR, EMPLOYEE, VIEWER. Employment types: GIG_INDEPENDENT, FLEET_MANAGED_CONTRACTOR, THIRD_PARTY_AGENCY, FULL_TIME_EMPLOYEE, PART_TIME_EMPLOYEE. Full employment assignment history with transition tracking.
Security Architecture
Authentication
- Mobile: Phone/OTP authentication. OTPs in Redis with TTL expiry.
- Admin: Email/password with Argon2id hashing. Password reset via single-use UUID (1-hour window, Zoho email).
- JWT: Access + refresh token pair.
RefreshTokenmodel with server-side invalidation. - Mobile storage:
flutter_secure_storage(hardware-backed Android, Keychain iOS).
API Rate Limiting
| Endpoint | Limit | Window | Purpose |
|:---|:---|:---|:---|
| Global (/api) | 100 req | 15 min | General abuse prevention |
| Auth/OTP | 10 req | 15 min | OTP brute-force prevention |
| Admin Auth | 5 req | 15 min | Admin brute-force prevention |
| POD OTP (/pod) | 5 req | 5 min | Delivery OTP brute-force guard |
Financial Security
| Risk | Mitigation |
|:---|:---|
| Double wallet credit | referenceId unique index on transaction table |
| Webhook double-processing | ProcessedWebhook table (immutable, never deleted) |
| Client amount tampering | Server fetches amounts from Razorpay directly |
| Duplicate RazorpayX payout | X-Payout-Idempotency header |
| Race condition on debit | SELECT FOR UPDATE database transaction |
| Wrong bank account | Penny Drop (FAV) verification before first payout |
| Mid-withdrawal bank change | Bank details snapshotted in WithdrawalRequest at creation |
Mobile Applications
Customer App
Flutter SDK ^3.11.1, v1.0.1+3. State: flutter_riverpod v3. Navigation: go_router v17. Maps: Mapbox Maps Flutter v2.24. HTTP: Dio v5. Payments: razorpay_flutter. Push: firebase_messaging v16 + flutter_local_notifications v21. Storage: flutter_secure_storage v10.
Feature areas: auth, home, booking, tracking, payment, enterprise, gig, profile.
Notable: scratcher package for physical scratch-card reward reveal; showcaseview for feature onboarding; video_player for onboarding videos.
Driver + Fleet App
Flutter with internationalization (l10n.yaml). Dual-role navigation: Driver mode (trips, wallet, GPS) vs Fleet Owner mode (fleet dashboard, truck management, earnings).
Workforce App
Flutter. Features: gig job feed, accept/decline/arrive/complete with OTP, training modules, gamification dashboard, wallet and withdrawals.
Admin Panel
Vite + React + TypeScript + TanStack Router. 39 route files.
| Area | Key Routes | Size |
|:---|:---|:---|
| Dashboard | index.tsx | 16KB |
| Booking Detail | bookings.$id.tsx | 17KB |
| Workforce | workforce.tsx | 21KB (largest) |
| Gamification | platform.gamification.tsx | 13.5KB |
| Verification | verification.tsx | 11.7KB |
| Live Map | live-map.tsx | 10KB |
| Training | platform.training.tsx | 10.5KB |
Finance modules: earnings, revenue, wallets, subscriptions, refunds, withdrawals. Compliance modules: document review, expiry alerts, ULIP status. Platform modules: pricing config, notifications, announcements, leads, training, gamification.
Technical Stack
| Layer | Technology | Version | |:---|:---|:---| | Backend Runtime | Node.js + TypeScript | TypeScript 6.x | | HTTP Framework | Express | v5.2.1 | | ORM | Prisma | v5.22 | | Database | PostgreSQL | -- | | Cache | Upstash Redis (IORedis) | v5.10 | | Job Queue | BullMQ | v5.76 | | Realtime | Socket.io | v4.8 | | Validation | Zod | v4.4 | | Auth | jsonwebtoken + argon2 | JWT v9, argon2 v0.44 | | Payments (Inbound) | Razorpay | v2.9 | | Payments (Outbound) | RazorpayX Payouts API | -- | | Storage | AWS S3 (SDK v3) | -- | | Push Notifications | Firebase Admin (FCM) | v13.9 | | Maps (Backend) | Google Maps Services | v3.4 | | PDF Generation | pdfmake | v0.3 | | Error Monitoring | Sentry (node + profiling) | v10.56 | | Logging | Winston + Morgan | -- | | Security | Helmet.js | v8.1 | | Rate Limiting | express-rate-limit | v8.5 | | Scheduled Jobs | node-cron | v4.6 | | Email | Nodemailer | v8.0 | | Mobile Framework | Flutter | SDK ^3.11.1 | | Mobile State | flutter_riverpod | v3.3 | | Mobile Navigation | go_router | v17.2 | | Mobile Maps | Mapbox Maps Flutter | v2.24 | | Mobile HTTP | Dio | v5.9 | | Admin Framework | React + Vite + TanStack Router | -- |
Deployment Infrastructure
| Component | Provider |
|:---|:---|
| Database | DigitalOcean Managed PostgreSQL |
| Redis | Upstash (serverless, pgBouncer for migration with directUrl) |
| Object Storage | AWS S3 (docs, photos, POD, certificates) |
| CDN / Proxy | Cloudflare |
| Application Server | DigitalOcean Droplet + Nginx |
| CI/CD | GitHub Actions (server + admin repos) |
| Error Tracking | Sentry with Node profiling |
| Uptime Monitoring | UptimeRobot via /health endpoint |
Production chain: Cloudflare -> DigitalOcean -> Nginx -> Express. HTTPS enforcement reads X-Forwarded-Proto with trust proxy: 1 correctly through the multi-hop chain.
Conclusion
GoMyTruck is one of the most technically sophisticated logistics platforms built for the Indian market. The depth of the architecture -- 31 backend modules, three dedicated Flutter apps, a 2,382-line database schema, three WebSocket gateways, automated dual-mode bank payouts, government API verification, and an enterprise org management layer -- reflects the genuine complexity of production logistics operations.
Parther Technologies made deliberate, documented architectural decisions at every layer: modular monolith over microservices for startup speed; dedicated apps per user type for interface clarity; immutable audit tables for legal compliance; and a float-based driver wallet model that mirrors how cash logistics actually works.
The result is a platform ready for production deployment, with the architectural foundations in place to expand into enterprise B2B, AI-driven route optimization, and national logistics integrations.
All technical claims in this case study are verified from direct forensic analysis of the GoMyTruck project source code, database schema, API layer, architecture documentation, and project specifications. No metrics have been fabricated.
