mirror of
http://forgejo-oa09toasww4dgii9cj3gpzda.187.127.164.61.sslip.io/iamcoolvivek007/bharath.git
synced 2026-06-11 00:06:51 +00:00
Vivek
394117dd74
- Govt-app styled freight marketplace - Role-based auth (driver/shipper/broker/admin) - Load board with bidding system - Trip tracking with status flow - In-app messaging - Admin panel - Mobile bottom nav + PWA - Docker + Coolify ready
279 lines
13 KiB
Markdown
279 lines
13 KiB
Markdown
# 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.*
|