carmanagement/project_design/FEATURES.md

Features & Priorities — RentFlow

MVP (Phase 1) — Must Ship Before Launch

Subscription & Billing

• Company signup → plan selection → payment via AmanPay or PayPal
• 14-day free trial (no payment required until trial ends)
• Company status: PENDING → TRIALING → ACTIVE / PAST_DUE / SUSPENDED
• Subscription gate middleware on all dashboard API routes
• Trial / past-due banners in dashboard
• Suspended account blocks dashboard; public site stays up
• Manual renewal flow: company pays via AmanPay (card/cash/e-wallet) or PayPal
• Invoice history (AmanPay transaction IDs or PayPal capture IDs)
• Supported currencies: MAD, USD, EUR

Tenant Isolation (Fleet Management)

• Every Prisma query scoped by companyId
• requireTenant middleware attaches companyId from authenticated employee
• Vehicle, customer, reservation IDs validated against companyId before any operation
• No cross-company data exposure — enforced at API level, not just UI
• Add / edit / archive vehicles
• Vehicle photos (Cloudinary)
• Published / unpublished toggle (controls marketplace + public site visibility)
• Vehicle categories, specs, features list

Offers / Promotions System

• Create offer (%, fixed amount, free day, special rate)
• Valid from / until dates
• Applicable to: all vehicles / by category / specific vehicles
• Optional promo code + max redemptions
• Minimum rental days
• isPublic flag — show on global marketplace
• isFeatured flag — featured carousel placement (plan-gated: GROWTH+)
• Offer applied at booking (discount calculated, stored on Reservation)
• Offer performance stats (redemptions, revenue impact)
• Offer banner image upload

Global Marketplace (rentflow.com/explore)

• Featured offers carousel on /explore home
• Search vehicles by city, dates, category, price range
• Company cards (logo, rating, offer badge)
• Company marketplace profile page (vehicles + offers + reviews)
• Vehicle detail page (photos, specs, redirect CTA to company site)
• Cross-company availability check
• Filter by category, transmission, price, features
• Marketplace listing toggle per company (opt out)

Renter Account System

• Renter signup / login (own auth, separate from Employee/Clerk)
• Email verification
• Renter profile (name, phone, locale, currency)
• Cross-company reservation history in /renter/dashboard
• Save / unsave companies
• Guest booking (no account required, but prompted to sign up after)
• When renter books, auto-create Customer record in that company's CRM

Online Reservations (all sources)

• Booking from dashboard (employee creates manually)
• Booking from company public site (BookingSource: PUBLIC_SITE)
• Booking from global marketplace (BookingSource: MARKETPLACE)
• Reservation lifecycle: DRAFT → CONFIRMED → ACTIVE → COMPLETED
• Offer / promo code applied at booking step
• Availability check before confirming
• Booking confirmation (number, summary, company contact)
• Cancel with reason + cancelledBy (COMPANY / RENTER / SYSTEM)

Branding & White-Label Public Site

• Company display name, logo, tagline, hero image
• Primary brand color picker
• Subdomain: {slug}.rentflow.com (claimed during onboarding)
• Real-time subdomain availability check
• Vercel wildcard domain routing (*.rentflow.com)
• Company public site: home with offers, vehicle listing, vehicle detail, booking, confirmation
• Offers page on public site
• "Powered by RentFlow" badge (removable on Pro)
• Site language + currency preference

Payments — Rental (AmanPay + PayPal)

• Company connects their own AmanPay merchant account (Merchant ID + Secret Key)
• Company connects their own PayPal business account
• Collect payment at booking (marketplace redirect + public site)
• AmanPay widget: national card, international card, cash (3000+ points), e-wallet
• PayPal buttons component (standard checkout)
• If no payment method configured: "Contact to reserve" + pay on pickup flow
• Payment status per reservation
• Refund on cancellation (via AmanPay or PayPal API)
• Guest checkout (no renter account required)

Notifications — Full System

• Email (Resend) — all notification types, rich HTML templates
• SMS (Twilio) — confirmations, reminders, payment alerts
• WhatsApp (Twilio WhatsApp API) — confirmations, reminders (key for AR/FR)
• In-App (Socket.io + Redis) — real-time bell icon in dashboard + renter site
• Push (Firebase FCM) — renter PWA push notifications
• Notification table — logs every delivery attempt per channel
• NotificationPreference table — per-user opt-in/out per type + channel
• Preferences UI: matrix toggle (notification type × channel)
• All company events: new booking, cancelled, payment received, trial ending, maintenance due, offer expiring, new review
• All renter events: confirmed, 24h reminder, 2h reminder, vehicle ready, return reminder, cancelled, refund, new offer from saved company, review request
• Scheduled notifications via cron (reminders, trial ending, maintenance due)

Reviews

• Renter submits review (only after reservation COMPLETED)
• 1–5 stars overall + vehicle + service
• Text comment
• Company can reply to review
• Reviews shown on marketplace company profile
• Average rating on company card + brand settings

Customer CRM

