Pumpy Family Life
A two-sided accommodation marketplace connecting inventory, availability, bookings, payments, providers and host operations. I designed the API domains and transactional lifecycle across backend and storefront.
Source code is private. The case study focuses on state transitions, transaction rules and operational constraints rather than client-specific UI or business data.
- Product model
- Two-sided marketplace
- Audience
- Guests · hosts · providers
- Timeline
- 2025
- My role
- Backend engineer & API architect
- Context
- Private commercial product
- Delivery scope
- Domains · transactions · frontend integration
01
Product surfaces
Product surfaces
Distinct product surfaces made school, association and campus responsibilities visible before getting into the backend architecture.
Family booking flow
User-facing search, booking and checkout progression tied to real availability and pricing rules.
Provider management workspace
Supply-side profile, operational status and publication readiness before discovery.
Verification and trust states
Explicit approval states for properties and providers before they become publicly discoverable.
02
Problem and constraints
Problem and constraints
Accommodation commerce is not a simple listing flow. Inventory approval, date availability, price rules, guest currency, payment state, cancellation, refunds, reviews and host settlement must agree over time.
Trust before scale
Properties and providers cannot become discoverable before operational verification and approval.
Booking states and payment states are related, not identical
Booking, payment, refund and host-settlement states influence each other without collapsing into one generic status.
Live inventory versus transactional certainty
Availability seen during search can be stale by the time a booking is confirmed.
Operational visibility matters
Verification, pricing snapshots, refund paths and payout conditions need explicit operational signals.
03
My exact ownership
My exact ownership
I designed
- The domain boundaries between inventory, providers, community, booking and operational tooling.
- The lifecycle rules around approval, availability, booking, payment and refund states.
- The transaction model preserving pricing and payment transitions independently from discovery screens.
I implemented
- The modular API across users, accommodations, providers, community, dashboard and transactional flows.
- Booking, availability, review and verification workflows tied to explicit state transitions.
- The React storefront integration for query caching, map-based discovery and transactional forms.
I collaborated on
- Operational policies around provider approval, public discoverability and booking constraints.
- Frontend behavior aligning marketplace UX with transactional and verification rules.
03
Objectives
Objectives
Inventory
Model properties, hotels, rooms and calendars without duplicating common rules.
Transaction integrity
Validate availability and preserve the exact commercial calculation used at checkout.
Financial lifecycle
Make payment, refund, fee and host-payout transitions explicit.
Operations
Provide verification, dashboards, logs and signed media access for operational teams.
04
System architecture
System architecture
React · search · maps · checkout
Django REST · JWT · domain modules
PostgreSQL · Redis · object storage
Stripe · maps · notifications
Marketplace surfaces stayed distinct, while one domain backend enforced shared booking, payment, verification and pricing rules.
Technology stack
Backend
Django 4.2 · Django REST Framework · PostgreSQL · Django Filters
Frontend
React 18 · TypeScript · TanStack Query · Zustand · Mapbox
Transactions
Stripe · Payment snapshots · Refund lifecycle · Host payouts
Runtime
Redis · Cloudflare R2 · WhiteNoise · Structured logging
05
State model
State model
Payment state is validated independently from booking state so retries, cancellation and refunds remain explicit and auditable.
Pending
Price, fees, currency rate and booking references are snapshotted.
Processing
The payment processor confirms or rejects the transaction.
Completed
The booking is paid and host settlement can follow its own lifecycle.
Alternate transitions
Failed → pending
A failed transaction may be retried without creating an invalid transition.
Partial or full refund
Only a completed payment can move into refund states.
Cancelled
Pending or processing payments can terminate without settlement.
Payment state and booking state stay explicitly related rather than merged, which keeps retries, refunds and cancellation paths auditable.
07
Engineering challenges
Engineering challenges
Historical pricing must remain historical
Live rates, promotions and currency conversion can change after checkout.
Snapshot nightly price breakdown, service fee, billing version and EUR exchange rate on the payment record.
More financial fields and migrations are required, but reporting and refunds remain reproducible.
Without snapshots, refunds, support investigations and financial reporting drift as live catalog data changes.
Preventing invalid financial transitions
Generic status updates can refund an unpaid transaction or complete a cancelled one.
Encode allowed payment transitions in the model and reject state changes outside that graph.
Exceptional corrections require explicit operational tooling instead of direct database edits.
If booking and payment states can drift freely, users see impossible statuses and operations lose trust in the ledger.
Availability at the booking boundary
Search results can be stale by the time a guest confirms dates.
Treat calendar availability as discovery data and revalidate it when creating the booking.
Checkout can reject a previously visible option, but double booking is prevented at the transactional boundary.
If search availability is trusted blindly, stale inventory becomes double-booking or costly manual cleanup.
08
Failure modes & mitigations
Failure modes & mitigations
Provider verification incomplete
Supply approval states block public discovery until required host or property checks are complete.
Booking created while payment is unresolved
Payment transitions are validated independently so a reservation cannot be treated as financially complete by accident.
Search availability becomes stale at checkout
Availability is revalidated at the booking boundary instead of trusting discovery data.
Refund or payout path contradicts payment history
Allowed transition graphs keep refunds and host settlement tied to valid prior states.
09
Technical decisions
Technical decisions
Domains before endpoints
Django applications separate inventory, users, providers, chat and editorial concerns while one API router presents a coherent surface.
Verification is part of supply
Properties and providers move through explicit approval states before becoming publicly discoverable.
One transactional path
Availability, pricing, booking state, payment and review eligibility are treated as one connected lifecycle.
10
Security & operations
Security & operations
Authentication lifecycle
JWT rotation, blacklisting and explicit logout coexist with session authentication for operational tooling.
Request throttling
Anonymous, authenticated and authentication endpoints have separate rate budgets.
Private object access
Cloud storage uses signed URLs and non-overwriting object keys.
Operational diagnostics
Request IDs, processing-time headers, slow-request signals and sanitized headers support investigations.
- JWT rotation and explicit logout/blacklist paths.
- Availability validation at the booking boundary.
- Storage fallback and environment-aware configuration.
11
Delivered system
Delivered system
Implementation outcomes — no unverified commercial metrics.
Auditable transactions
Payment records retain the pricing and conversion assumptions used at purchase time.
Enforced lifecycle
Invalid payment transitions are rejected by the domain model.
Governed supply
Approval states control when properties and providers become public.
Modular expansion
Marketplace, provider, community and editorial domains can evolve without one oversized application module.
What I learned
“Marketplace complexity is mostly lifecycle complexity: each entity needs clear states, ownership and transitions before integrations are added.”