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 session endpoint added
  - Stripe webhook endpoint added with signature verification and event filtering
  - billing snapshot refresh 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
  - real post-onboarding entity management screens are still missing
- `[next]` Milestone 8: Catalog management, live staging validation, and operational hardening

## 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.

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

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 + sqlc + goose
- 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
  - Stripe webhook route added
  - 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
  - sqlc and goose commands are now 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.
- Reminder delivery now has a working runtime path instead of just a queued schema.
- sqlc generation and goose migration execution are now 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.

## 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.
- First-time onboarding exists, but there are still no CRUD screens for locations, staff, services, or schedules after workspace creation.
- Stripe lifecycle sync is implemented structurally, but 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 and reminder dispatch against live staging infrastructure
- replace noop notification providers with the first production email transport and a gated SMS transport
- add real app management screens for services, staff, locations, and availability 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