Source document · API/README.md

SB Relaxing Club API

The API repository will contain the Go backend for SB Relaxing Club. It is the authority for identity, authorization, marketplace data, orders, payments, chat, media, community features, notifications, reporting, and audit history.

Read first

Planned architecture

The backend starts as one modular Go application with feature modules under internal/app/ and technical adapters under internal/platform/.

cmd/api             HTTP and WebSocket process
cmd/worker          outbox, notification, and media jobs
internal/app        auth, orders, payments, chat, and other product modules
internal/platform   database, HTTP, queue, storage, configuration, observability
migrations          PostgreSQL migrations
openapi             versioned public HTTP contract

See the required repository structure before scaffolding.

API contract rules

• Routes are versioned under /api/v1.
• Every normal JSON response uses the shared success/error envelope.
• HTTP status and stable error.code drive client behavior.
• Money is integer minor units plus ISO currency.
• Times are UTC RFC3339 unless a local date/time explicitly includes an IANA timezone.
• Order and payment states are separate.
• State-changing retry-prone requests support idempotency.
• API DTOs, domain types, and database rows are separate.

Run the API

export DATABASE_URL='postgres://user:password@localhost:5432/sb_relaxing_club?sslmode=disable'
go run ./cmd/migrate
go run ./cmd/api

The server listens on http://localhost:8080 by default. Try:

curl http://localhost:8080/health
curl http://localhost:8080/api/v1

Implementation status

Core Go packages pass unit tests and the HTTP router has endpoint-presence and authentication-flow coverage. The Android app now consumes the service catalog endpoint.

Staging/production mode requires PostgreSQL, a 32-byte token secret, MailAfrica API key and sender configuration (or SMTP credentials), HTTPS S3-compatible storage, and an explicit listing subscription price/currency/duration. PostgreSQL-backed adapters are selected for auth, catalog, orders, payments, notifications, provider dashboard, chat, media metadata, community, lifestyle, reporting, and admin. /ready checks PostgreSQL in staging and production. GET /api/v1/listings searches only active, approved, currently subscribed listings and supports text/category filtering plus offset pagination. Provider owners create draft listings and menu items; they can request a subscription payment through POST /api/v1/listings/{id}/subscription-payments. The server snapshots its configured plan price, and admin confirmation extends the subscription transactionally. Provider approval publishes a paid listing. Order creation accepts menu_item_id and quantity; provider, listing, currency, and total are derived from an active, approved, subscribed catalog listing, then persisted with an item and price snapshot. Customers and listing owners can read only their own orders through GET /api/v1/orders and GET /api/v1/orders/{id}. A customer can create an order payment through POST /api/v1/orders/{id}/payments; the payment amount/currency are copied from the order, and submission/confirmation update payment and order states transactionally. Push delivery, subscription renewal reminders/suspension automation, Stripe payment intents, and verified Stripe webhook processing still need implementation.

Email/password sign-in sends a short-lived, single-use OTP and issues session tokens only through POST /api/v1/auth/login/verify; registration and password recovery also use email OTPs. Versioned order transitions are available at POST /api/v1/orders/{id}/transition; authorization derives from customer ownership or provider profile ownership, and completion commits the order, sale snapshot, audit event, and outbox event together. Providers can create off-platform sales at POST /api/v1/providers/me/sales. Meeting participation supports join/leave and host-only end routes. Admin endpoints cover operational totals, searchable users/providers/listings/orders/payments, account roles and status, provider approval, listing moderation, payment confirmation/rejection, order transitions, community moderation, announcements, audit history, and service-scoped accountant reporting. Admin accountants receive explicitly assigned services through the admin service-assignment routes. Google OAuth exchange, guest booking recovery, video and livestream APIs, meeting passcodes/signaling/media transport, and complete catalog/content management remain outstanding against the SRS.

The companion Next.js documentation application lives in the workspace’s ../docs/ directory and is deployed at the root of its own Vercel domain. The Go API remains on its API host under /api/v1. Local reference media is ignored by Git and is not required to build the API.

The companion Next.js admin application lives in ../admin/ and runs on port 3001 by default. Set API_BASE_URL to the Go API origin (defaults to http://localhost:8080) and run npm install && npm run dev from that directory. Admin sign-in uses the API email OTP flow and allows only admin and accountant roles. Admin collection routes and the operational summary are documented in openapi/openapi.yaml.

Documentation commands can be run from this repository:

make docs          # synchronize source Markdown into the docs app
make docs-check    # fail when synchronized copies are stale
make docs-dev      # run the documentation site at /docs

The GitHub Actions workflow runs PostgreSQL migrations, the complete Go test suite, build, and go vet. To run the database-backed suite locally, set DATABASE_URL, run go run ./cmd/migrate, then run go test -count=1 ./....

Documentation requirement for each change

When implementing or changing a feature:

1. Update OpenAPI for endpoint/schema/error changes.
2. Update the API SRS for new behavior, state transitions, security rules, or architecture.
3. Update CONTEXT.md when a domain term or relationship changes.
4. Update docs/ARCHITECTURE.md when module ownership or infrastructure changes.
5. Update this README for setup, commands, configuration, or repository layout changes.
6. Add a concise entry to docs/CHANGELOG.md.
7. Run npm run docs:sync and npm run docs:check from the workspace’s ../docs/ directory.