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 <1.5 seconds under 3G networks. * **Preset Alert Selector:** UI component allowing scanners to immediately select a reason (e.g., "Vehicle is blocking me") and submit without typing text or downloading an app. * **Owner Self-Service Portal:** Clean registration portal mapping physical stickers to phone numbers using instant SMS/WhatsApp OTP validation. ### Phase 3: Telecommunications & Privacy Layer * **Anonymized Communication Router:** Logic built inside the backend that maps the unique scanned URL to the correct owner's phone number without ever exposing that phone number to the client-side front-end code. * **OTP Gateway Integration:** Implementation of Twilio/Firebase SMS infrastructure to handle authentication. * **Real-time Alert Dissemination:** API infrastructure to parse scanner inputs and push immediate webhooks/messages to SMS or WhatsApp API aggregators. ### Phase 4: Security, Anti-Spam, & Basic Admin Panel * **Intelligent Rate Limiting (Anti-Spam):** System restrictions permitting maximum 3 alert triggers per unique user IP address within a 15-minute window to avoid vehicle owners getting targeted by notification storms. * **Admin Control Center:** Basic dashboard for platform operators to lookup QR statuses, track platform-wide alert success rates, manually block malicious IPs, and suspend reported QR codes. --- ## 5. Development Timeline & Milestone Schedule | Milestone | Deliverables | Timeline | | :--- | :--- | :--- | | **Milestone 1** | Database deployment, secure batch QR generation engine, and printer-ready CSV exporters. | **Week 1-2** | | **Milestone 2** | Mobile res