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