# 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

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

## Architecture and App Boundaries

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

## Data Model Plan

### Accounts

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

### Equipment

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

### Adventrues

- [x] Create `AdventureCategory` (wine tour, hiking, excursion, etc.)
- [x] Create `AdventureOffering` (vendor, title, details, location, duration, capacity, pricing)
- [x] Create `AdventureImage`

### Booking

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

### Payment

- [x] Create `PaymentRecord` linked to bookings and Stripe IDs
- [x] Create `WebhookEvent` model for idempotent Stripe event processing

## Runtime and Infrastructure (Implemented)

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

## API Plan (DRF)

### Auth and Accounts

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

### Equipment APIs

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

### Adventrues APIs

- [x] Public adventure list/detail endpoints
- [x] Filters: category, location, date range, price range
- [x] Vendor CRUD for own adventures

### Booking APIs

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

### Payment APIs

- [x] Create Stripe PaymentIntent for approved bookings (mocked)
- [x] Payment status endpoint
- [x] Stripe webhook endpoint for payment lifecycle updates (mocked)

## Booking and Availability Rules

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

## Permissions and Security

- [x] Public read access for browse endpoints
- [x] Auth required for booking operations
- [x] 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

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

## Unit Testing and API Testing Plan

### Model Tests

- [x] Custom user creation and role rules
- [x] Availability overlap validation
- [x] Booking state transition validation
- [x] Payment idempotency constraints

### API Tests (DRF)

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

### Admin Tests

- [x] Admin model registration smoke tests
- [x] Admin actions for booking status updates

### Service Tests

- [x] Availability calculation correctness
- [x] Booking quote calculations
- [x] 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

- [x] Create and wire `accounts`, `equipment`, `adventrues`, `payment`
- [x] Set custom user model
- [x] Configure DRF, auth, and base permissions
- [ ] Establish shared utilities and base test setup

### Phase 1: Equipment Marketplace MVP

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

### Phase 2: Booking Engine

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

### Phase 3: Adventrues

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

### Phase 4: Payments

- [x] Stripe PaymentIntent endpoint integration (mocked)
- [x] Payment state synchronization with booking status
- [x] Webhook handlers and retries (idempotent event processing)
- [x] 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
- [x] API documentation and handoff notes

## Immediate Next Steps (Recommended)

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