DriveEasy Car Rental Platform - Software Requirements Specification

DriveEasy Car Rental Platform - Software Requirements Specification DriveEasy

This document specifies the requirements for the DriveEasy car rental platform, a web-based system that allows customers to search for, reserve, pick up, and return rental vehicles across multiple branch locations. The platform supports online self-service for customers, fleet management for branch staff, and reporting dashboards for management.

Anna Sigurdsson Product Owner DriveEasy ehf. anna@driveeasy.example Bjarki Thorsson Lead Architect DriveEasy ehf. bjarki@driveeasy.example 2026-01-15 2026-02-20 v1.0.0 - 2026-Q3 The keywords "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as described in RFC 2119. "SHALL" and "MUST" denote absolute requirements. "SHOULD" denotes a recommendation. "MAY" denotes an option. IDs follow the pattern PREFIX-AREA-NNN where PREFIX indicates the element type (REQ, GOAL, TC, ENT, etc.), AREA indicates the functional area (RES for reservations, VEH for vehicles, PAY for payments, etc.), and NNN is a zero-padded sequence number. PCI-DSS compliance profile. Payment card handling must conform to PCI Data Security Standard v4.0. Reservation A confirmed booking that allocates a vehicle category for a customer during a specific date range at a designated branch location. Booking Rental Agreement The legally binding contract created at vehicle pick-up that governs the terms and conditions of the rental period, including insurance coverage, mileage limits, and liability. Rental Contract Vehicle Category A classification grouping vehicles by size and features, following ACRISS codes. Examples: Economy (ECMR), Compact (CCMR), Full-Size (FCMR), SUV (SFMR), Luxury (LCMR). Car ClassVehicle Class Branch A physical location where vehicles are stored, picked up, and returned. Each branch has an address, operating hours, and an assigned fleet. LocationStation CDW Collision Damage Waiver - an optional insurance product that limits the customer's financial liability for damage to the rental vehicle to the deductible amount stated in the waiver. One-Way Rental A rental where the vehicle is returned to a different branch than the pick-up location, incurring an additional one-way fee. A person who searches for vehicles, makes reservations, picks up and returns rental cars. May be authenticated (registered) or a guest. An employee at a branch location who handles vehicle check-out, check-in, damage inspections, and walk-in reservations. A manager responsible for vehicle acquisition, disposal, maintenance scheduling, and fleet distribution across branches. An IT administrator who manages user accounts, system configuration, pricing rules, and branch settings. External payment processing system (Stripe) that handles credit card authorizations, captures, and refunds. External email delivery service used for reservation confirmations, reminders, receipts, and account notifications. Feature completeness, customer satisfaction, conversion rates, competitive parity with industry leaders. Fleet utilization rates, branch efficiency, maintenance scheduling, real-time vehicle availability accuracy. Revenue recognition, pricing accuracy, payment reconciliation, financial reporting and audit compliance. GDPR compliance for personal data, PCI-DSS for payment data, rental agreement enforceability, insurance liability terms. Data protection, access control, vulnerability management, incident response, secure software development lifecycle. The system SHALL be deployed on AWS eu-west-1 (Ireland) to satisfy EU data residency requirements. Data Residency Policy - DriveEasy IT Governance The backend SHALL be implemented in Java 21 LTS using Spring Boot 3.x to align with the existing technology stack and team skills. Technology Standards - DriveEasy Platform Engineering PostgreSQL 16 SHALL be used as the primary relational database. Technology Standards - DriveEasy Platform Engineering The web frontend SHALL support the latest two major versions of Chrome, Firefox, Safari, and Edge. UX Guidelines - DriveEasy Design Team Primary Account Numbers (PANs) SHALL be rendered unreadable anywhere they are stored. The system SHALL NOT store CVV, full magnetic stripe, or PIN data after authorization. Quarterly scan reports, tokenization audit, no PAN in logs or backups. The system needs to handle recurring payments for rental extensions and damage charges after the initial rental. Storing full card numbers is prohibited by PCI-DSS. Use Stripe payment tokenization. Card details are collected via Stripe Elements on the frontend and never touch our servers. A reusable payment token is stored for post-rental charges. 1. Build PCI-compliant card vault in-house - rejected due to cost and compliance burden. 2. Use PayPal - rejected due to lower conversion rates in target markets. 3. Use Adyen - viable alternative but Stripe offers better developer experience and documentation. Positive: PCI scope is minimized (SAQ-A level). Negative: Vendor lock-in to Stripe; migration would require re-tokenizing all stored payment methods. Rental pricing varies by vehicle category, season, branch, rental duration, and demand. The business needs to adjust prices frequently without code deployments. Implement a rule-based pricing engine with configurable pricing rules stored in the database. Rules are evaluated in priority order with the first matching rule applied. 1. Hard-coded pricing tables - rejected; too inflexible. 2. External pricing SaaS - rejected; latency concerns and cost. Positive: Business can adjust pricing via admin UI. Negative: Complex rule evaluation logic; requires thorough testing of rule interactions. Fraudulent reservations using stolen credit cards could result in financial loss and vehicle theft. Car rental is a high-risk industry for card-not-present fraud. Implement 3D-Secure for online payments, require identity verification at pick-up with matching driver's license, pre-authorization hold on card at reservation time. See REQ-SEC-001, REQ-SEC-002. Insufficient fleet availability due to simultaneous reservations or late returns could lead to customers being unable to pick up reserved vehicles, causing reputational damage and compensation costs. Maintain a configurable overbooking buffer per category per branch. Implement real-time availability checks with pessimistic locking during reservation creation. See REQ-RES-003. A data breach exposing customer personal data (driver's licenses, payment information, addresses) would result in regulatory fines, legal liability, and severe reputational harm. Encrypt data at rest and in transit, implement least-privilege access controls, conduct regular penetration testing, maintain incident response plan. See REQ-SEC-003, REQ-SEC-004. Deep integration with Stripe for payments could make migration to an alternative provider costly and time-consuming. Abstract payment operations behind a PaymentGateway interface to isolate vendor-specific code. See DEC-PAYMENT-TOKEN. The DriveEasy domain models the core concepts of a car rental business: customers make reservations for vehicle categories at branch locations, vehicles are assigned at pick-up time, rental agreements govern the active rental period, and payments are processed for rental charges, extras, and damage claims. A person who rents vehicles. Holds personal information, driver's license details, and linked payment methods. Unique customer identifier. Customer's email address, used as login identifier. Must be a valid email per RFC 5322. Unique across all customers. Customer's first name. 1-100 characters. Customer's last name. 1-100 characters. Contact phone number in E.164 format. Must match E.164 pattern: +[country][number], max 15 digits. Date of birth, used for age eligibility verification. Customer must be at least 21 years old at rental start. Driver's license number. Driver's license expiration date. Must not be expired at time of pick-up. Account creation timestamp. A physical car in the fleet. Assigned to a branch and belongs to a vehicle category. Tracks mileage, maintenance status, and availability. Unique vehicle identifier. Vehicle license plate number. Unique across all vehicles. Format varies by country. Vehicle Identification Number (17 characters). Exactly 17 alphanumeric characters per ISO 3779. Vehicle manufacturer (e.g., Toyota, Volkswagen). Vehicle model name (e.g., Corolla, Golf). Model year. Must be within last 5 years for active fleet. Reference to vehicle category (ACRISS code grouping). Branch where the vehicle is currently assigned. Current odometer reading in kilometers. Non-negative. Updated at each check-in. Current operational status of the vehicle. A booking for a vehicle category at a branch for a date range. A specific vehicle is assigned at pick-up time, not at reservation. Unique reservation identifier. Human-readable confirmation code (e.g., DE-A1B2C3). Format: DE-[A-Z0-9]{6}. Unique across all reservations. Reference to the customer who made this reservation. Requested vehicle category. Branch where the vehicle will be picked up. Branch where the vehicle will be returned. Scheduled pick-up date and time. Must be at least 1 hour in the future at time of booking. Scheduled return date and time. Must be after pickupDate. Maximum rental duration: 90 days. Current reservation lifecycle status. Total estimated price at time of reservation. Non-negative. Currency is EUR. A physical rental location with an address, operating hours, and fleet. Unique branch identifier. Branch display name (e.g., "Keflavik Airport"). Short branch code (e.g., KEF, REK, AKU). 2-5 uppercase alphanumeric characters. Unique. Full street address of the branch. GPS latitude coordinate. Range: -90.0 to 90.0. GPS longitude coordinate. Range: -180.0 to 180.0. Whether the branch is currently operational. A financial transaction associated with a reservation. Covers pre-authorization, rental charges, extras, fuel, and damage fees. Unique payment identifier. Reference to the associated reservation. Payment amount in EUR. Positive value. Two decimal places. Type of payment transaction. Payment processing status. Stripe PaymentIntent ID for reconciliation. Timestamp when the payment was initiated. A customer must be at least 21 years of age at the start of the rental period to rent any vehicle. Customers under 25 incur a young driver surcharge of EUR 15 per day. Customer born 2005-06-15, rental starting 2026-06-14: REJECTED (age 20). Customer born 2005-06-15, rental starting 2026-06-15: ACCEPTED (age 21). Customer born 2002-03-01, rental starting 2026-06-01: ACCEPTED, surcharge applied (age 24). The customer's driver's license must be valid (not expired) on both the pick-up date and the scheduled return date. License expires 2026-07-01, rental 2026-06-15 to 2026-06-30: ACCEPTED. License expires 2026-06-20, rental 2026-06-15 to 2026-06-30: REJECTED. Free cancellation is permitted up to 48 hours before the scheduled pick-up time. Cancellations within 48 hours incur a fee equal to one day's rental charge. No-shows are charged the full rental amount. Pick-up at 2026-07-10 14:00, cancel at 2026-07-08 13:59: FREE. Pick-up at 2026-07-10 14:00, cancel at 2026-07-08 14:01: one day fee. No-show on 2026-07-10: full rental charged. Returns within 59 minutes after the scheduled time incur no penalty (grace period). Returns 1-4 hours late are charged a half-day rate. Returns more than 4 hours late are charged a full additional day. Due 14:00, returned 14:45: no extra charge (grace period). Due 14:00, returned 16:30: half-day charge applied. Due 14:00, returned 19:00: full additional day charged. When the return branch differs from the pick-up branch, a one-way fee is charged. The fee is determined by the distance between branches: EUR 50 for same-region, EUR 150 for cross-region. Vehicles are provided with a full tank. Customers must return the vehicle with a full tank or pay a refueling charge at EUR 2.50 per liter of fuel required to fill the tank, plus a EUR 30 service fee. Achieve a fully digital reservation flow so that customers can search for, compare, and book rental vehicles online without needing to call or visit a branch. Industry data shows 78% of car rentals are researched online. An online booking channel reduces branch workload and enables 24/7 reservation capability, increasing booking volume. Maintain an average fleet utilization rate of at least 75% across all branches during peak season and 55% during off-peak. Each idle vehicle costs approximately EUR 40/day in depreciation and insurance. Maximizing utilization directly improves profitability. Achieve a 15% increase in average revenue per rental through upselling of vehicle upgrades, insurance products, and extras. Extras and upgrades typically carry higher margins than base rental rates. Intelligent upselling at reservation and check-out improves average ticket value. Ensure full compliance with GDPR for personal data processing and PCI-DSS for payment card handling at all times. Non-compliance carries fines of up to 4% of annual turnover (GDPR) and loss of card processing privileges (PCI). Compliance is non-negotiable. Achieve and maintain a customer satisfaction score (CSAT) of at least 4.2 out of 5.0 for the digital booking and rental experience. High customer satisfaction drives repeat business and positive reviews, which are critical for growth in the competitive car rental market. The booking platform SHALL maintain high availability to support 24/7 online reservations. 99.9% uptime measured monthly, excluding planned maintenance windows. Vehicle search and reservation operations SHALL be responsive to ensure a smooth user experience. Vehicle search: p95 latency under 500ms. Reservation creation: p95 latency under 1000ms. Page load (above the fold): under 2 seconds on 4G connection. The system SHALL scale to handle peak booking periods (summer season, holiday weekends) without degradation. Support 500 concurrent users and 50 reservation transactions per second during peak load. The system SHALL protect customer data and resist common attack vectors. Zero critical or high-severity vulnerabilities in production. OWASP Top 10 coverage in security testing. Annual penetration test with all findings remediated within 30 days. Customers frequently return vehicles late, causing cascading availability problems for subsequent reservations at the same branch. Send automated reminders 24h and 2h before return. Enforce late fees. Build buffer time between consecutive reservations. Allow agents to reassign vehicles from nearby branches. Payment gateway outages or card declines during reservation could cause lost bookings and revenue. Implement retry logic with exponential backoff. Hold reservation for 15 minutes during payment retry. Support multiple payment methods as fallback. Summer tourism season in Iceland creates 5-10x demand spikes that could overwhelm the system and deplete fleet availability. Auto-scaling infrastructure, aggressive caching for search queries, rate limiting for API endpoints, advance fleet planning based on historical booking data. 1. Customer opens the DriveEasy website or mobile app. 2. Customer enters pick-up location, pick-up date/time, and return date/time. 3. Optionally, customer selects a different return location for one-way rental. 4. System validates dates (pick-up in future, return after pick-up, max 90 days). 5. System queries available vehicle categories for the given criteria. 6. System displays available categories with photos, features, and daily prices. 7. Customer can filter by category type, transmission, fuel, and sort by price. 8. Customer selects a vehicle category to proceed to reservation. 1. Customer selects a vehicle category from search results. 2. System displays pricing breakdown (base rate, taxes, fees). 3. System offers optional extras (CDW, GPS, child seat, additional driver). 4. Customer selects desired extras. 5. System updates total price with extras. 6. Customer enters personal details or logs in to existing account. 7. Customer enters payment information via Stripe Elements widget. 8. System creates a pre-authorization hold on the customer's card. 9. System confirms availability with pessimistic lock and creates reservation. 10. System generates a confirmation code and sends confirmation email. 11. Customer sees confirmation page with reservation details and code. 1. Customer arrives at branch and presents confirmation code and driver's license. 2. Agent looks up reservation by confirmation code. 3. System verifies customer identity against reservation and license validity. 4. Agent selects an available vehicle matching the reserved category. 5. System assigns the vehicle to the reservation and changes status to checked-out. 6. Agent performs walk-around inspection with customer, noting pre-existing damage. 7. Agent records vehicle mileage and fuel level. 8. Customer signs the rental agreement digitally on the agent's tablet. 9. System captures the pre-authorization and generates the rental agreement. 10. Agent hands over keys and vehicle documents to customer. 1. Customer returns vehicle to the designated branch. 2. Agent scans vehicle or enters license plate to locate the reservation. 3. Agent records return mileage and fuel level. 4. Agent performs damage inspection and documents any new damage with photos. 5. System calculates final charges: base rental, extras, fuel surcharge, late fees, one-way fee, and damage assessment if applicable. 6. System processes final payment (capture remaining amount or refund excess). 7. System updates reservation status to completed. 8. System marks vehicle as available (or routes to maintenance if damaged). 9. System sends receipt email to customer. 1. Customer logs in and navigates to "My Reservations". 2. Customer selects the reservation to cancel. 3. System displays cancellation policy and any applicable fee. 4. Customer confirms cancellation. 5. System releases the pre-authorization hold on the customer's card. 6. If within 48 hours of pick-up, system charges the cancellation fee. 7. System updates reservation status to cancelled. 8. System sends cancellation confirmation email. 9. System releases the reserved capacity for the vehicle category. 1. Fleet manager logs into the admin dashboard. 2. Fleet manager views fleet overview: vehicles by branch, category, and status. 3. Fleet manager adds a new vehicle with VIN, plate, make, model, and category. 4. Fleet manager assigns or transfers vehicles between branches. 5. Fleet manager schedules vehicles for maintenance, changing status. 6. Fleet manager retires old vehicles from active service. 7. System updates availability counts in real-time. 1. Attacker obtains stolen credit card details from dark web. 2. Attacker creates an account with fake identity details. 3. Attacker makes a reservation using stolen card for an expensive vehicle. 4. If payment succeeds, attacker picks up vehicle using a forged license. 5. Attacker does not return the vehicle, resulting in vehicle theft. COUNTERMEASURES: - 3D-Secure authentication for all online payments. - Pre-authorization hold captures funds and validates card. - Identity verification at pick-up: license must match reservation name. - Fraud scoring on reservations based on behavioral patterns. - GPS tracking on all vehicles with geofence alerts. 1. Attacker obtains customer credentials via phishing or credential stuffing. 2. Attacker logs in as the customer. 3. Attacker changes email and phone to attacker-controlled addresses. 4. Attacker makes a reservation using the customer's stored payment method. 5. Attacker picks up vehicle under stolen identity. COUNTERMEASURES: - MFA required for login and for changing contact information. - Rate limiting on login attempts with account lockout. - Notification to original email when contact details are changed. - Re-authentication required for sensitive operations. 1. Customer arrives for pick-up but no vehicles of the reserved category are available (e.g., all vehicles in maintenance or previous rentals not yet returned). 2. System displays alert to branch agent. 3. Agent offers a free upgrade to the next available category. 4. If no vehicles at all are available, agent arranges transfer from nearest branch or offers full refund plus compensation voucher. 5. System logs the incident for fleet planning analysis. 1. Customer completes reservation form and submits payment. 2. Stripe API call times out after 30 seconds. 3. System holds the reservation in "pending" status for 15 minutes. 4. System displays message: "Payment is being processed. You will receive a confirmation email shortly." 5. System retries payment via webhook reconciliation. 6. If payment succeeds, reservation is confirmed and email sent. 7. If payment fails after 3 retries, reservation is cancelled and customer is notified via email. 1. Two customers simultaneously attempt to book the last available vehicle in a category at the same branch for overlapping dates. 2. System uses database-level pessimistic locking on availability count. 3. First transaction to acquire the lock succeeds; reservation is created. 4. Second transaction finds availability exhausted and receives an error: "This category is no longer available for your dates." 5. System suggests alternative dates or nearby branches to the second customer. Requirements for the reservation lifecycle: searching, creating, modifying, and cancelling vehicle reservations. The system SHALL allow customers to search for available vehicle categories by specifying pick-up branch, return branch, pick-up date/time, and return date/time. Core functionality for online self-service booking. The customer is on the search page. The customer enters valid pick-up/return locations and dates and submits. The system displays all available vehicle categories with daily prices, sorted by price ascending. The customer enters dates where no vehicles are available. The search is submitted. The system displays a message "No vehicles available for your dates" and suggests nearby dates or branches. The system SHALL allow authenticated customers to create a reservation for a selected vehicle category, with optional extras, and process payment pre-authorization. Enables online booking without branch interaction. An authenticated customer has selected a vehicle category and extras. The customer submits payment details and confirms the reservation. The system creates the reservation with status "confirmed", generates a confirmation code, pre-authorizes the card, and sends a confirmation email. The system SHALL use pessimistic locking when creating a reservation to prevent overbooking of the last available vehicle in a category. Prevents double-booking race conditions under concurrent load. See edge case SCN-EDGE-DOUBLE-BOOK for the expected behavior. Only one vehicle remains in a category at a branch for the requested dates. Two customers simultaneously attempt to reserve that category. Exactly one reservation succeeds; the other receives a "not available" error. The system SHALL allow customers to cancel a reservation. Cancellation fees SHALL be applied according to business rule BR-CANCEL-POLICY. A customer has a confirmed reservation with pick-up more than 48 hours away. The customer cancels the reservation. The reservation is cancelled with no fee, the pre-authorization is released, and a cancellation email is sent. A customer has a confirmed reservation with pick-up less than 48 hours away. The customer cancels the reservation. The reservation is cancelled, a one-day cancellation fee is charged, the remaining pre-authorization is released, and an email is sent. The system SHALL send a confirmation email within 60 seconds of reservation creation, containing the confirmation code, rental details, pick-up instructions, and cancellation policy. The system SHALL allow customers to modify the dates, branch, or extras of a confirmed reservation, subject to availability. Price differences SHALL be reflected in the updated pre-authorization. A customer has a confirmed reservation. The customer changes the return date to a later date and availability exists. The reservation is updated, the price is recalculated, and a modified confirmation email is sent. Requirements for fleet tracking, vehicle lifecycle, and branch operations. The system SHALL allow branch agents to check out a vehicle to a customer by assigning a specific vehicle to a confirmed reservation, recording mileage, fuel level, and any pre-existing damage. A branch agent has a confirmed reservation and an available vehicle of the correct category. The agent completes the check-out process. The vehicle status changes to "rented", the reservation status changes to "checked-out", mileage and fuel are recorded, and the rental agreement is generated. The system SHALL allow branch agents to check in a returned vehicle, recording return mileage, fuel level, and any new damage, and calculate final charges including late fees per BR-LATE-RETURN and fuel surcharge per BR-FUEL-POLICY. The system SHALL provide a fleet management dashboard showing vehicle counts by branch, category, and status, with the ability to filter and search. The system SHALL allow fleet managers to initiate vehicle transfers between branches, updating the vehicle's assigned branch and tracking the transfer status. Requirements for payment authorization, capture, refunds, and reconciliation. The system SHALL create a pre-authorization hold on the customer's payment card for the estimated rental amount at the time of reservation confirmation. A customer confirms a reservation with a valid payment card. The reservation is submitted. A pre-authorization hold for the estimated total is placed on the card via Stripe, and the payment record is created with status "authorized". The system SHALL capture the final rental amount upon vehicle return, adjusting the pre-authorization to the actual charges. The system SHALL process refunds for cancelled reservations and overpayments within 5 business days, using the original payment method. The system SHALL respond to API requests within 500ms at the 95th percentile under normal load (up to 200 concurrent users). The system SHALL maintain 99.9% availability measured monthly, with planned maintenance windows not exceeding 4 hours per month during off-peak hours (02:00-06:00 UTC). The system SHALL support horizontal scaling by adding application server instances behind a load balancer without requiring architectural changes. The system SHALL expose a RESTful API conforming to OpenAPI 3.1 specification, using JSON request and response bodies, standard HTTP status codes, and HATEOAS links for resource navigation. The system SHALL integrate with Stripe API v2024-06 for payment processing, using PaymentIntents for pre-authorization and capture, and Stripe Elements for PCI-compliant card collection. The system SHALL integrate with an SMTP-compatible email service for sending transactional emails (confirmations, receipts, reminders). Emails SHALL use HTML templates with plain-text fallback. The system SHALL validate all input data at the API boundary: email addresses per RFC 5322, phone numbers per E.164, dates per ISO 8601, and VINs per ISO 3779. Invalid input SHALL be rejected with a 400 response and descriptive error messages. Completed rental records SHALL be retained for 7 years to comply with financial audit requirements. Customer personal data SHALL be anonymized after 3 years of account inactivity unless an active rental agreement exists. The system SHALL perform automated daily database backups with point-in-time recovery capability. Backups SHALL be encrypted and stored in a separate AWS availability zone. The system SHALL authenticate customers using email and password with optional TOTP-based multi-factor authentication. Passwords SHALL be hashed using bcrypt with a cost factor of at least 12. A registered customer with MFA enabled. The customer enters correct email and password. The system prompts for a TOTP code before granting access. The system SHALL enforce 3D-Secure (SCA) authentication for all online card payments to reduce fraud risk per PSD2 requirements. All customer personal data and payment tokens SHALL be encrypted at rest using AES-256. Database encryption SHALL use AWS RDS encryption with customer-managed KMS keys. All network communication SHALL use TLS 1.2 or higher. The system SHALL NOT accept connections over unencrypted HTTP. The system SHALL enforce role-based access control (RBAC) with the following roles: customer, branch-agent, fleet-manager, admin. Each API endpoint SHALL declare its required role(s). The system SHALL log all security-relevant events: login attempts, permission changes, payment operations, data access, and administrative actions. Logs SHALL be immutable and retained for 1 year. The system SHALL be deployable as Docker containers orchestrated by Amazon ECS on AWS eu-west-1, conforming to constraint CON-CLOUD. The backend SHALL be implemented in Java 21 with Spring Boot 3.x and PostgreSQL 16, conforming to constraints CON-LANG and CON-DB. The system SHALL provide an automated mechanism for customers to request deletion of their personal data. Verified erasure requests SHALL be fulfilled within 30 days per GDPR Art. 17. A customer submits a verified data erasure request. 30 days have elapsed. All personal data is deleted or anonymized, except records required for legal retention, and the customer receives confirmation. The system SHALL display a cookie consent banner on first visit, allowing granular opt-in to analytics and marketing cookies. Only essential cookies SHALL be set before consent is given. The web frontend SHALL be fully responsive, providing an optimized layout for mobile (320px-767px), tablet (768px-1023px), and desktop (1024px+) viewports. The web frontend SHALL conform to WCAG 2.1 Level AA accessibility guidelines, including keyboard navigation, screen reader support, sufficient color contrast, and focus indicators. The system SHALL support English and Icelandic, with the ability to add additional languages. All user-facing text SHALL be externalized into translation files. The system SHALL emit structured JSON logs to stdout, including correlation IDs, timestamps, log level, service name, and relevant business context. Logs SHALL be collected by AWS CloudWatch. The system SHALL expose /health/live and /health/ready endpoints returning HTTP 200 when the service is alive and ready to serve traffic, respectively. The readiness probe SHALL verify database and Stripe connectivity. The system SHALL expose application metrics in Prometheus format at /metrics, including request rates, error rates, latencies, active reservations, and fleet utilization by branch. Models the lifecycle of a rental reservation from creation through completion or cancellation. Reservation created, awaiting payment authorization. Generate confirmation code. Start 15-minute payment timeout. Payment authorization is in progress or not yet attempted. Payment authorized, reservation is active and waiting for pick-up. Send confirmation email. Schedule pick-up reminder for 24h before. Pre-authorization hold is active on customer's payment card. Vehicle has been picked up by the customer. Rental is active. Assign vehicle. Update vehicle status to rented. Generate rental agreement. Exactly one vehicle is assigned. Vehicle status is "rented". Vehicle returned, final payment processed, rental is closed. Release vehicle. Process final payment. Send receipt email. Reservation cancelled by customer or system before pick-up. Release pre-authorization. Apply cancellation fee if applicable. Send cancellation email. Customer did not pick up the vehicle within the grace period. Charge full rental amount per BR-CANCEL-POLICY. Send no-show notification. Payment authorization succeeds. Stripe pre-authorization returns success. Vehicle category still available. Persist reservation with status confirmed. Decrement available inventory count. Payment authorization fails after retries or timeout. Maximum retry attempts exhausted or 15-minute timeout expired. Log payment failure. Notify customer. Release held inventory. Branch agent checks out vehicle to customer. Customer identity verified. Driver's license valid per BR-LICENSE-VALID. Vehicle assigned and inspected. Record starting mileage and fuel level. Capture initial payment. Generate signed rental agreement. Customer cancels more than 48 hours before pick-up. Current time is more than 48 hours before scheduled pick-up. Release pre-authorization in full. Increment available inventory. Customer cancels within 48 hours of pick-up. Current time is within 48 hours of scheduled pick-up. Charge one-day cancellation fee. Release remaining pre-authorization. Increment available inventory. Customer does not arrive within the pick-up grace period (2 hours after scheduled time). Current time exceeds scheduled pick-up time by more than 2 hours. Charge full rental amount. Increment available inventory. Send no-show notification. Customer returns the vehicle to a branch. Return inspection completed. Final charges calculated. Record return mileage and fuel level. Calculate final charges per BR-LATE-RETURN and BR-FUEL-POLICY. Capture final payment. Release vehicle back to fleet. Models the operational status of a vehicle in the fleet. Vehicle is at a branch and available for rental. Vehicle has passed most recent inspection. No outstanding maintenance. Vehicle is currently rented to a customer. Vehicle is assigned to exactly one active reservation. Vehicle is undergoing scheduled or unscheduled maintenance. Create maintenance work order. Remove from available inventory. Record maintenance completion. Update mileage if applicable. Vehicle has been permanently removed from the active fleet. Archive vehicle record. Remove from all inventory counts. Reservation is confirmed and customer has been verified. Link vehicle to reservation. Record check-out mileage. Vehicle returned with no damage requiring repair. Return inspection shows no damage beyond normal wear. Unlink from reservation. Update mileage. Clean and refuel. Vehicle returned with damage requiring repair. Return inspection identifies damage beyond normal wear. Log damage details with photos. Create repair work order. Initiate damage charge to customer. Mileage threshold reached or time-based service interval due. Create maintenance work order. All work order items completed and signed off. Close work order. Mark vehicle available. Fleet manager approves retirement. No future reservations depend on this vehicle. Archive vehicle record. Repair cost exceeds economic threshold. Fleet manager approves retirement. Close work order. Archive vehicle record. Public-facing REST API for the customer web and mobile applications. Requires JWT bearer token for authenticated endpoints. Vehicle search is available without authentication.

