Bookra/project.md

# Bookra

## Delivery Tracker
- `[done]` Milestone 1: Remote-first monorepo scaffold completed
  - SolidJS frontend shell
  - Go + Gin backend shell
  - OpenAPI-driven TS client generation
  - Neon Auth adapter boundary
  - remote-first env layout for Vercel, Railway, and Neon
- `[done]` Milestone 2: Repository-backed booking baseline completed
  - DB/in-memory repository boundary added
  - public availability now generated through backend service logic
  - public booking creation now goes through real service validation
  - appointment conflict detection implemented
  - class capacity and waitlist fallback implemented
  - backend tests added for booking and slot behavior
  - frontend public booking page can submit a demo booking
- `[done/partial]` Milestone 3: Tenant bootstrap, dashboard hydration, and Neon-authenticated API flows
  - tenant bootstrap endpoint now resolves through repository-backed membership lookup
  - dashboard summary endpoint now resolves through repository-backed metrics lookup
  - frontend dashboard now hydrates from API when a Neon Auth JWT is available
  - frontend dashboard degrades to contract-shaped preview mode when auth is unavailable
  - Neon Auth token acquisition remains adapter-isolated and still needs production validation against live Neon Auth
- `[done/partial]` Milestone 4: Stripe subscription sync and entitlement baseline completed
  - normalized billing snapshot model added to backend and OpenAPI contract
  - backend-owned subscription state now syncs through one overwrite path
  - Stripe checkout launch endpoint added
  - Stripe webhook endpoint added with signature verification and event filtering
  - billing snapshot refresh endpoint added
  - customer portal endpoint added
  - plan entitlements now derive from normalized plan state
  - dashboard now surfaces billing status, entitlements, and checkout actions
  - mock/no-key fallback still works for local development
- `[done/partial]` Milestone 5: Reminder jobs, notification delivery abstractions, and remote job-runner baseline completed
  - booking creation now schedules reminder jobs for qualifying upcoming bookings
  - notification service now dispatches due jobs through replaceable provider interfaces
  - localized reminder copy now renders with tenant locale/timezone context
  - notification delivery log persistence added
  - internal reminder dispatch endpoint added for Railway-style scheduled execution
  - shared job-runner key added for remote job execution
  - current providers are noop-safe abstractions; real email/SMS vendors still need production integration
- `[done/partial]` Milestone 6: Production auth completion and tenant identity sync baseline completed
  - verified Neon JWTs now sync app-side users automatically on protected requests
  - app-side membership resolution now maps by `users.neon_subject` instead of assuming JWT subject equals DB primary key
  - frontend auth provider now reads JWT from the Neon session contract instead of a fallback token hook
  - bootstrap payload now returns user identity fields needed for authenticated shells
  - Neon subject schema migration added for production databases
  - live Neon Auth / staging validation still needs to be completed against real infrastructure
- `[done/partial]` Milestone 7: First-tenant onboarding flow added to the dashboard
  - authenticated users without membership now see a real workspace creation flow in `/dashboard`
  - protected tenant onboarding endpoint added with backend validation for slug, preset, locale, and timezone
  - onboarding now creates the tenant, owner membership, and first default location
  - dashboard can transition from empty bootstrap shell to a provisioned tenant state
  - post-onboarding entity screens for locations, services, staff, blocked days, working hours, and class templates/sessions now exist (Milestones 8 and 10)
- `[done/partial]` Milestone 8: Catalog management shipped; live staging validation and operational hardening remain
  - service CRUD end-to-end: repository (pgx + in-memory), catalog service with validation and tenant isolation, protected `/v1/catalog/services` routes, OpenAPI schemas, dashboard services page
  - staff CRUD end-to-end with active toggle, optional location assignment, and `MaxStaff` entitlement enforcement; dashboard staff page with upgrade prompt
  - dashboard summary now resolves `staffName` on bookings and computes `setupCompletion` from real state (brand, location, service, staff, schedule)
  - booking modal service field is a select bound to the tenant's real services; blocked-day creation supports optional per-staff scoping
  - deleting a service or staff member preserves bookings (FK `SET NULL`) and removes the member's availability rules (`CASCADE`), mirrored in the in-memory repository
  - live staging validation, real Neon Auth/Stripe/SMS provider checks, and operational hardening are still open
