Tokoroa Alpine Club

AlpineClubBookingsNZ is an open-source booking, membership, payment, and lodge-operations platform for small clubs. Members book real beds against real capacity; admins run the whole club — bookings, membership lifecycle, fees, Stripe and bank-transfer payments, Xero accounting, lodge chores, even the TV in the lodge lobby — from one app.

One deployment serves one club — and this repository is the generic product every club deploys, not one club's copy of it. Nothing here encodes which club you are. Your name, capacity, age tiers, integer-cent rates, policies, wording, branding, and which capabilities exist at all are values you supply. So the normal way to adopt this is configure, don't fork, on four levers:

• Module toggle — switch a whole capability on or off for your deployment (kiosk, chores, waitlist, Xero, bed allocation, lobby displays, and more). docs/guides/modules.md is the live list, with each module's out-of-the-box default.
• Setting — every club has the capability, each supplies its own value or policy. Edited in the app, stored in the database, live immediately; no redeploy, no .env edit. Install-time values live in config/club.json.
• Seed default — the value a fresh install starts with. Change it when it is a poor starting point for a typical club, and send that upstream.
• Code change — only when the behaviour genuinely is not expressible through the generic model. Build the configuration surface at the same time, and contribute it upstream rather than carrying it forever in a fork.

The test that picks between them: would a different club answer this question differently? If yes, it is configuration, not code.

→ Adopting it? Start at Run this for your club, and read Configure, don't fork before you change any code.

What's in the box

🛏️ Booking engine — bed-capacity availability, NZ date-only lodge nights, waitlist and offers, holds, changes, cancellation rules, refunds, credits, promo and group discounts, exclusive whole-lodge holds → guide	👪 Membership lifecycle — registration, families and partners, nominations, seasonal membership types and age tiers, annual subscription billing, cancellation with GST-aware refunds → guide
💳 Payments, two ways — Stripe card payments (PaymentIntents + webhooks) and Xero-backed Internet Banking invoices with settlement tracking. Booking pages show additional card asks and dated supplementary invoice amounts with how to pay; card additions also have automatic reminders → guide	📒 Xero accounting built in — OAuth, webhooks, retry queues, invoice/credit-note lifecycle, and a native finance dashboard on Postgres snapshots → finance docs
🏔️ Lodge operations — rooms and beds, drag-and-drop bed allocation with per-lodge auto-allocation priorities, chores and rosters, work parties, hut leaders, lockers, inductions, PIN lodge kiosk → guide	📺 Lobby TV displays — paired read-only screens showing arrivals, rooms, chores, and notices, driven by live booking data with privacy-reduced names → display docs
🏘️ Multi-lodge core — lodge-scoped rooms, seasons, lockers, and chores with a cross-lodge waitlist → multi-lodge docs

Every feature above ships with an illustrated operator guide, one per admin area, plus member-facing user guides. They are indexed under Run this for your club, and docs/COVERAGE_MATRIX.md maps every admin route to the guide that covers it.

Concrete-booking emails can link authorized signed-in recipients straight to the booking detail, while public bearer actions remain separate.

See it in action

Admin dashboard	Member booking wizard
Drag-and-drop bed allocation	Lobby TV board (design concept)
Reports	Public club website

Apart from the lobby-display design concept above, screenshots are generated by a deterministic capture harness against seeded demo data (pnpm run docs:screenshots, see docs/images/README.md) and embedded throughout the operator guides.

Architecture at a glance

flowchart LR
  subgraph users [At the club]
    M["Members & guests"]
    A["Admins & committee"]
    K["Lodge kiosk (PIN)"]
    TV["Lobby TV displays"]
  end
  subgraph app [Next.js 16 App Router]
    W["Web app · API routes · cron jobs"]
  end
  M & A & K & TV --> W
  W --> DB[("PostgreSQL 16<br/>Prisma 7")]
  W <--> S["Stripe<br/>payments"]
  W <--> X["Xero<br/>accounting"]
  W --> E["AWS SES<br/>email"]
  W --> O["Sentry · pino<br/>observability"]
  W -. "blue/green deploys" .-> D["Docker Compose + Caddy"]

TypeScript end to end: Next.js 16 App Router and React 19, PostgreSQL 16 with Prisma 7, Auth.js credentials sessions (optional TOTP/email two-factor, magic-link, and Google sign-in), Tailwind CSS and Radix UI, Vitest and Playwright. It is also published as a real-world reference implementation of a production Next.js application with payments, accounting, email, scheduled jobs, and Docker-based blue/green deployment. The full system design — data model, booking capacity rules, integration boundaries, cron, and deployment shape — is in docs/ARCHITECTURE.md.

After successful two-factor verification, sign-in opens the resolved destination in a fresh page load. Enrollment keeps recovery codes visible until Continue.

Quickstart

Needs Node 24 and pnpm 11 (npm install -g pnpm@11 once per machine; see "Package manager: pnpm").

