first commit

project.md

@@ -0,0 +1,321 @@
+# 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