Search for available vehicle categories.

Query parameters: - pickupBranchId (uuid, required) - returnBranchId (uuid, required) - pickupDate (ISO 8601 datetime, required) - returnDate (ISO 8601 datetime, required) - category (string, optional) - filter by ACRISS category - sort (string, optional) - "price_asc" (default), "price_desc", "category" - page (int, optional, default 1) - size (int, optional, default 20, max 50) 200 OK: Paginated list of available vehicle categories. Each entry includes: categoryId, categoryName, acrissCode, dailyRate, totalEstimate, features, imageUrl, availableCount. 400 Bad Request: Invalid date range, missing parameters. 422 Unprocessable Entity: Pick-up date in the past, return before pick-up.

Create a new reservation.

JSON body: { "categoryId": "uuid", "pickupBranchId": "uuid", "returnBranchId": "uuid", "pickupDate": "ISO 8601", "returnDate": "ISO 8601", "extras": ["cdw", "gps", "child-seat"], "paymentMethodId": "Stripe payment method ID" } Requires: authenticated customer. 201 Created: Reservation object with confirmationCode, status, totalPrice. Location header: /api/v1/reservations/{reservationId} 400 Bad Request: Validation errors. 402 Payment Required: Payment authorization failed. 409 Conflict: Vehicle category no longer available for requested dates.

