Bookra/apps/backend

Bookra Backend

Go + Gin API for Bookra, designed for Railway deployment with Neon Auth, Neon Postgres, and Paddle billing.

Commands

go run ./cmd/api
go build ./...
npm run db:generate
npm run db:migrate:status
npm run db:migrate:up

Environment

• BOOKRA_FRONTEND_URL allowed browser origin
• BOOKRA_DATABASE_URL Neon pooled connection
• BOOKRA_DATABASE_DIRECT_URL Neon direct connection for migrations/admin tasks
• BOOKRA_NEON_AUTH_URL Neon Auth base URL used for JWKS verification
• BOOKRA_AUTH_JWT_SECRET optional local JWT fallback when not using Neon Auth
• BOOKRA_JOB_RUNNER_KEY shared secret for remote reminder dispatch calls
• BOOKRA_EMAIL_FROM sender identity for email reminders
• BOOKRA_PADDLE_ENV billing environment: sandbox or live
• BOOKRA_PADDLE_API_KEY Paddle API key
• BOOKRA_PADDLE_WEBHOOK_SECRET Paddle notification destination secret
• BOOKRA_PADDLE_{STARTER,PRO,BUSINESS}_{CZK,USD}_PRICE_ID Paddle price IDs
• BOOKRA_UMAMI_API_URL and BOOKRA_UMAMI_API_KEY optional analytics integration

Notes

• Auth verification is isolated in internal/auth.
• OpenAPI lives in openapi/bookra.openapi.yaml.
• SQL migrations live in migrations/.
• sqlc.yaml is wired through npm run db:generate.
• Goose migrations are wired through npm run db:migrate:* and use the Neon direct connection URL.
• Reminder dispatch now runs through POST /v1/internal/jobs/reminders/dispatch with X-Bookra-Job-Key.

Production Auth

Bookra production auth should use Neon Auth directly:

• frontend uses VITE_NEON_AUTH_URL
• backend verifies Neon JWTs with BOOKRA_NEON_AUTH_URL
• auth-service may stay deployed for standalone auth/admin workflows, but backend billing and app APIs do not depend on it

Trusted redirect domains in Neon Auth should include your frontend origin such as https://bookra.eu, plus local dev origins when needed.

Paddle Setup

Get these values from Paddle dashboard:

• BOOKRA_PADDLE_ENV: sandbox for testing, live for production
• BOOKRA_PADDLE_API_KEY: Developer tools -> Authentication
• BOOKRA_PADDLE_WEBHOOK_SECRET: Notification settings -> destination secret key
• BOOKRA_PADDLE_*_PRICE_ID: Catalog -> each SaaS plan recurring price ID

Create one recurring price per plan/currency you support:

• starter czk
• starter usd
• pro czk
• pro usd
• business czk
• business usd

Set your webhook destination to:

POST /v1/webhooks/paddle
POST /api/paddle_webhook

Use Paddle webhook simulator for event testing.