# 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 ```env # 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.*