booking_backend/implementation.md

Booking Platform Implementation Plan

This plan defines the backend architecture and delivery path for a DRF-based booking platform supporting equipment rentals now and adventures/events later.

Project Status

• Initial Django project scaffold exists (WaterTrek, booking, Docker/dev setup)
• DRF + authentication foundation fully configured
• Domain apps created and wired (accounts, equipment, adventrues, payment)
• Core data models and migrations implemented
• Public browsing/filter APIs implemented (equipment + adventrues)
• Booking/availability workflow implemented (equipment + adventrues booking flow)
• Stripe payment workflow implemented (mocked Stripe flow for development)
• Admin panel configured for operations
• Unit and API test coverage established (baseline model/service/api/admin tests)

Architecture and App Boundaries

• Keep project configuration in WaterTrek
• Use dedicated apps with strict ownership:
  • accounts: custom user model, roles, profiles
  • equipment: vendor storefronts and rental inventory
  • adventrues: tours/excursions/events (non-equipment bookings)
  • booking: availability calendars, booking requests, lifecycle
  • payment: Stripe intents/charges/refunds/webhooks
• Use DRF-only API endpoints (no HTML templates)
• Version API routes under /api/v1/

Data Model Plan

Accounts

• Implement custom User model (email login, password, phone)
• Add role flags or role enum (vendor, customer)
• Create VendorProfile (business identity, contact info, slug/store metadata)
• Create CustomerProfile for renter-specific data

Equipment

• Create EquipmentCategory (boat, car, bike, motorcycle, extensible)
• Create EquipmentItem (vendor, title, item ID, details, location, pricing, active status)
• Create EquipmentImage (image, primary image, ordering, alt text)
• Add extensible attributes (JSON) for future filtering metadata

Adventrues

• Create AdventureCategory (wine tour, hiking, excursion, etc.)
• Create AdventureOffering (vendor, title, details, location, duration, capacity, pricing)
• Create AdventureImage

Booking

• Create availability models (slot/rule-based)
• Link availability to EquipmentItem and AdventureOffering
• Create Booking model with lifecycle statuses:
  • requested
  • approved
  • declined
  • cancelled
  • confirmed
• Add booking notes, total price snapshot, and timestamp fields
• Add audit log/event history model for booking transitions

Payment

• Create PaymentRecord linked to bookings and Stripe IDs
• Create WebhookEvent model for idempotent Stripe event processing

Runtime and Infrastructure (Implemented)

• Dockerized Django service with uv dependency management
• PostgreSQL service in docker-compose
• Gunicorn configured as the web server for container runtime
• WhiteNoise static file serving configured for admin/static assets
• Container entrypoint runs migrations and collectstatic
• Custom user manager added so createsuperuser works with email login

API Plan (DRF)

Auth and Accounts

• Registration endpoint (vendor registration)
• Login + token refresh endpoints (JWT)
• Current user endpoint (/me)
• [~] Vendor/customer profile endpoints (vendor profile endpoint implemented)

Equipment APIs

• Public equipment list/detail endpoints
• Filters: type/category, location, date range, price range
• Vendor CRUD for own inventory
• Vendor storefront endpoint by slug

Adventrues APIs

• Public adventure list/detail endpoints
• Filters: category, location, date range, price range
• Vendor CRUD for own adventures

Booking APIs

• Availability query endpoint
• Booking request endpoint
• Vendor approve/decline endpoints
• Customer cancel endpoint
• Booking detail/list endpoints for both customer and vendor dashboards

Payment APIs

• Create Stripe PaymentIntent for approved bookings (mocked)
• Payment status endpoint
• Stripe webhook endpoint for payment lifecycle updates (mocked)

Booking and Availability Rules

• Enforce no overlap for approved/confirmed booking windows
• Define soft-hold behavior for requested bookings
• Normalize all datetimes to UTC in persistence
• Return ISO-8601 datetime strings to frontend
• Implement booking domain services:
  • is_bookable(...)
  • quote_booking(...)
  • create_booking_request(...)
  • transition_booking_status(...)

Permissions and Security

• Public read access for browse endpoints
• Auth required for booking operations
• Vendors can only edit their own resources
• Object-level permission checks for update/delete actions
• Rate limiting for auth and booking-request endpoints
• Media upload validation (type and size)

Admin Panel Plan

• Register all core models in Django admin
• Configure list views, filters, search, and inlines:
  • EquipmentItemAdmin with image inlines
  • AdventureOfferingAdmin with image inlines
  • BookingAdmin with status/date/vendor/customer filters
  • PaymentRecordAdmin with Stripe identifiers and statuses
  • VendorProfileAdmin searchable by business and email
• Add safe admin actions (approve/decline/confirm bookings)
• Mark system-managed fields as read-only where appropriate

Unit Testing and API Testing Plan

Model Tests

• Custom user creation and role rules
• Availability overlap validation
• Booking state transition validation
• Payment idempotency constraints

API Tests (DRF)

• Auth and token flows
• Role-based permissions and object access control
• Equipment/adventure list/detail/filter behavior
• Booking request happy path
• Booking overlap and invalid-range rejection
• Vendor approval/decline actions
• Payment API behavior with Stripe mocked

Admin Tests

• Admin model registration smoke tests
• Admin actions for booking status updates

Service Tests

• Availability calculation correctness
• Booking quote calculations
• Booking lifecycle transitions and guards

Stripe Integration Phases

• Phase A: payment models + local service abstraction
• Phase B: Stripe key/config wiring and PaymentIntent creation
• Phase C: webhook signature verification + idempotent processing
• Phase D: refunds and cancellation payment handling

Delivery Phases and Milestones

Phase 0: Foundation

• Create and wire accounts, equipment, adventrues, payment
• Set custom user model
• Configure DRF, auth, and base permissions
• Establish shared utilities and base test setup

Phase 1: Equipment Marketplace MVP

• Equipment models, migrations, admin
• Vendor inventory CRUD APIs
• Public browse/filter APIs
• Vendor storefront endpoint
• Unit/API tests for MVP behavior

Phase 2: Booking Engine

• Availability models and query APIs
• Booking request and status transition flows
• Overlap protections and lifecycle rules
• Unit/API/admin tests for booking workflows

Phase 3: Adventrues

• Adventure models, APIs, and admin
• Adventure availability integration
• Adventure booking requests through shared booking flow
• Test coverage for adventure-specific cases

Phase 4: Payments

• Stripe PaymentIntent endpoint integration (mocked)
• Payment state synchronization with booking status
• Webhook handlers and retries (idempotent event processing)
• Payment-focused unit/integration tests (mocked Stripe flow)

Phase 5: Hardening

• Permission audit and security checks
• Performance optimization and indexing
• Expanded tests and reliability tooling
• API documentation and handoff notes

Immediate Next Steps (Recommended)

• Complete DRF foundation:
  • Add djangorestframework and JWT auth package
  • Wire REST_FRAMEWORK defaults and auth classes in settings
  • Create versioned API router under /api/v1/
• [~] Build first API slice:
  • Read-only public list/detail endpoints for equipment and adventures
  • Authenticated booking request endpoint
• Raise quality baseline:
  • Add model tests for user manager + booking constraints
  • Add API smoke tests for auth and public catalog endpoints