git clone https://github.com/thatskiff33/AlpineClubBookingsNZ.git
cd AlpineClubBookingsNZ
cp .env.example .env                              # then edit — see CONFIGURATION.md
cp config/club.example.json config/club.json
pnpm install --frozen-lockfile && pnpm exec prisma generate
pnpm run setup:check                               # guided: pnpm run setup:wizard

Boot a full production-style stack (app + PostgreSQL) with Docker only:

cp .env.staging.example .env.staging
docker compose --env-file .env.staging -p tacbookings-staging \
  -f docker-compose.yml -f docker-compose.staging.yml up -d --build postgres app
docker compose --env-file .env.staging -p tacbookings-staging \
  -f docker-compose.yml -f docker-compose.staging.yml run --rm migrate
docker compose --env-file .env.staging -p tacbookings-staging \
  -f docker-compose.yml -f docker-compose.staging.yml exec app ./node_modules/.bin/tsx --conditions=react-server prisma/seed.ts

Then open http://localhost:3001 and sign in with your SEED_ADMIN_* credentials.

Adopting this for your club is a documented, tested path, and every step is configuration:

1. Set your club name, beds, age tiers, and integer-cent rates in config/club.json (or run pnpm run setup:wizard).
2. Seed the first admin, then finish the in-app checklist at /admin/setup.
3. Brand it — colours, fonts, and logo at /admin/site-style, no redeploy needed — and replace the included club branding and copy with your own (NOTICE.md).
4. Toggle the capabilities you want under Admin → Modules. Connecting Xero is fully in-app — a guided wizard at Admin → Xero → Setup walks you through creating the Xero app, entering its credentials (encrypted at rest), and the OAuth connect, with no .env edits or key generation.

The whole adopter path is indexed at Run this for your club. The step-by-step walk from clone to first deployment is docs/IMPLEMENTATION_GUIDE.md; every environment variable and the config/club.json schema are in CONFIGURATION.md; the reference Docker + reverse-proxy blue/green production setup is in DEPLOYMENT.md.

Engineering quality

• Money is property-tested. Pricing, promo discounts, refund tiers, change fees, credits, and Xero settlement math are enforced as universally-quantified properties (integer cents; refund + retained = paid) with fast-check — see docs/DOMAIN_INVARIANTS.md.
• Critical journeys run in real browsers. Playwright E2E suites cover booking, payments, waitlist, two-factor login, bed allocation, and more against a seeded staging stack (docs/E2E_PLAYWRIGHT.md).
• No test may depend on today's date. Every unit test file runs with "today" frozen at 1 July 2026, and a canary re-runs the whole suite with the machine's real clock wound forward by a year to catch anything that escapes the freeze (docs/TESTING.md).
• Migrations are gated for zero-downtime. Every schema change is classified under the blue/green ledger before it can merge (docs/BLUE_GREEN_MIGRATION_POLICY.md).
• Accessibility is a baseline, not a feature. Semantic status tokens, icon-or-text redundancy, keyboard focus outlines, and a reduced-motion guard, verified by a staging Lighthouse workflow (docs/STAGING_ACCESSIBILITY.md).
• CI blocks the merge. Lint, typecheck, unit + property tests, build, migration-drift, static-analysis, and E2E checks are all required on main (docs/MAINTENANCE.md).
• Backups are drilled, not assumed. S3-backed PostgreSQL backups are configured in-app at Admin → Integrations → Database Backups (no .env edits), run on demand or nightly, and ship with a scripted quarterly restore drill (, ).

Releases and upgrades

Versioned, classified releases with written upgrade paths: GitHub Releases · CHANGELOG.md · release notes index · docs/UPGRADING.md · docs/PRODUCTION_UPGRADE_RUNBOOK.md. Deploys ship from GHCR images (alpineclubbookingsnz-app, alpineclubbookingsnz-migrate) via a single blue/green deploy script.

Documentation

The documentation is split by audience into three doors, indexed at the documentation hub:

You are…	Go to
Adopting, configuring, deploying or operating it for a club	Run this for your club — Configure, don't fork · docs/IMPLEMENTATION_GUIDE.md · CONFIGURATION.md · DEPLOYMENT.md · operator guides · docs/UPGRADING.md
Changing the code — contributor or automated agent	Change the code — AGENTS.md · CONTRIBUTING.md · docs/ARCHITECTURE.md · docs/DOMAIN_INVARIANTS.md · ·

Community, security, and licence

• Questions and help: SUPPORT.md · conduct: CODE_OF_CONDUCT.md
• Contributions welcome — read CONTRIBUTING.md first. Running a fork and want a change maintained for you? Contribute it upstream
• Report suspected vulnerabilities privately via SECURITY.md; never post secrets, personal data, or accounting records in public issues
• MIT licensed (LICENSE). Club branding, logos, copy, and domains are included for context only — replace them before using a fork for another organisation (NOTICE.md)

Built for every small club still running its lodge on spreadsheets. The reference deployment is Tokoroa Alpine Club, which runs it in production; nothing about that club is baked into this repository.