- `[done/partial]` Milestone 9: Public booking flow with real service/staff selection
  - public booking page is now a stepped flow: pick service → optional staff preference → pick day → pick time; class sessions still listed below
  - `GET /v1/public/tenants/{slug}/catalog` exposes bookable services and active staff for the booking page
  - availability endpoint accepts `serviceId`, `staffId`, and `date` filters; default response is unchanged for the embeddable widget
  - slots now carry `staffName`, respect tenant-wide and per-staff blocked days, and are generated per-day without the preview cap when `date` is given
  - booking creation hardened: appointment requests must fit inside a matching availability rule, not overlap a blocked day, and staff/location IDs must belong to the tenant with staff active
  - remaining: live staging validation
- `[done/partial]` Milestone 10: Per-staff availability and class/session management
  - working-hours repository now accepts a nullable staff scope on list/update (pgx + in-memory); staff-scoped rules live in `availability_rules` and directly drive public slot generation
  - protected routes added: `GET/PUT /v1/catalog/staff/{id}/working-hours[/{day}]` with tenant-ownership checks
  - class template + session CRUD end-to-end: repository (`classes.go`), catalog service with validation, protected `/v1/catalog/class-templates` and `/v1/catalog/class-sessions` routes, OpenAPI + regenerated client
  - sessions derive `endsAt` from template duration, default capacity from the template, validate future start, tenant-owned template and optional location; list resolves template title, location name, and live booked count
  - deletion semantics mirror the schema: deleting a template cascades its sessions; deleting a session preserves bookings via `class_session_id SET NULL` (mirrored in the in-memory repo)
  - dashboard zones page gained a staff-scope selector on the working-hours tab (business-wide vs individual schedule) and a Classes tab with template create/delete and session scheduling
  - normalized `availability_rules` time columns (`HH:MM:SS`) down to the `HH:MM` API contract in the service layer
  - remaining: live staging validation
- `[done/partial]` Milestone 11: Booking lifecycle — dashboard cancellation and waitlist promotion
  - businesses can cancel bookings from the dashboard (`POST /v1/catalog/bookings/{id}/cancel`), tenant-checked, with a two-step confirm in the booking detail modal
  - cancelling a class booking (dashboard or customer self-service) now promotes the earliest waitlisted bookings while free capacity remains, ordered by booking `created_at`; promoted customers receive a confirmation email, cancelled customers a cancellation email
  - shared `bookings.PromoteWaitlist` helper drives both cancel paths; waitlist ledger entries are marked resolved on promotion
  - bookings surface the `waitlisted` status: stats card, filter option, warning-tone badge, demo seed entry; `dashboard.{status}` interpolation resolves the new i18n key automatically
  - `BookingRecord` now carries `created_at` (needed for fair waitlist ordering); `GetBookingByID` added to the repository surface
  - remaining: live staging validation; waitlist position display and manual promotion controls are not yet exposed
- `[done/partial]` Milestone 12: Real dashboard business metrics
  - `DashboardMetrics` gained `CompletedCount` (confirmed bookings already ended within the window) in both pgx and in-memory repositories
  - `DashboardSummary` now queries three trailing windows (next 7d, last 7d, 7-14d ago) and emits four KPIs with real trend deltas: `bookings_this_week`, `completed`, `cancellations`, `utilization` (delta in percentage points)
  - `DashboardKPI` carries optional `change`/`trend` (`up|down|neutral`); the KPI card already rendered these, so real data now drives the trend arrows instead of the previous `neutral`/`—` fallback
  - KPI labels are localized in the frontend via a `code` → i18n-key map (`dashboard.kpi.bookingsThisWeek`, `cancellations`, `utilization`; `completed` reuses the existing key); backend labels stay English as a fallback
  - the booking-trend chart was already bucketing real `allBookings` into the current week — confirmed, no change needed
  - demo mode intentionally keeps curated static KPI values; real tenants get the computed set
  - remaining: live staging validation; "new clients" KPI still has no backend metric (customer entity lacks first-booking tracking)