• Auto-created from any booking source
• Company-scoped view (never cross-company)
• Linked to global Renter account (if booked as logged-in renter)
• Rental history, notes, flag/blacklist

Auth & Onboarding

• Company employee auth via Clerk
• Renter auth via own JWT (separate)
• Onboarding step 2: branding + subdomain
• Onboarding step 4: "Your vehicles now appear on the RentFlow marketplace"
• Role system: OWNER / MANAGER / AGENT

Platform Admin Panel

• AdminUser model: email, password (bcrypt), role (SUPER_ADMIN/ADMIN/SUPPORT/FINANCE/VIEWER), 2FA (TOTP), last login tracking
• AdminPermission model: per-admin resource+action overrides on top of role defaults
• AuditLog model: every admin action logged (action, resource, before/after JSON, IP, note)
• Admin JWT auth (separate from Clerk and renter JWT) — 8h expiry
• TOTP 2FA: setup with QR code, verify, enforce for ADMIN+ roles
• Role hierarchy: VIEWER < FINANCE < SUPPORT < ADMIN < SUPER_ADMIN
• Admin role access matrix: 17 dashboard features × 5 roles
• admin.rentflow.com separate app (Next.js)
• Company management: list, search/filter, create, edit, suspend, reactivate, delete
• Company staff management: list employees per company, add employee, edit (name/email/role), deactivate/reactivate, reset password
• Impersonation: ADMIN+ can log in as any company employee (Clerk impersonation session), with dashboard banner
• Subscription override: force status, change plan, add free period with auto-revert
• Manual invoice mark-as-paid
• Renter management: list, search, view history, block/unblock
• Audit log UI: searchable, filterable by admin/action/company, CSV export
• Admin user management (SUPER_ADMIN only): create/edit/deactivate admins, set roles
• Platform metrics: MRR, churn, active companies, marketplace stats, notification delivery rates
• Prisma seed creates first SUPER_ADMIN from env vars
• Employee role control matrix (OWNER/MANAGER/AGENT) with 17 feature permissions documented

---

Advanced Rental Operations (Phase 1)

Vehicle Damage Inspection

• Interactive top-down SVG damage map in check-in/check-out workflow
• 22 clickable zones (hood, roof, doors, fenders, bumpers, wheels, windshield, mirrors, interior, undercarriage)
• 5 severity levels per zone: SCRATCH, DENT, CRACK, MISSING, OTHER — each shown in distinct color
• Optional note per damaged zone
• Optional damage photos upload (Cloudinary)
• DamageReport model — one per check-in, one per check-out (@@unique([reservationId, type]))
• Fuel level and odometer recorded at each inspection
• Customer acknowledgement timestamp + name
• Damage map rendered in PDF contract (static SVG with color markers) — CHECKIN + CHECKOUT side by side

Insurance Policies

• InsurancePolicy model: name, type (CDW, SCDW, THEFT, THIRD_PARTY, FULL, BASIC, ROADSIDE, PERSONAL, CUSTOM)
• Three charge types: PER_DAY, PER_RENTAL (flat), PERCENTAGE_OF_RENTAL
• Required vs optional flag — required policies auto-apply, cannot be opted out
• ReservationInsurance junction: snapshot of policy terms locked at booking time
• insuranceTotal cached on Reservation for fast invoice generation
• Insurance line items in customer invoice with charge type label
• Insurance shown on rental contract

Second / Additional Driver

• AdditionalDriver model: full personal details + license info
• Charge types: FREE, PER_DAY, FLAT
• Company configures default charge in ContractSettings
• License validation applied to additional drivers (same 3-month rule)
• Additional driver(s) listed on contract + invoice line item (if charged)
• Employee can approve/deny flagged additional driver license

Driver License Validation

• licenseExpiry, licenseIssuedAt, licenseCountry, licenseNumber, licenseCategory fields on Customer
• LicenseStatus enum: PENDING, VALID, EXPIRING, APPROVED, DENIED, EXPIRED
• 3-month rule: if license expires within 90 days → status=EXPIRING → requires employee approval
• Expired: status=EXPIRED → automatic flag → employee must explicitly approve or deny before confirmation
• License validation badge on customer record (green/amber/red)
• Warning banner on reservation detail when customer has EXPIRING or EXPIRED license
• Approve / Deny buttons for OWNER and MANAGER roles only
• Approval logged: who approved, when, and note

Age-Based & Experience-Based Pricing Rules

• PricingRule model: configurable per company
• Conditions: AGE_LESS_THAN, AGE_GREATER_THAN, LICENSE_YEARS_LESS_THAN, LICENSE_YEARS_GREATER_THAN
• Default rule: Under-25 surcharge (+15% of base rental, configurable)
• Default rule: 5+ years experience discount (−5%, configurable)
• Adjustment types: PERCENTAGE, FLAT_PER_DAY, FLAT_TOTAL
• Rules applied to primary driver AND all additional drivers (each rule applied once even if multiple drivers qualify)
• Rules shown as line items on invoice (surcharges positive, discounts negative)
• Snapshot of applied rules stored in Reservation.pricingRulesApplied JSON

