Before You Sign

PROJECT OVERVIEW Before You Sign is an end-to-end vehicle verification, history, and consumer protection platform developed specifically for the South African pre-owned automotive market. The system prevents vehicle fraud, protects consumers from buying cloned or financed cars, and empowers automotive dealerships to display verified accreditation using digital reports and scannable QR vehicle tags.

CORE USER ROLES AND ACCESS TIERS 2.1. Public Buyers:

Perform instant searches by entering a 17-digit VIN or license plate.
Scan QR window codes directly on showroom floors using their mobile camera.
View real-time verification indicators across police records, finance status, and accident history.
Subscribe to Guardian or Advocate memberships for continuous legal and vehicle transaction protection.
2.2. Registered Dealerships:

Register an automotive business profile subject to administrator verification.
Manage vehicle inventory in draft, pending review, verified, and sold states.
Upload vehicle photos, registration papers, and roadworthy documentation.
Automatically generate printable QR code window tags for verified inventory.
2.3. System Administrators:

Review and approve or reject dealership partner applications.
Manually audit vehicle records submitted by dealers against official data points.
Approve vehicles, request changes, or reject fraudulent listings.
Oversee user accounts, membership subscriptions, and audit logs.
KEY SYSTEM CAPABILITIES 3.1. Verification and Audit Engine:
Multi-point verification covers SAPS stolen registers, bank encumbrance, accident write-off status, and mileage history.
Enforces human-verified administrative oversight before a vehicle attains verified status.
3.2. QR Code Generation and Mobile Scanner:

Automatically renders high-resolution QR codes mapped to each vehicle report.
Features an integrated in-browser camera scanner powered by HTML5 QR code technology for instant on-site lookup.
3.3. Payment and Membership Integration:

Integrated with PayFast, the primary payment gateway for South Africa.
Handles subscription memberships (Guardian at R150/month and Dealership Partner at R200/month) with secure payment redirects and notifications.
3.4. Cloud Media Management:

Utilizes Cloudinary with Multer storage for automated image optimization, transformations, and resilient delivery of vehicle photos and documents.
TECHNOLOGY STACK 4.1. Runtime and Backend: Node.js with Express.js. 4.2. Database: PostgreSQL hosted on Neon serverless database, queried via the native node-postgres (pg) pool. 4.3. View Engine: Server-rendered EJS templates with custom responsive CSS. 4.4. Security and Sessions:
PostgreSQL-backed persistent sessions via connect-pg-simple and express-session.
Double-submit CSRF token validation via csrf-csrf.
Helmet security headers with fine-grained Content Security Policy rules.
Password hashing with bcrypt.
Input validation and sanitization using express-validator. 4.5. Communications: Nodemailer for transactional email notifications. 4.6. Local Development Tools: Nodemon for hot reloading, dotenv for environment management, and RunServer.bat for one-click startup.
DIRECTORY AND ARCHITECTURE BREAKDOWN 5.1. Root Files:
app.js: Express application entry point configuring middleware, database pool, view engines, sessions, security headers, and route mounting.
RunServer.bat: One-click Windows batch script that checks Node.js prerequisites, validates the presence of .env, and launches the development server.
package.json: Application manifest specifying dependencies, migration scripts, and dev scripts.
index.html: Standalone modern landing page prototype featuring video showcase integration, VIN lookup, and responsive design.
vercel.json: Serverless deployment configuration for cloud hosting.
.env and .env.example: Environment secrets and connection strings for database, sessions, Cloudinary, and PayFast.
5.2. src/config:

db.js: Centralized PostgreSQL connection pool management and parameterized query execution helper.
multer.js: Multi-part file upload configuration supporting local storage in development and Cloudinary in production.
5.3. src/controllers:

adminController.js: Administrator dashboard handlers, dealer approvals, and vehicle review decisions.
authController.js: User registration, login, logout, and password management.
dealerController.js: Dealership inventory management, vehicle creation, editing, and submission.
membershipController.js: Tier selection, PayFast payment dispatch, and webhook processing.
publicController.js: Landing page, public search engine, and vehicle report display.
5.4. src/models:

Pure SQL data access layer utilizing raw parameterized queries for dealerships, vehicles, users, audit logs, and memberships without bulky ORM overhead.
5.5. src/routes:

adminRoutes.js, authRoutes.js, dealerRoutes.js, membershipRoutes.js, and publicRoutes.js with role-based authentication middleware guards.
5.6. src/middleware:

authMiddleware.js: Session validation and role-based authorization (Admin, Dealer, Buyer).
csrfMiddleware.js: Request token validation for state-changing HTTP requests.
errorMiddleware.js: Centralized 404 and 500 error catching.
5.7. src/services:

qrService.js: Server-side QR code generation.
payfastService.js: Signature hashing, payment form generation, and transaction confirmation.
emailService.js: Outbound transactional notification emails.
auditService.js: Immutable event tracking for administrative actions.
5.8. src/views:

EJS templates organized into layouts, public pages, authentication views, dealership consoles, and administrator portals.
5.9. src/public:

Static CSS stylesheets, icons, and client-side JavaScript for the mobile camera QR scanner.
SECURITY AND COMPLIANCE IMPLEMENTATION
Strict HTTP-only, secure, SameSite cookies to protect session IDs.
Comprehensive CSRF protection preventing unauthorized state-changing actions.
Content Security Policy (CSP) blocking unauthorized scripts, forms, and framing attacks.
Parameterized database queries eliminating SQL injection vulnerabilities.
Data structures aligned with the South African Protection of Personal Information Act (POPIA).
DEPLOYMENT AND EXECUTION
Local run executed via npm run dev or RunServer.bat at http://localhost:3000.
Database initialization handled via npm run migrate.
Seed data for default administrator and dealer credentials loaded via npm run seed.
Cloud deployment ready for Vercel, Render, or dedicated Linux server environments.