- `[done/partial]` Milestone 13: Reminder pipeline reliability
  - reminder jobs are lifecycle-aware: customer and dashboard cancellation mark pending jobs `cancelled`; reschedule deletes pending jobs and re-arms one via `reminderSchedule` for the new time (no job when moved inside the no-reminder horizon)
  - dispatch now joins `bookings.status` and skips non-confirmed bookings (`skipped` job status, `skippedCount` in the response contract) — cancelled/waitlisted customers no longer receive reminders for bookings that are not happening
  - reschedule hardened with the same validation as booking creation: appointment reschedules must fit an availability rule and avoid blocked days (`validateAppointmentTarget` is now a shared package-level helper); class bookings keep session-defined times
  - new repository methods `CancelPendingReminderJobsForBooking` / `DeletePendingReminderJobsForBooking` in pgx and in-memory implementations
  - remaining: live staging validation; SMS reminder channel exists in schema (`channel` column) but only `email` is dispatched — SMS reminders are a separate opt-in feature
- `[done/partial]` Milestone 14: Metrics completion + reminder dispatch scheduling
  - `DashboardMetrics` gained `NewClientsCount` — distinct customer emails whose earliest-ever booking (`starts_at`) lands in the window; a fifth KPI `new_clients` completes the set the demo data promised
  - KPI grid rebalanced for five cards (`lg:grid-cols-3 xl:grid-cols-5`); `new_clients` maps to the existing `dashboard.kpi.newClients` i18n key
  - reminder dispatch now has a real trigger: `.github/workflows/reminder-dispatch.yml` calls `POST /v1/internal/jobs/reminders/dispatch` every 15 minutes with `X-Bookra-Job-Key` from secrets (`BOOKRA_API_URL`, `BOOKRA_JOB_RUNNER_KEY`); jobs are timestamp-based so scheduler lateness delays but never skips
  - remaining: live staging validation; the workflow no-ops gracefully until the two secrets are configured
- `[done/partial]` Milestone 15: SMS reminder channel
  - booking creation arms a second reminder job on `channel: sms` when the tenant has SMS enabled (`tenant_sms_settings.enabled`) and the customer left a phone number; email jobs are unchanged
  - `notifications.Service` gained an injected `smsSender` function adapter (wired to `sms.Service.SendMessage` in the API server, keeping the package dependency-free); dispatch routes `channel: sms` through it with localized body text and the customer phone as recipient
  - `sms.Service.SendMessage` still enforces enabled/plan/monthly-limit and logs usage, so SMS reminders inherit metering and billing automatically; missing provider config or phone marks the job `failed` with a delivery-log reason
  - reminder lifecycle work from milestone 13 applies per-booking, so cancel/reschedule clears and re-arms both channels
  - remaining: live staging validation against a real SMS Manager key
- `[done/partial]` Milestone 16: Waitlist position display
  - `GetWaitlistPosition` repository method (pgx + memory) returns the 1-based queue spot: count of earlier-created waitlisted bookings on the same session + 1
  - `CustomerBookingView` carries `waitlistPosition` for waitlisted class bookings; the manage page now shows a proper status badge for `waitlisted`/`cancelled` (previously both rendered as "Pending") plus a notice with the queue position and the auto-promotion explanation, in CS and EN
  - fixed invalid token names along the way (`--danger-soft`/`--warning-soft` do not exist; `--error-subtle`/`--warning-subtle` do)
  - remaining: live staging validation; manual waitlist promotion controls are still not exposed

## Overview
Bookra is a Czech-first booking SaaS for small local service businesses. It targets salons, massage therapists, small clinics, repair shops, and small studios/clubs that need a simple public booking flow, internal schedule management, reminders, and basic business reporting without becoming a full ERP.

The product is multi-tenant, calm in scope, and optimized for production quality rather than a fast prototype.

## Product Direction
Bookra uses one unified booking core with tenant presets.

This means:
- one platform for appointments and simple classes
- different business presets for salon, clinic, repair, massage, sports/studio
- shared scheduling, reminders, dashboard, and billing logic
- no industry-specific forked products in v1

## Launch Scope
### Market
- Czech Republic first
- English included at launch
- EU-friendly hosting and data handling defaults

### Supported booking models
- Appointments
- Capacity-based classes

