# How our system was built — and why (history and decisions, Sept–Nov 2026)

Use this to answer "why does the system do X?", "when did we add Y?" and "what was decided about Z?". Dates are 2026.

## September — the booking app
- The main booking app (the PWA at /, with an Android wrapper app) searches live flights, hotels, car hire and coaches through API Travel Solutions' supplier connections, and sells packages. Real API credentials live only in a private config file, never in the code.
- Round-trip flights are searched in parallel; dialogs work with Escape and the phone's Back button; recent searches and calendars that block past days.

## October — the sites
- **9–11 Oct**: the first full travel sites (/travel/ … /travel5/). Hard rule then: never change the booking widget itself; sites embed it. travel4 got a first-class "embed mode" so a site can restyle the widget's flow without changing any booking call. travel5 is in the client's getaway.co.za look (black, red, gold, white) with the new Getaway Travel logo.
- **11 Oct**: booking flows made calm (no flashing between steps) on travel4/5.
- **2 Oct audit**: real PWA (offline page, install button), search validation, rate limits. The owner wants only premium, professional themes — no toy-like or illustrative ones, no curly fonts.
- **20 Oct**: 14 design-led sites ported from Claude Design exports onto the live widget (travel6–24, Buffelsfontein 1–2): each keeps its design and animation, only the booking is swapped for the real one. Showcase sites sit behind a showcase login.
- **26–27 Oct**: the back office rebuilt as a premium admin: a 9-step package wizard covering everything a package page shows, draft preview on any site, agent sign-up, approvals with chosen sites, managed lists, code pickers from the suppliers' own data, package rules (departures, seasons, child prices, single supplement, cut-off). **Partner Pack**: agent onboarding, documents (KYC), ledger, statements, stock, standards, reports.

## November — money, rules and going live
- **4 Nov**: **payment before every booking** — no on-account anywhere ("we are not taking risk on account bookings"). Every rate can be % or fixed R. Agent deal desk with versioned deals; tiers (later switched off); Corporate Booker (white-label company bookers). Pricing engine: never sell at the bare supplier price; strict mode adds our margin + VAT. Finance integrity: every sale's ledger lines add back to the sale; invoice numbers from one sequence; refunds once; owners' settlement; supplier payments; VAT payable. Admin regrouped into divisions; screens 13% smaller on big monitors.
- **5 Nov**: production audit: payment ↔ booking binding, cron + backups, go-live tool, VAT zero-rating switch. Owner's side note: make agent logins and package loading easy (still to do).
- **6 Nov**: **Deals, not Settings** — agents and corporates are priced and paid only on their own terms. **One source, no mistakes** — one place per setting, states honoured system-wide. **Corporates on our server** — client bookers are folders at /<shortname>/ (no installs, no keys), own domains allowed. **VAT the SA way** (agent on live sales, principal on own packages, agents' packages on their behalf).
- **7 Nov**: CA-level books audit: one payment → one booking, seller fixed at payment, browser cannot send money fields, complete deals required to trade, gateway cost booked in full, loss checks include agent share, VAT and promos. **Books are immutable**: history never recomputed, nothing with sales deleted, database triggers seal the books after go-live; invoices and credit notes frozen when issued; tax invoice contents ticked against VAT Act s20.
- **8 Nov**: the owners' **four split rules** (live 50/50; our packages 70/30; agent packages 50/50; monthly fees = live rule). International-flight fee zero-rated ON. Insurance stays off. **Finance** became the ONE home of money screens (Agents · Corporates · Platform · Books). Forgotten-password reset, list tools on every table (search, filters, sort, pages), Training section, three layouts (Standard, Classic/calm, Travel OS), My desk and Calendar, approval board for corporate trips. The dev books repaired ("everything real"): R0 bookings recorded from their payments or cancelled, invoice gaps recorded as void. Real fees set: gateway 2.9% + R2, flights R250 fixed, stays/cars 10%, coaches 8%.
- **9 Nov**: security pass: two-step sign-in for money actions after go-live, hashed sessions, ten-minute signed document links, throttles, sealed audit log.
- **13 Nov**: buffelsfontein6 "Bosreise" — the client's proposal look with Afrikaans sayings, bottle-opener pointer, frosted loader.
- **15 Nov**: whole-system contradiction audit: own-package money has one rule (the old platform fee can only be switched off), agent texts promise only deal rates, months end in SA time everywhere, corporate clients without written fees cannot book, help for every screen with in-depth "?" windows. **TravelClip** (this assistant) built: local brain (Qwen3-4B on the owner's computer), memory apart from the books, business-only by default with an owner-only tech mode, learns from Teach notes, 👍/👎 and corrections. The advisor added to Fees & margins (live CA heads-up while typing). Same evening the owner moved **flights to 10% and added a 1% customer card fee** (because a fixed R250 lost money on big fares).
- **16 Nov**: dashboard sales now read paid sales from the books in SA time (same as Finance). TravelClip got a calculator (exact numbers from the real engine with verdicts), accounting/tax/finance courses, every airport worldwide, and every South African town, region, wine farm and reserve with its nearest airport.

## Standing rules (never break them)
1. Card payment before every booking. 2. Agents on their deal only; corporates on their own fees; Settings only for our own sales.
3. One place per setting; money screens only in Finance. 4. Books immutable; corrections are new records. 5. No loss-making sale goes through.
6. Say "gateway fees (card)" / "payment gateway" — never the gateway company's name. 7. Sites: normal mouse pointer, readable colours, quick subtle motion, no black/solid backgrounds; things to do are never searched.

## Still open (as known on 16 Nov)
Tax invoice legal details before go-live; a git commit of everything since 6 Nov; simpler agent sign-up and package loading; a Getaway login; corporate booker self-service password reset; the Kestrel deal (their agent earns more than we do on flights); accountant questions (principal vs agent on international tickets, agents' tax invoices, intercompany).
