Source document · API/docs/WORKFLOWS.md

End-to-end API workflows

The API is a modular monolith. Each flow crosses several HTTP operations, but application rules and PostgreSQL transactions remain server-side. The diagrams below show the implemented request sequence and the point where responsibility moves between modules.

Provider publication

1. Register and verify the account, then sign in.
2. Create the provider profile. It starts pending approval.
3. Create an owned listing and menu items. These remain drafts until the provider is approved and its subscription is active.
4. Create a subscription payment. The server takes amount, currency, and duration from its configured plan; clients cannot set the plan price.
5. The provider submits a manual payment claim with its method and version. An administrator confirms subscription payments; an administrator or the owning provider can confirm order payments. Provider approval and payment confirmation are separately audited operations.
6. The public listing search returns listings only when active, approved, and currently subscribed.

Booking and manual payment

Order creation accepts menu_item_id, quantity, optional notes, and optional RFC3339 schedule_at. Guests also provide email and phone; authenticated members use their bearer identity instead. Use a stable Idempotency-Key for retries of the same logical create request. Reusing a key with different content returns a conflict.

Create the payment with POST /api/v1/orders/{id}/payments and {"method":"wechat_qr"} or {"method":"alipay_qr"}. The response contains the server-owned amount and configured instructions. POST /api/v1/payments/{id}/submit records that the customer claims to have paid; it is not proof of payment. Confirmation is a separate authorized action. Current client flow is manual; automatic Stripe intent/webhook processing is not available in the production flow yet.

Account and token rotation

See authentication and access control for endpoint details, role boundaries, and secure token storage.

Upload and attach a Moment image

1. Call POST /api/v1/media/upload with purpose, MIME type, and byte size. The request validates the allowed purpose/type and size.
2. The API returns a media asset ID and a short-lived signed object-storage URL.
3. Upload the bytes directly to the signed URL using the method and content type returned by the storage provider. Do not send the object-storage credentials to the app.
4. Include the returned media asset ID in media_asset_ids when calling POST /api/v1/community/moments.
5. Read an authorized asset through GET /api/v1/media/{id} to receive a temporary read URL. The API checks the asset’s visibility before signing it.

Moment creation supports text, up to five media asset IDs, or both. Community interactions include feed, counters, likes, views, comments, reports, and user block/unblock operations.

Chat

1. Resolve an active listing contact with GET /api/v1/listings/{id}/contact after signing in.
2. Create or reuse a conversation with POST /api/v1/chat/conversations using the other user ID.
3. List conversations with GET /api/v1/chat/conversations.
4. Fetch or send messages at /api/v1/chat/conversations/{id}/messages.
5. Acknowledge read state with POST /api/v1/chat/conversations/{id}/read.
6. For realtime delivery, open /api/v1/chat/conversations/{id}/realtime as an authenticated WebSocket. The server validates the Origin and conversation membership.

Conversation and message reads are scoped to a participant. The API persists messages and read state in PostgreSQL; the WebSocket is a delivery channel, not a replacement for the persisted history.

Operational notifications and reporting

Order-created notifications are written to the outbox in the same transaction as the order. The worker delivers in-app notifications to the customer and provider with at-least-once retry behavior. Android push delivery is optional and requires Firebase credentials. GET /api/v1/notifications reads the inbox and POST /api/v1/notifications/{id}/read acknowledges an item.

Administrators and accountants use GET /api/v1/reports/summary for a scoped 30-day summary. Administrators also have overview, collection search/status changes, provider approval, payment rejection, community moderation, announcements, audit, accountant service assignment, and CSV export endpoints. The API applies the role and accountant service scope rather than trusting client filters.