Waqar Ul Wahab
ALL PROJECTS/TOURAXIS

Overview

TourAxis is a tourism marketplace that connects tourists planning trips in destination cities with three kinds of provider — guides, hotel managers and vehicle operators — all overseen by a three-tier admin governance model (platform → country → city). It is built as two independently deployed applications: a Django REST API and a React single-page app, backed by a 29-model domain and 100+ endpoints covering catalogue listings, trip plans, bookings, a payment/payout ledger, reviews, notifications, analytics and live GPS tracking. Seven distinct roles share one platform: three governance tiers, three provider types and the default tourist.

Problem

A marketplace of this shape has two hard problems that must be solved at the same time. The first is authorization: providers may only touch their own listings, admins may only govern a defined geographic region, and every one of those checks has to be consistent across a dozen apps rather than re-implemented — and fail closed — per endpoint. The second is money and inventory integrity: prices must be computed server-side (never trusted from the client), bookings must not double-sell a guide, a hotel room or a vehicle, and a trip's live total must stay correct as bookings are accepted, declined or cancelled. The engineering brief was to make both of these load-bearing and correct while keeping the domain model DRY across the whole platform.

System Design

How It Works

01/04
01

Provider onboarding & catalogue approval

Providers self-register and list, then a geographically scoped admin moderates the listing before it goes public, with an orthogonal KYC track.

  1. 1Provider self-registers with an allowed self-signup role
  2. 2Provider creates a guide/hotel/vehicle listing, created pending and owned by the caller
  3. 3While pending the listing is visible only to its owner, filtered out of public querysets
  4. 4An in-scope admin approves (idempotent) or rejects (reason required) and notifies the owner
  5. 5An orthogonal KYC verification track vets provider documents independently of approval
02

Trip planning & the booking lifecycle

A tourist builds a single-city trip plan, requests provider bookings, and providers accept or decline through role-gated inboxes under a locked state machine.

  1. 1Tourist creates a trip plan for one city with a read-only currency derived from the country
  2. 2Itinerary stops are replaced transactionally and the live estimated total is recomputed
  3. 3Guide/hotel/vehicle bookings are created REQUESTED, guarded by availability and row-locked overlap checks
  4. 4Providers accept or decline from role-gated inboxes, re-verifying ownership under a lock
  5. 5Owner complete/cancel actions cascade booking statuses through one locked transition helper
03

Server-priced checkout & payouts

Checkout re-prices the plan server-side, captures payment through a pluggable gateway and records provider payouts in one atomic transaction.

  1. 1Checkout verifies the caller is the plan traveller or an admin
  2. 2The plan is re-priced server-side and any client-supplied amount is ignored
  3. 3Payment line items are derived, a 10% platform fee is computed, and payment is captured via a pluggable gateway
  4. 4A payout is created per active provider booking, linked back with a gross/net split
  5. 5A receipt notification and email are sent best-effort and fail-soft; payer and provider read their own ledgers
04

Live trip tracking

Anyone who can view a live plan streams GPS pings that render on the map, polled continuously while the trip is active.

  1. 1Viewers of a plan (owner, hired guide, group members, admins) post GPS pings to the tracking endpoint
  2. 2The reporter is forced to the authenticated user and the timestamp defaults server-side
  3. 3Latest position and the full ordered trail are exposed per plan, indexed for fast latest-first reads
  4. 4The frontend polls the latest position and trail roughly every 15 seconds while the plan is live

Key Features

  • Seven-role model (3 governance tiers, 3 provider types, tourist) with DB-reloaded, immutable role claims
  • Centralised fail-closed geographic authorization engine reused across all 11 backend apps
  • Catalogue approval workflow plus an orthogonal KYC verification track for providers
  • Trip planner with a DRAFT-to-COMPLETED state machine and granular guide-delegation flags
  • Anti-double-booking inventory checks (guide blackouts, hotel room blocks, vehicle overlap) under row locks
  • Server-authoritative checkout with 10% platform fee, provider payout ledger and a pluggable gateway
  • Completed-trip-gated polymorphic reviews driving a denormalised rating cache with admin moderation
  • Fail-soft notification layer (in-app feed + transactional email) and live GPS trip tracking

Outcomes

  • A single fail-closed authorization core makes admin governance consistent across 11 apps instead of per-view, rejecting IDOR and cross-region access
  • Server-side repricing with fee split and typed payout linkage keeps the money path authoritative; the gateway abstraction lets a real processor drop in with no view/model changes
  • DB-level date constraints, protected city references, row-locked transitions and half-up money quantization push correctness into the database and state machine
  • A 29-model domain factored through shared abstract mixins keeps the schema DRY and approval/rating logic single-path

More work