bharath/docs/architecture/TECHNICAL_ARCHITECTURE.md

BharathTrucks — Technical Architecture Document

Version: 1.0
Date: 2026-05-31

---

1. Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    bharathtrucks.com                      │
│                   (Cloudflare DNS/CDN)                    │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│              Hostinger VPS (Coolify)                      │
│  ┌────────────────────────────────────────────────────┐  │
│  │              Docker Container                       │  │
│  │  ┌──────────────────────────────────────────────┐  │  │
│  │  │         Node.js + Express Server             │  │  │
│  │  │                                              │  │  │
│  │  │  ┌─────────┐  ┌──────────┐  ┌───────────┐  │  │  │
│  │  │  │ Routes  │  │  Views   │  │Middleware │  │  │  │
│  │  │  │(Express)│  │  (EJS)   │  │(Auth/Rate)│  │  │  │
│  │  │  └────┬────┘  └──────────┘  └───────────┘  │  │  │
│  │  │       │                                      │  │  │
│  │  │  ┌────▼────────────────────────────────────┐ │  │  │
│  │  │  │          Controllers                     │ │  │  │
│  │  │  └────┬────────────────────────────────────┘ │  │  │
│  │  │       │                                      │  │  │
│  │  │  ┌────▼────────────────────────────────────┐ │  │  │
│  │  │  │        Service Layer                     │ │  │  │
│  │  │  └────┬────────────────────────────────────┘ │  │  │
│  │  └───────┼──────────────────────────────────────┘  │  │
│  └──────────┼─────────────────────────────────────────┘  │
└─────────────┼────────────────────────────────────────────┘
              │
┌─────────────▼────────────────────────────────────────────┐
│                    Supabase (Cloud)                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐  │
│  │PostgreSQL│  │   Auth   │  │ Storage  │  │Realtime │  │
│  │(Database)│  │  (OTP)   │  │ (Files)  │  │  (WS)   │  │
│  └──────────┘  └──────────┘  └──────────┘  └─────────┘  │
└───────────────────────────────────────────────────────────┘

---

2. Technology Stack

Layer	Technology	Justification
Runtime	Node.js 20 LTS	Fast, async I/O, large ecosystem
Framework	Express.js 4.x	Minimal, flexible, well-documented
Views	EJS	Server-rendered (SEO, fast on 3G, no JS required)
Database	Supabase PostgreSQL	Managed, free tier, built-in auth
Auth	Supabase Auth (Phone OTP)	India-native phone-first auth
File Storage	Supabase Storage	Documents, profile photos
Realtime	Supabase Realtime	Live bid updates, notifications
CSS	Custom CSS	Full control for govt-app aesthetic
PWA	Service Worker + Manifest	Installable, offline caching
Container	Docker	Consistent deployment
Orchestration	Coolify	Self-hosted PaaS on Hostinger VPS
CDN/DNS	Cloudflare	Free SSL, caching, DDoS protection
Domain	bharathtrucks.com	Brand identity

---

3. Application Structure

bharathtrucks/
├── webapp/
│   ├── src/
│   │   ├── app.js                 # Express app setup
│   │   ├── server.js              # Server entry point
│   │   ├── routes/
│   │   │   ├── index.js           # Route aggregator
│   │   │   ├── auth.routes.js     # Login, register, OTP
│   │   │   ├── load.routes.js     # Load CRUD, search
│   │   │   ├── bid.routes.js      # Bidding operations
│   │   │   ├── driver.routes.js   # Driver dashboard
│   │   │   ├── shipper.routes.js  # Shipper dashboard
│   │   │   ├── broker.routes.js   # Broker dashboard
│   │   │   ├── admin.routes.js    # Admin panel
│   │   │   └── web.routes.js      # Marketing pages
│   │   ├── controllers/
│   │   │   ├── auth.controller.js
│   │   │   ├── load.controller.js
│   │   │   ├── bid.controller.js
│   │   │   ├── driver.controller.js
│   │   │   ├── shipper.controller.js
│   │   │   ├── broker.controller.js
│   │   │   └── admin.controller.js
│   │   ├── services/
│   │   │   ├── supabase.js        # Supabase client init
│   │   │   ├── auth.service.js    # Auth logic
│   │   │   ├── load.service.js    # Load business logic
│   │   │   ├── bid.service.js     # Bid business logic
│   │   │   └── notification.service.js
│   │   ├── middleware/
│   │   │   ├── auth.middleware.js  # Session validation
│   │   │   ├── role.middleware.js  # Role-based access
│   │   │   ├── rate.middleware.js  # Rate limiting (bids/day)
│   │   │   └── error.middleware.js
│   │   ├── views/
│   │   │   ├── layouts/
│   │   │   │   └── main.ejs       # Base layout
│   │   │   ├── pages/
│   │   │   │   ├── landing.ejs
│   │   │   │   ├── login.ejs
│   │   │   │   ├── register.ejs
│   │   │   │   ├── loadboard.ejs
│   │   │   │   ├── driver-dashboard.ejs
│   │   │   │   ├── shipper-dashboard.ejs
│   │   │   │   ├── broker-dashboard.ejs
│   │   │   │   └── admin-dashboard.ejs
│   │   │   └── partials/
│   │   │       ├── header.ejs
│   │   │       ├── footer.ejs
│   │   │       ├── nav.ejs
│   │   │       └── load-card.ejs
│   │   ├── public/
│   │   │   ├── css/
│   │   │   │   ├── main.css       # Global styles
│   │   │   │   ├── govt-theme.css  # Govt-app aesthetic
│   │   │   │   └── components.css  # Reusable components
│   │   │   ├── js/
│   │   │   │   ├── app.js         # Client-side logic
│   │   │   │   └── sw.js          # Service Worker
│   │   │   ├── images/
│   │   │   └── manifest.json      # PWA manifest
│   │   └── config/
│   │       ├── env.js             # Environment config
│   │       └── constants.js       # App constants
│   ├── package.json
│   ├── Dockerfile
│   ├── .env.example
│   └── .dockerignore
├── docker/
│   └── docker-compose.yml
├── scripts/
│   └── seed.js                    # DB seed data
├── docs/
└── README.md