### Explicitly out of scope for v1
- Customer payments for bookings
- Deposits or prepaid services
- Memberships, passes, or package accounting
- Regulated healthcare workflows
- Medical records or sensitive health data
- Marketplace/discovery layer

## Customer Experience
- Public booking page per business
- Guest booking supported by default
- Optional customer accounts for history and faster rebooking
- Confirmation, cancellation, and reschedule flow
- Czech and English UI from day one
- Timezone-aware booking and reminders

## Business Experience
Each business can manage:
- multiple locations
- multiple staff members
- services
- class sessions
- business hours and exceptions
- buffer times
- blackout periods
- reminder settings
- branding basics
- dashboard metrics

Owner dashboard should show:
- bookings this week
- cancellations
- utilization
- simple revenue forecast based on scheduled services

## Core Scheduling Rules
The booking engine must support:
- multi-tenant isolation
- staff and location assignment
- conflict detection
- buffer times
- timezone-safe date handling
- waitlists
- class capacity limits
- exception-based availability rules

Appointments and classes should share the same scheduling foundation where possible.

## Notifications
v1 reminder strategy:
- email is first-class
- SMS is optional and treated as a paid add-on
- SMS must be abstracted behind a provider interface
- Czech-first provider support is preferred, with room for generic fallback providers later

## Billing
Bookra uses Stripe for B2B SaaS subscription billing. (Migrated from Paddle; the Paddle integration was removed.)

Stripe scope in v1:
- tenant subscription plans
- plan upgrades/downgrades
- add-ons such as SMS or expanded limits
- webhook-based subscription state sync
- customer self-serve billing portal

Stripe is not used for end-customer booking checkout in v1.

## Remote-First Architecture
Bookra follows the `tdvorak-fullstack` profile with remote deployment overrides.

### Stack
- Frontend: SolidJS + Vite + TypeScript + Tailwind
- Backend: Go + Gin
- Database: Neon Postgres + goose (handwritten pgx repositories; sqlc removed)
- Auth: Neon Auth
- API contract: OpenAPI as source of truth
- Frontend deployment: Vercel
- Backend deployment: Railway
- Local development: direct app processes against remote services

### Structure
- modular monolith first
- monorepo layout
- generated TypeScript API client from OpenAPI
- strong tenant boundaries
- background jobs for reminders and waitlist handling
- no Docker Compose and no self-hosted infra path in v1

Suggested layout:
- `/apps/frontend`
- `/apps/backend`
- `/packages/api-client`
- `/packages/shared-types`

## Auth And Identity
- Neon Auth handles sign-up, sign-in, sessions, and browser auth state
- frontend owns browser auth flows
- Go backend verifies Neon Auth JWTs through JWKS
- backend treats Neon `sub` as the authenticated principal
- backend now syncs `neon_subject` into app-side `users` records on authenticated requests
- JWT usage is isolated to frontend-to-backend API calls across domains
- Neon-specific auth code must stay behind replaceable adapters because Neon Auth is beta

## Database And Environments
- Neon is the only database platform
- pooled connections for application traffic
- direct connections for migrations and admin tasks
- staging and production only in v1
- no per-PR backend preview environments in v1

## Main Domain Model
Key entities:
- tenants
- tenant users
- customer accounts
- locations
- staff
- services
- class templates
- class sessions
- availability rules
- availability exceptions
- bookings
- waitlist entries
- reminder jobs
- subscription accounts
- subscription events

## v1 Delivery Phases
### Phase 1
- monorepo setup
- Neon Auth integration shell
- tenant foundation
- locations, staff, services
- i18n foundation
- OpenAPI baseline
- status: completed

### Phase 2
- appointment booking flow
- availability rules
- conflict detection
- cancellation and rescheduling
- timezone-safe scheduling
- status: in progress
- current implementation:
  - public availability endpoint returns generated appointment and class slots
  - public booking creation validates tenant existence, timestamps, conflicts, and class capacity
  - frontend public route can trigger booking creation from live slots
  - repository pattern supports Neon-backed persistence with memory fallback

### Phase 3
- class sessions
- capacity limits
- waitlists
- email reminders
- dashboard metrics
- status: materially implemented
- current implementation:
  - class sessions appear in public availability
  - class capacity and waitlist status are enforced at booking time
  - dashboard metrics endpoint is repository-backed but still minimal in scope
  - booking creation now schedules reminder jobs
  - due reminder jobs can now be dispatched through the notifications service
  - delivery logging now exists for reminder execution

