bharath/README.md

# 🚛 BharathTrucks — India's National Freight Marketplace

> राष्ट्रीय माल परिवहन मंच — ट्रक ड्राइवर, शिपर और ब्रोकर के लिए

## Quick Start

```bash
cd webapp
npm install
cp .env.example .env    # Add your Supabase credentials
npm start               # http://localhost:3000
```

## Database Setup

1. Create a Supabase project at [supabase.com](https://supabase.com)
2. Go to SQL Editor → paste contents of `supabase-FULL-migration.sql` → Run
3. Copy your project URL and anon key to `.env`

**Default admin:** username=`admin`, password=`admin123`

## Seed Development Data

```bash
node seed.js
```

This creates sample users and loads. Passwords: `password123` (all users except admin).

## Deploy to Production (Coolify + Hostinger VPS)

1. Push code to GitHub/GitLab
2. In Coolify: New Resource → Docker → point to repo
3. Set environment variables (from `.env.example`)
4. Domain: bharathtrucks.com → point DNS to VPS IP
5. Done — auto-deploys on push to main

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Backend | Node.js + Express |
| Views | EJS (server-rendered) |
| Database | Supabase (PostgreSQL) |
| Auth | Username + Password (bcrypt) + CSRF |
| Security | Helmet, Rate Limiting, CSRF, Input Sanitization |
| Styles | Custom CSS v2 (govt-app theme, dark mode) |
| Deployment | Docker + Coolify |
| PWA | Service Worker + Manifest |

## Features

- **Load Board** — Shippers post loads, drivers browse and bid (paginated, filterable)
- **Bidding** — Drivers bid on loads, shippers accept best bid
- **Trip Tracking** — Status flow: confirmed → picked up → in transit → delivered
- **Messaging** — Direct chat between users
- **Dashboards** — Role-specific (driver/shipper/broker) with real stats
- **Admin Panel** — User management, platform metrics, load overview, stats API
- **WhatsApp Share** — Share loads via WhatsApp
- **Mobile-First** — Bottom nav, responsive, PWA installable
- **Govt-App Design** — Tricolor, navy theme, Hindi-first, trust signals
- **Dark Mode** — Toggle between light and dark themes (persisted)
- **Multi-Language** — Hindi, English, Tamil, Telugu
- **Toast Notifications** — Success/error feedback on all actions
- **CSRF Protection** — All forms protected with CSRF tokens
- **Pagination** — All list views paginated
- **Input Validation** — Server-side validation on all forms
- **Error Handling** — Proper HTTP status codes, 403/404/500 pages

## User Roles

| Role | Username | Features |
|------|----------|----------|
| Driver | Vehicle number (e.g. MH31AB1234) | Browse loads, bid, track trips, earnings |
| Shipper | Choose any username | Post loads, review bids, accept, track shipments |
| Broker | Choose any username | Post loads for clients, manage deals |
| Admin | `admin` | User management, platform metrics |

## Project Structure

```
webapp/
├── src/
│   ├── server.js           # Express app entry (security hardened)
│   ├── config/             # env.js, constants.js
│   ├── middleware/
│   │   ├── auth.js         # Auth checks with 403 handling
│   │   ├── i18n.js         # Internationalization
│   │   └── security.js     # CSRF, sanitization, logging, asyncHandler
│   ├── routes/             # All route files (async error handling)
│   ├── services/           # supabase.js
│   ├── views/pages/        # All EJS pages
│   ├── views/partials/     # header, footer, bottom-nav
│   ├── views/layouts/      # main.ejs
│   ├── lib/                # india.js, gamification.js
│   ├── i18n/               # Translation files (hi, en, ta, te)
│   └── public/             # CSS, JS, manifest, SW
├── seed.js                 # Development seed data script
├── Dockerfile              # Production Docker config (alpine, non-root)
├── package.json
├── supabase-FULL-migration.sql
└── .env.example
```

## Environment Variables

```
NODE_ENV=development
PORT=3000
APP_URL=http://localhost:3000
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-supabase-anon-key
SUPABASE_SERVICE_KEY=your-supabase-service-role-key
SESSION_SECRET=random-64-char-string
RATE_LIMIT_BIDS_PER_DAY=5
```

## Security Features

- CSRF tokens on all forms
- Session fixation protection (resave: false)
- Secure cookie settings in production
- Rate limiting (200 req/15min general)
- Input sanitization (HTML entity encoding)
- bcrypt password hashing (10 rounds)
- Security headers via Helmet
- Proper error handling (no stack traces in production)
- Graceful shutdown on SIGTERM
- Non-root Docker container

## Changelog v2.0

- Security: CSRF protection, secure sessions, input sanitization
- Code Quality: Async error handling on all routes, proper HTTP codes
- UI/UX: Dark mode, toast notifications, loading states, form validation
- Features: Pagination on all lists, 403 forbidden page, admin stats API
- Performance: Database indexes, query optimization
- DevEx: Seed script, improved Dockerfile, comprehensive .gitignore