Retrieve reservation details.

200 OK: Full reservation object including status, vehicle (if assigned), pricing breakdown, and cancellation policy. 404 Not Found: Reservation does not exist or belongs to another customer.

Cancel a reservation.

200 OK: Updated reservation with status "cancelled", cancellation fee details. 400 Bad Request: Reservation not in cancellable state. 404 Not Found: Reservation not found.

Modify a confirmed reservation (dates, branch, extras).

JSON body with fields to update: { "returnDate": "ISO 8601 (optional)", "returnBranchId": "uuid (optional)", "extras": ["cdw", "gps"] (optional, replaces current extras) } 200 OK: Updated reservation with recalculated pricing. 400 Bad Request: Invalid modifications. 409 Conflict: Requested changes not available.

List all active branches.

200 OK: Array of branch objects with id, name, code, address, coordinates, operating hours. API for branch operations: vehicle check-out, check-in, damage recording, and walk-in reservations. Requires branch-agent or admin role.

Check out a vehicle to a customer.

JSON body: { "vehicleId": "uuid", "mileage": 45230, "fuelLevel": 100, "damageNotes": "Small scratch on rear bumper (pre-existing)", "customerLicenseVerified": true } 200 OK: Updated reservation with status "checked-out" and assigned vehicle. Includes generated rental agreement PDF URL. 400 Bad Request: Missing required fields. 409 Conflict: Vehicle not available or reservation not in confirmed state.