### Phase 4
- Stripe subscriptions
- SMS add-on support
- plan enforcement
- hardening, logging, and operational tooling
- status: in progress
- current implementation:
  - billing snapshot persistence added
  - Stripe checkout route added (Checkout Sessions)
  - Stripe webhook route added with signature verification
  - Stripe portal route added (customer portal sessions)
  - subscription refresh route added
  - entitlement mapping is now available to the frontend
  - API edge now includes security headers and public route rate limiting
  - remote job-runner endpoint added for reminder execution
  - goose commands are wired into repeatable npm scripts

## Current Implementation Notes
- Backend is no longer static-demo-only for booking flows.
- The repository layer supports:
  - Neon-backed pgx access when `BOOKRA_DATABASE_URL` is configured
  - deterministic in-memory fallback when Neon is not configured
- OpenAPI remains the frontend/backend contract source.
- Frontend public booking flow is now interactive, not just presentational.
- Route structure is now explicit:
  - `/` is the primary marketing landing page
  - `/dashboard` is the main application entry
  - `/book/:tenantSlug` stays public and customer-facing
- Neon Auth remains intentionally isolated behind adapters because the managed product is still beta.
- Billing now follows a backend-owned snapshot model rather than trusting incremental webhook payloads.
- `apps/auth-service` is now retired from active runtime and docs.
- Reminder delivery now has a working runtime path instead of just a queued schema.
- goose migration execution is runnable through workspace scripts.
- Protected backend requests now perform automatic app-side identity sync before tenant membership resolution.
- `/dashboard` now includes first-run onboarding instead of only a passive empty state for unassigned authenticated users.
- Catalog management now covers services and staff end-to-end; staff creation enforces `MaxStaff` entitlements and staff location assignment validates tenant ownership.
- Dashboard summary computes `setupCompletion` from real configured state (brand, location, service, staff, availability rules) rather than a static value.
- Public booking flow offers real service and staff selection via a stepped picker backed by `GET /v1/public/tenants/{slug}/catalog` and filtered availability (`serviceId`, `staffId`, `date`).
- Appointment creation validates that requested times fit inside availability rules, skip blocked days, and reference tenant-owned staff and locations.

## Current Gaps
- Neon Auth token extraction is wired structurally, but still needs live browser validation against a real Neon Auth environment.
- Tenant membership bootstrap now syncs identities structurally, but staging still needs seeded membership records and onboarding flows for first-time tenants.
- Post-onboarding CRUD now covers services, staff, locations, blocked days, working hours, and customers; class/session template management and per-staff availability rules still have no management UI.
- Stripe lifecycle sync is implemented; still needs live environment validation against real products, price IDs, and webhook signatures.
- Real email/SMS provider integrations are not implemented yet; current delivery providers are safe noops.
- The internal reminder dispatch route exists, but Railway scheduling and secret rotation still need production setup.

## Next Build Targets
- replace preview-mode dashboard hydration with fully validated Neon Auth JWT flow
- sync Neon Auth identities into tenant membership records and onboarding bootstrap
- validate Stripe checkout/webhooks/portal and reminder dispatch against live staging infrastructure
- replace noop notification providers with the first production email transport and a gated SMS transport
- add management UI for class/session templates and per-staff availability rules so service duration, capacity, and staff schedules are editable after onboarding

## Product Principles
- calm, premium, structured UX
- production-grade architecture
- no generic SaaS clutter
- deterministic scheduling behavior
- minimal operational complexity in v1
- build for maintainability, not feature sprawl

## Success Criteria For v1
Bookra is successful when a small business can:
- create its business profile
- configure staff, locations, and services
- publish a booking page
- accept bookings without double-booking
- send reminders reliably
- manage cancellations and waitlists
- view simple business health metrics
- subscribe to a paid plan through Stripe

## Final Positioning
Bookra is not an ERP, not a medical system, and not a marketplace.

It is a focused booking operating layer for small local service businesses that need:
- simple setup
- reliable scheduling
- clear reminders
- lightweight reporting
- clean SaaS billing