Fuel / Gasoline Policy (Structured)

• FuelPolicyType enum: FULL_TO_FULL, FULL_TO_EMPTY, SAME_TO_SAME, PREPAID, FREE
• Multilingual policy description auto-generated from type (EN/FR/AR)
• Optional custom note added by company
• Fuel level recorded at check-in AND check-out via DamageReport.fuelLevel
• Policy printed on contract in customer's language

Full Invoice Price Breakdown

• Line items: base rental × days, per insurance policy, additional driver (if charged), pricing rule surcharges, pricing rule discounts, security deposit (refundable label)
• Category labels per line: RENTAL, INSURANCE, ADDITIONAL_DRIVER, SURCHARGE, DISCOUNT, DEPOSIT
• Tax/VAT line (if ContractSettings.showTax = true)
• Subtotal → discounts → surcharges → insurance → tax → deposit → GRAND TOTAL
• All amounts formatted in company's currency and locale

Billing Period Reporting (Accountant Export)

• Reports page at /dashboard/reports
• Preset periods: This Week, This Month, This Year, Custom range
• Summary cards: total bookings, base revenue, discounts given, insurance collected, additional driver revenue, net collected
• Full reservations table: contract#, invoice#, customer, vehicle, plate, dates, days, base, discount, insurance, additional driver, pricing adjustments, total, payment status, source
• Export as CSV (one click) — for import into accounting software (QuickBooks, Sage, etc.)
• Report generated on-demand from DB — no pre-computed tables

---

Phase 2 — Post-Launch

Fleet Enhancements

• Maintenance log with cost tracking
• Maintenance due alerts (date + mileage)
• Vehicle availability calendar view in dashboard

CRM Enhancements

• Repeat customer detection + discount
• Customer communication log (emails sent)
• Customer lifetime value stat

Analytics

• Revenue chart (day/week/month)
• Fleet utilization rate + underperforming vehicles alert
• Offer ROI analysis (revenue gained vs discounted)
• Marketplace impressions per vehicle
• CSV export

Renter Experience

• Renter "Continue with Google" auth
• Favorite vehicles across companies
• Renter profile completion % indicator
• Booking modification request (change dates)

Public Site Enhancements

• About page with company description + team photo
• Google Maps embed for pickup location
• "Request to book" mode (no immediate payment)
• WhatsApp floating button

---

Phase 3 — Growth

Custom Domain (Pro)

• Company enters cars.acme.com in /dashboard/brand
• Vercel API auto-provisions domain
• DNS instructions shown
• SSL automatic

Marketplace Enhancements

• City/region pages (/explore/cities/paris)
• Renter 2FA
• Sponsored listing (pay-per-click for marketplace placement)
• AI-powered vehicle recommendations based on renter history

Advanced Offers

• Flash sales (limited time countdown timer)
• Loyalty program (repeat renter discounts)
• Bundle offers (car + extras)

Integrations

• Google Calendar sync
• QuickBooks export
• Zapier webhooks

Documents — Rental Contracts & Customer Bills

• ContractSettings model: per-company legal name, RC/ICE number, tax ID, custom terms, fuel/deposit/damage policies, additional clauses, signature block, footer notes, invoice tax settings, numbering prefixes
• contractNumber + invoiceNumber fields on Reservation — assigned once via atomic DB transaction, never reset
• checkInFuelLevel / checkOutFuelLevel fields for contract accuracy
• Rental Contract PDF — branded with company logo + name + primary color, contains: customer details, vehicle data + cover photo, rental dates/locations, financial table (rate × days − discount + deposit), all policy clauses, full T&Cs, signature lines (company + customer)
• Customer Invoice PDF — branded, contains: company legal info + tax ID, bill-to block, line items table (vehicle, deposit, tax if configured), totals (subtotal, discount, tax, grand total), payment details (AmanPay/PayPal transaction ID, paid date), PAID/PENDING stamp
• Both documents support EN / FR / AR — all labels, date formats, and currency format per company locale
• On-demand generation — PDFs are NEVER stored. Generated fresh from DB data on every request. No Cloudinary PDF upload.
• Streaming PDF response — Content-Type: application/pdf, Content-Disposition: inline (view in browser tab) or attachment (download)
• Print from browser — user opens PDF in new tab and prints via native browser print dialog
• Email with PDF attachment — Resend sends email with both documents as attached PDFs
• Send contract + invoice together — single API call generates both and attaches both to one email
• Custom recipient email — override the customer's email address when sending (for forwarding)
• Renter self-download — renter can download their own contract/invoice from /renter/dashboard
• Settings preview — preview contract/invoice PDF with real company branding + sample data before finalizing settings
• Automatic triggers: invoice sent on payment confirmed; contract sent on check-in completed

Multi-location per company

• Multiple pickup/return locations
• Location-aware vehicle assignment
• Distance filter on marketplace

---

Out of Scope

• GPS / telematics
• Driver license OCR / ID verification
• Insurance products
• Fuel management
• Peer-to-peer (this is B2B SaaS + B2C marketplace, not P2P)
• Native mobile app (PWA covers push notifications)