---

4. Authentication Flow

User (Phone) → Enter Number → Supabase OTP → Verify Code → Session Created
                                                                    │
                                                    ┌───────────────┼───────────────┐
                                                    │               │               │
                                              New User?        Existing User    Admin?
                                                    │               │               │
                                            Role Selection    Dashboard        Admin Panel
                                                    │
                                            Profile Setup
                                                    │
                                              Dashboard

• Session: Supabase JWT stored in httpOnly cookie
• Role check: Middleware reads user role from profiles table
• Rate limiting: Free users get 5 bids/day (tracked in DB)

---

5. Data Flow — Load Lifecycle

Shipper Posts Load → Load Board (visible to all)
                          │
                    Drivers Browse
                          │
                    Driver Bids (price + ETA)
                          │
                    Shipper Reviews Bids
                          │
                    Accepts Best Bid
                          │
              ┌───────────┼───────────┐
              │                       │
        Driver Notified         Load Status: "Booked"
              │
        Trip Starts → In Transit → Delivered
              │
        Payment (UPI link) → Confirmed → Complete

---

6. Security Architecture

Layer	Measure
Transport	HTTPS via Cloudflare SSL
Auth	Supabase JWT + httpOnly cookies
Sessions	Server-side validation on every request
Input	Sanitization + validation (express-validator)
SQL	Parameterized queries via Supabase client
Rate Limiting	express-rate-limit (API) + DB-level (bids)
CORS	Restricted to bharathtrucks.com
Headers	Helmet.js security headers
File Upload	Type + size validation, Supabase Storage
Admin	Separate auth flow, IP whitelist optional

---

7. Performance Strategy

Technique	Implementation
Server-side rendering	EJS — no client-side framework overhead
Minimal JS	Progressive enhancement, no SPA
Image optimization	WebP, lazy loading, CDN-cached
Database	Indexed queries, connection pooling
Caching	Cloudflare page rules for static assets
PWA	Service Worker caches shell + recent loads
Compression	gzip via Express compression middleware
Bundle size	No framework = ~5KB JS total

Target: < 3 second full page load on 3G connection

---

8. Scalability Plan

Users	Infrastructure
0–1000	Single Hostinger VPS (4GB RAM), Supabase free tier
1000–5000	Upgrade VPS (8GB), Supabase Pro
5000–20000	Add Redis caching, CDN optimization
20000+	Horizontal scaling (multiple containers), dedicated DB

---

9. Third-Party Integrations

Service	Purpose	Phase
Supabase	DB + Auth + Storage + Realtime	Phase 1
Cloudflare	CDN + DNS + SSL	Phase 1
WhatsApp API (wa.me links)	Share loads	Phase 1
SMS Gateway (MSG91/Twilio)	Critical notifications	Phase 2
Razorpay/UPI	Payment processing	Phase 2
Google Maps API	Route visualization	Phase 2

---

10. Environment Configuration

# Server
NODE_ENV=production
PORT=3000

# Supabase
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_KEY=eyJ...

# App
APP_URL=https://bharathtrucks.com
SESSION_SECRET=xxx
RATE_LIMIT_BIDS_PER_DAY=5

# Optional (Phase 2)
SMS_API_KEY=xxx
RAZORPAY_KEY=xxx

---

This architecture prioritizes simplicity, speed, and low-cost operation while supporting growth to 20K+ users.