Check in a returned vehicle.

JSON body: { "mileage": 45890, "fuelLevel": 75, "damageReport": { "hasDamage": true, "description": "Dent on front passenger door", "photoUrls": ["https://..."] } } 200 OK: Final charge breakdown, updated reservation with status "completed". 400 Bad Request: Missing required fields. 409 Conflict: Reservation not in checked-out state. API for fleet management: vehicle CRUD, transfers, and reporting. Requires fleet-manager or admin role.

Add a new vehicle to the fleet.

JSON body with vehicle details: vin, licensePlate, make, model, year, categoryId, branchId, currentMileage. 201 Created: Vehicle object with generated vehicleId. 400 Bad Request: Validation errors. 409 Conflict: VIN or license plate already exists.

List fleet vehicles with filtering.

Query parameters: branchId, categoryId, status, page, size. 200 OK: Paginated list of vehicles.

Transfer a vehicle to a different branch.

JSON body: { "targetBranchId": "uuid" } 200 OK: Updated vehicle with new branchId. 409 Conflict: Vehicle is currently rented or in maintenance. Emitted when a reservation is successfully confirmed after payment authorization. Triggers confirmation email and inventory update. { "reservationId": "uuid", "confirmationCode": "string", "customerId": "uuid", "customerEmail": "string", "categoryName": "string", "pickupBranch": "string", "pickupDate": "ISO 8601", "returnDate": "ISO 8601", "totalPrice": "decimal", "timestamp": "ISO 8601" } Emitted when a reservation is cancelled. Triggers cancellation email and inventory release. { "reservationId": "uuid", "confirmationCode": "string", "customerId": "uuid", "cancellationFee": "decimal", "reason": "customer_requested | payment_failed | no_show", "timestamp": "ISO 8601" } Emitted when a vehicle is checked out to a customer. Updates fleet availability dashboards. { "reservationId": "uuid", "vehicleId": "uuid", "licensePlate": "string", "branchId": "uuid", "mileageAtCheckout": "integer", "timestamp": "ISO 8601" } Emitted when a vehicle is returned. Triggers receipt email, fleet update, and potential maintenance scheduling. { "reservationId": "uuid", "vehicleId": "uuid", "branchId": "uuid", "mileageAtReturn": "integer", "fuelLevel": "integer", "hasDamage": "boolean", "finalCharge": "decimal", "timestamp": "ISO 8601" } Emitted when a payment transaction completes (authorization, capture, or refund). Used for financial reconciliation. { "paymentId": "uuid", "reservationId": "uuid", "type": "pre-auth | charge | refund", "amount": "decimal", "currency": "EUR", "stripePaymentIntentId": "string", "status": "authorized | captured | failed | refunded", "timestamp": "ISO 8601" } Tests for the reservation lifecycle: search, create, modify, cancel, and edge cases around availability and concurrency. Tests for payment authorization, capture, refund, and failure handling. Security tests covering authentication, authorization, injection, and data protection. Load and stress tests for API response times, concurrent users, and scalability. Verify that vehicle search returns correct available categories for valid criteria. 1. Set up test data: 3 branches, 5 categories, 20 vehicles with known availability. 2. Send GET /api/v1/vehicles/search with pickupBranchId=KEF, dates=2026-07-01 to 2026-07-05. 3. Verify response contains categories with available vehicles at KEF for those dates. 4. Verify each category includes dailyRate, totalEstimate, and availableCount. 5. Verify results are sorted by price ascending by default. Response is 200 OK with a paginated list of available categories. Categories with zero availability are excluded. Prices are accurate. Verify end-to-end reservation creation with payment authorization. 1. Authenticate as test customer. 2. POST /api/v1/reservations with valid categoryId, branches, dates, and Stripe test card. 3. Verify response is 201 with confirmationCode. 4. Verify reservation status is "confirmed" in database. 5. Verify Stripe pre-authorization was created for correct amount. 6. Verify confirmation email was sent. Reservation created with unique confirmation code. Pre-authorization matches total estimated price. Email delivered within 60 seconds. Verify free cancellation more than 48 hours before pick-up. 1. Create a confirmed reservation with pick-up 5 days from now. 2. POST /api/v1/reservations/{id}/cancel. 3. Verify reservation status changes to "cancelled". 4. Verify Stripe pre-authorization is released (no charge). 5. Verify cancellation email is sent with zero fee. Reservation cancelled. No cancellation fee charged. Pre-authorization fully released. Availability count restored. Verify integration with Stripe PaymentIntents for pre-authorization. 1. Create PaymentIntent with Stripe test API key and amount EUR 350.00. 2. Confirm PaymentIntent with test card 4242424242424242. 3. Verify PaymentIntent status is "requires_capture". 4. Capture PaymentIntent for final amount EUR 320.00. 5. Verify captured amount and remaining is released. Pre-authorization hold of EUR 350.00 created successfully. Final capture of EUR 320.00 succeeds. Remaining EUR 30.00 released. Verify graceful handling of Stripe payment failures. 1. Attempt reservation with Stripe test decline card 4000000000000002. 2. Verify PaymentIntent fails with "card_declined". 3. Verify reservation moves to "cancelled" state. 4. Verify customer receives appropriate error message. 5. Verify no charge was made to the card. Payment failure is handled gracefully. Reservation is cancelled. Customer sees "Payment declined" message with suggestion to try a different card. Verify cancellation fee logic per BR-CANCEL-POLICY. 1. Test cancel at 49 hours before pick-up: expect zero fee. 2. Test cancel at 48 hours exactly before pick-up: expect zero fee. 3. Test cancel at 47 hours 59 minutes before pick-up: expect one-day fee. 4. Test cancel at 1 hour before pick-up: expect one-day fee. 5. Test no-show: expect full rental charge. Fee calculation correctly applies the 48-hour boundary. One-day fee equals the daily rate of the reserved category. Verify late return surcharge per BR-LATE-RETURN. 1. Return 30 minutes late: expect no extra charge (grace period). 2. Return 59 minutes late: expect no extra charge (grace period). 3. Return 1 hour 1 minute late: expect half-day charge. 4. Return 3 hours 59 minutes late: expect half-day charge. 5. Return 4 hours 1 minute late: expect full-day charge. 6. Return 8 hours late: expect full-day charge. Grace period, half-day, and full-day thresholds applied correctly. Verify age checks per BR-AGE. 1. Customer age 20 at rental start: expect rejection. 2. Customer age 21 at rental start: expect acceptance, no surcharge. 3. Customer age 24 at rental start: expect acceptance, young driver surcharge. 4. Customer age 25 at rental start: expect acceptance, no surcharge. Under-21 customers are rejected. Age 21-24 incur EUR 15/day surcharge. Age 25+ have no surcharge. Verify that unauthenticated requests to protected endpoints are rejected. 1. Send POST /api/v1/reservations without Authorization header. 2. Send POST /api/v1/reservations with expired JWT. 3. Send POST /api/v1/reservations with tampered JWT payload. 4. Send POST /api/v1/reservations with JWT signed by wrong key. All requests return 401 Unauthorized. No reservation is created. Response does not leak internal details. Verify that customers cannot access other customers' reservations. 1. Create reservation as Customer A. 2. Authenticate as Customer B. 3. GET /api/v1/reservations/{customerA_reservationId} as Customer B. 4. POST /api/v1/reservations/{customerA_reservationId}/cancel as Customer B. Both requests return 404 Not Found (not 403, to avoid information leakage). Verify search endpoint is not vulnerable to SQL injection. 1. Send GET /api/v1/vehicles/search?pickupBranchId='; DROP TABLE reservations;-- 2. Send GET /api/v1/vehicles/search?pickupDate=2026-01-01' OR '1'='1 3. Verify database integrity after each request. Requests return 400 Bad Request. Database is not affected. No SQL error details are exposed in responses. Verify search endpoint meets p95 latency target under load. 1. Seed database with 50 branches, 10 categories, 5000 vehicles. 2. Run k6 load test: 200 virtual users, 5-minute duration. 3. Each user performs vehicle search with random branch and dates. 4. Collect response time percentiles. p50 latency under 200ms. p95 latency under 500ms. Error rate below 0.1%. Zero 5xx responses. Verify reservation creation under concurrent load without overbooking. 1. Set up a branch with exactly 10 vehicles in one category. 2. Launch 50 concurrent reservation requests for overlapping dates. 3. Verify exactly 10 reservations succeed. 4. Verify remaining 40 receive 409 Conflict. 5. Verify no overbooking occurred. Concurrency control prevents overbooking. 10 reservations created, 40 correctly rejected. No data inconsistency. Verify system handles personal data in compliance with GDPR requirements. 1. Review data flow diagrams for personal data processing. 2. Verify consent collection mechanism on registration and booking. 3. Verify data erasure endpoint and process. 4. Verify data retention periods match policy POL-GDPR-ERASURE. 5. Review privacy notice for completeness. All personal data processing has a valid legal basis. Erasure mechanism works within 30-day SLA. Retention periods enforced. Vehicle search is the entry point for online self-service booking. Concurrency-safe availability prevents overbooking and fleet mismanagement. Modification flexibility improves customer satisfaction. 3D-Secure reduces card-not-present fraud significantly. Reservation creation requires payment pre-authorization. Vehicle check-in triggers final payment capture. Payment pre-authorization depends on Stripe integration. Stripe integration depends on payment gateway interface spec maintained by the payments team. Primary implementation of reservation creation logic. DriveEasy consumes the Stripe PaymentIntents API for payment processing. Vendor lock-in could constrain future payment optimization opportunities. The rule-based pricing engine (DEC-PRICING-ENGINE) may become difficult to maintain as the number of pricing rules grows. Need to evaluate whether a dedicated pricing service or third-party solution would be more appropriate for the long term. Scheduled for architecture review in Sprint 4. Current plan is to proceed with the rule engine for v1.0 and re-evaluate based on operational experience after 6 months. The damage assessment and claims workflow at vehicle return needs further clarification. Questions: How are damage charges disputed? What is the appeals process? How are insurance claims (CDW) integrated with the damage workflow? Meeting scheduled with operations team for 2026-03-01 to map out the complete damage claims process. May result in additional requirements in PKG-VEH. Stakeholders have requested a loyalty/rewards program for repeat customers. This is currently out of scope for v1.0 but needs to be considered in the data model and architecture to avoid costly refactoring later. Decision deferred to v1.1 planning. ENT-CUSTOMER should be designed with extensibility for loyalty tier and points balance. Product Owner approval of functional requirements (PKG-RES, PKG-VEH, PKG-PAY) and UX requirements. Approved by Anna Sigurdsson on 2026-02-18. Security review of requirements in PKG-SEC and data protection measures. Pending review by Information Security team. Legal review of compliance requirements (REQ-PR-001, REQ-PR-002), rental agreement terms, and data processing agreements. Architecture approval of technology stack (CON-LANG, CON-DB, CON-CLOUD), integration decisions (DEC-PAYMENT-TOKEN), and non-functional requirements (PKG-NFR). Approved by Bjarki Thorsson on 2026-02-15.