QR Vehicle Communication Platform MVP

Statement of Work (SOW): Parking Agent MVP Development

## 1. Project Overview & Objective
Parking Agent is an app-less, privacy-first QR vehicle communication platform. The objective of this project is to build an Minimum Viable Product (MVP) consisting of a pre-generated QR inventory system, a secure mobile web interface for vehicle owners and scanners, automated OTP/notification routing, and a basic administrative management panel.

---

## 2. Technical Stack & Requirements (Recommended)
* **Backend Framework:** Node.js (Express/NestJS) OR Python (FastAPI/Django)
* **Database:** PostgreSQL (Relational database for structured QR mapping and vehicle relationships)
* **Caching/Session:** Redis (For OTP storage, rate-limiting, and short-term link verification)
* **Frontend:** React.js / Next.js or Vue.js (Mobile-first responsive design, PWA-ready)
* **Cloud Infrastructure:** AWS / Google Cloud / DigitalOcean (Docker containers, secure environment)
* **Third-Party Integrations:** Twilio / Firebase / Infobip (For SMS/WhatsApp OTP & Instant Alerts)

---

## 3. Database Architecture & Schema Design
To guarantee data privacy and extreme speed when a QR is scanned, the relational schema is designed as follows:

```
+------------------+ +------------------+ +--------------------+
| qr_inventory | | users | | vehicles |
+------------------+ +------------------+ +--------------------+
| id (PK, UUID) | | id (PK, UUID) | | id (PK, UUID) |
| qr_token (Unique)| | phone_number | | user_id (FK) |
| batch_number | | status (Active) | | plate_number |
| status (Enum) | | created_at | | vehicle_type |
| activated_at | +------------------+ | make_model |
| user_id (FK, Null)| | | color |
+------------------+ | +--------------------+
|
v
+------------------+ +------------------+
| alert_history | | otp_sessions |
+------------------+ +------------------+
| id (PK, UUID) | | id (PK, UUID) |
| qr_id (FK) | | phone_number |
| reason_category | | otp_code (Hashed)|
| scanner_ip | | expires_at |
| status (Enum) | | verified_at |
| created_at | +------------------+
+------------------+
```

### Table Definitions

#### A. `qr_inventory`
Tracks pre-printed physical QR stickers.
* `id`: UUID (Primary Key)
* `qr_token`: VARCHAR(64) - Secure unique string embedded in the URL (e.g., `parkingagent.com/v/xyz123`)
* `batch_number`: VARCHAR(32) - For printing tracking
* `status`: ENUM ('PRE_GEN', 'ACTIVE', 'SUSPENDED', 'BLOCKED')
* `user_id`: UUID (Foreign Key, nullable until sticker activation)
* `created_at` / `activated_at`: TIMESTAMP

#### B. `users`
Stores privacy-protected vehicle owner data.
* `id`: UUID (Primary Key)
* `phone_number`: VARCHAR(20) - Hashed or encrypted at rest for optimal security
* `status`: ENUM ('ACTIVE', 'BANNED')
* `created_at`: TIMESTAMP

#### C. `vehicles`
Links the vehicle assets to the user account.
* `id`: UUID (Primary Key)
* `user_id`: UUID (Foreign Key linking to `users`)
* `plate_number`: VARCHAR(20) - Vehicle registration number
* `vehicle_type`: ENUM ('CAR', 'BIKE', 'TRUCK', 'OTHER')
* `make_model`: VARCHAR(100) - Optional (e.g., "Honda Civic")
* `color`: VARCHAR(32) - Optional

#### D. `alert_history`
Logs all incoming contact attempts for security and spam control.
* `id`: UUID (Primary Key)
* `qr_id`: UUID (Foreign Key linking to `qr_inventory`)
* `reason_category`: ENUM ('BLOCKING', 'WRONG_PARKING', 'LIGHTS_ON', 'WINDOW_OPEN', 'DAMAGE', 'EMERGENCY', 'OTHER')
* `scanner_ip`: VARCHAR(45) - For anti-fraud/rate-limiting
* `status`: ENUM ('SENT', 'DELIVERED', 'RESOLVED', 'SPAM')
* `created_at`: TIMESTAMP

---

## 4. Detailed Scope of Work & Deliverables

### Phase 1: Core Engine & Inventory Management (Backend)
* **Secure Token Generation Engine:** Script to securely mass-produce `X` number of randomized alphanumeric crypto-tokens (e.g., 10,000 per batch).
* **Batch Export Utility:** CSV data exporter to output clean, raw URLs (`https://parkingagent.com/v/{token}`) matching the strict requirements of your physical printing vendor.
* **Database Layer Deployment:** Complete implementation of the schema detailed above with built-in indexing on `qr_token` to guarantee sub-100ms database lookups.

### Phase 2: Mobile-First Frontend (Owner & Scanner Flows)
* **Zero-Setup Scanner Web UI:** Clean, ultra-lightweight responsive web form that opens natively when a regular smartphone camera scans the QR code. Needs to load in