hamid
153 lines
8.6 KiB
Markdown
153 lines
8.6 KiB
Markdown
# Integration — the client↔server seam
|
|
|
|
The two projects have **no shared build**. Everything that crosses between them is described here, as one
|
|
thing. This page is the whole seam; the four files below are the detail.
|
|
|
|
> Last verified: 2026-07-30 against commit `d3ec723`, `swagger.v1.json` (2026-07-29, 178 paths / 186
|
|
> operations) and the code in `client/src/lib/api/`, `client/src/services/*/`, `server/src/API/`.
|
|
|
|
| File | Covers |
|
|
| --- | --- |
|
|
| [api-contract.md](api-contract.md) | Envelope, casing, pagination, errors, idempotency, auth, money, rate limits |
|
|
| [domains/](domains/index.md) | 22 files, one per client `services/` domain — every endpoint, verdicted against the live swagger |
|
|
| [openapi/](openapi/README.md) | The machine contract + how to regenerate it |
|
|
| [config-matrix.md](config-matrix.md) | Every env var and appsettings key: client, server, docker, the bot |
|
|
| [topology.md](topology.md) | The runtime dependency graph — 3 containers, Caddy, remote SQL, the OTP relay |
|
|
|
|
---
|
|
|
|
## Transport
|
|
|
|
HTTP/JSON. The client reads one base URL — `NEXT_PUBLIC_API_URL` — and prefixes every path with
|
|
`/api/v1/`. Locally that is `http://localhost:5002` (**plain HTTP**; `launchSettings.json` binds no TLS);
|
|
deployed it is `https://api.balinyaar.ir`, which Caddy terminates and forwards to `balinyaar-api:8080`.
|
|
|
|
**gRPC exists and the client does not use it.** `Baya.Web.Plugins.Grpc` serves exactly one service (User)
|
|
over HTTP/2 on the same port. Nothing in `client/` speaks it. Treat it as an internal affordance.
|
|
|
|
**Two OpenAPI documents are served, `v1` and `v1.1`.** All 55 controllers declare `[ApiVersion("1")]`, and
|
|
`ApiVersionDocumentProcessor` keeps only paths whose URL contains the document's version segment — so
|
|
**`v1.1` is served but contains zero paths.** `v1` is the contract.
|
|
|
|
## The envelope
|
|
|
|
Every response — success *and* failure — is `ApiResult`. The payload is always under `data`.
|
|
|
|
```json
|
|
{ "isSuccess": true, "statusCode": 200, "message": "Success",
|
|
"requestId": "0af7651916cd43dd8448eb211c80319c", "code": null, "data": { } }
|
|
```
|
|
|
|
`requestId` is the **W3C trace id** of the request (`Activity.Current.TraceId`), the same id
|
|
OpenTelemetry traces on — so a support ticket maps 1:1 to a trace. `code` is an optional stable
|
|
machine-readable error code (`otp_locked`, …), omitted from the wire when null.
|
|
|
|
The client never unwraps centrally: `clientFetch`/`serverFetch` return the **raw envelope**, and each
|
|
service calls `unwrap()` from [`client/src/lib/api/types.ts`](../../client/src/lib/api/types.ts).
|
|
|
|
## Casing — camelCase bodies, snake_case URLs
|
|
|
|
Verified mechanically against the live swagger: of **427 distinct property names, 0 contain an underscore
|
|
and 0 are PascalCase.** JSON bodies are camelCase. URL *segments* are snake_case, produced by the server's
|
|
`SnakeCaseParameterTransformer` from `[controller]`/`[action]` tokens (`SetPrimary` → `/set_primary`).
|
|
|
|
Three routes break the snake_case rule with hardcoded hyphens — `admin/partner-centers`, `admin/tickets`,
|
|
`admin/reviews` — see [domains/index.md](domains/index.md#route-shape-exceptions).
|
|
|
|
## Pagination
|
|
|
|
`{ items, total, page, pageSize }` (`total`/`page`/`pageSize` are int32). 29 operations are paginated.
|
|
The **declared** query-param names are not uniform — 25 declare `Page`/`PageSize`, 3 declare
|
|
`page`/`pageSize`, and `GET /search/nurses` declares `page`/`page_size`. Model binding is
|
|
case-insensitive so the first two are interchangeable; `page_size` is a *different name* and is not.
|
|
Full table in [api-contract.md](api-contract.md#pagination).
|
|
|
|
## Errors
|
|
|
|
`200` · `400` validation (field errors under `data`) · `401` unauthenticated · `403` forbidden ·
|
|
`404` not found (**also returned for a tenancy mismatch**, deliberately, so a 403 never confirms a row
|
|
exists) · `409` state-machine/idempotency conflict · `422` · `424` · `429` rate-limited · `5xx`.
|
|
|
|
`clientFetch` behaviour: **401** → one silent refresh + retry, then clear cookies, toast, redirect to
|
|
login (no throw); **403** and **5xx** → toast + throw `ApiError`; **other 4xx** → throw without toasting
|
|
(the calling hook owns the message); **network failure** → toast + `ApiError(0)`.
|
|
|
|
## Auth
|
|
|
|
**Bearer header, not cookie auth.** The JWE access token is *stored* in a cookie the client reads itself
|
|
and *sent* as `Authorization: Bearer <token>`. The server's CORS policy therefore does **not** allow
|
|
credentials, and the client sends no `credentials: 'include'`.
|
|
|
|
The token is opaque to the client (signed + AES-encrypted). Role and identity come from `GET /api/v1/me`;
|
|
a multi-role user picks one with `POST /api/v1/me/select_role`. On a 401 the client runs one
|
|
single-flight silent refresh (`POST /api/v1/auth/refresh`) — the server rotates the pair and detects
|
|
reuse, so a replayed refresh token kills the session. `/auth/refresh`, `/auth/request_otp` and
|
|
`/auth/verify_otp` are excluded from the retry.
|
|
|
|
**20 of 186 operations are anonymous** — the OTP pair, catalog + geo reference reads, the public nurse
|
|
search/profile/reviews/trust-badge reads, `ping`, the three webhooks, and Development's
|
|
`GET /api/v1/dev/last_otp/{phone}`. Full list in [api-contract.md](api-contract.md#the-anonymous-surface).
|
|
|
|
## Idempotency
|
|
|
|
`Idempotency-Key` is a request header. The server reads it on exactly **two** endpoints:
|
|
|
|
| Endpoint | Key scope |
|
|
| --- | --- |
|
|
| `POST /api/v1/bookings/{bookingRequestId}/payments` | one key per payment *attempt*, reused across retries of that attempt |
|
|
| `POST /api/v1/checkout_bnpl/initiate` | same, per BNPL attempt |
|
|
|
|
The client also sends it on `admin_payouts` process/retry, where **the server does not read it** — see
|
|
[domains/payouts.md](domains/payouts.md). Webhooks do not use the header; they dedupe on the provider's
|
|
`external_event_id`. The header is allowed through CORS but is **not declared in swagger** (it is read
|
|
from `Request.Headers`, not bound as a parameter).
|
|
|
|
## Money
|
|
|
|
**IRR Rials, integer, no floats, anywhere.** On the wire the direction matters, and it is consistent:
|
|
|
|
- **Outbound (DTOs/results): a digit string.** All 68 money properties on read models are `type: string`.
|
|
Parse with the `@/utils` BigInt helpers — never `Number()`.
|
|
- **Inbound (commands): `integer/int64`.** All 3 money properties on command bodies.
|
|
|
|
Toman is display-only and is converted **only** inside a provider adapter at its boundary
|
|
(`ICurrencyNormalizer`, `Seams:Currency:TomanToIrrMultiplier`). `gross = commission + payout` always,
|
|
and VAT is on Balinyaar's commission only. See [docs/rules/server/money.md](../rules/server/money.md)
|
|
and [docs/rules/client/services.md](../rules/client/services.md).
|
|
|
|
## Enums
|
|
|
|
**Swagger declares no string enums** — 1 of 339 schemas has an `enum`, and it is the integer
|
|
`ApiResultStatusCode`. Every status/code field is a bare `string` on the wire. The vocabulary therefore
|
|
lives in the domain files here, cross-checked against the server's `Baya.Domain` code sets and the
|
|
client's string-literal unions. **All 18 shared vocabularies match on both sides** as of this stamp; the
|
|
one exception is noted in [domains/tickets.md](domains/tickets.md).
|
|
|
|
---
|
|
|
|
## What the server owes the client
|
|
|
|
1. The `ApiResult` envelope on every response, with `requestId` populated and `code` set on any failure
|
|
the client must branch on.
|
|
2. camelCase bodies; snake_case URL segments; `{ items, total, page, pageSize }` on every list.
|
|
3. `404`, never `403`, for a row the caller does not own.
|
|
4. Money as a digit string outbound; the three-amount split guaranteed server-side.
|
|
5. A masked address and only unencrypted `customerNotes` before a booking is confirmed; full care
|
|
instructions only after, only to the assigned nurse and admin.
|
|
6. `is_internal` filtered at the query layer — a non-staff caller can never read or set one.
|
|
7. Idempotent behaviour on the two keyed endpoints, and `409` (not `500`) on a converged replay.
|
|
8. Reachability: `/healthz/live`, `/healthz/ready`, and CORS origins that list the client's real origin.
|
|
|
|
## What the client owes the server
|
|
|
|
1. `Authorization: Bearer <token>` on every authenticated call — and nothing else for auth. No cookies
|
|
cross the wire.
|
|
2. `Accept-Language` (`fa` default) on every call, from the active locale segment.
|
|
3. `Content-Type: application/json` — **except** `FormData` bodies, where the browser sets the multipart
|
|
boundary itself.
|
|
4. One stable `Idempotency-Key` per payment/BNPL attempt; a new attempt gets a new key.
|
|
5. `page`/`pageSize` within the server's cap; never an unbounded list request.
|
|
6. IRR integers inbound; Toman conversion only at the UI boundary.
|
|
7. Exactly one silent refresh per 401, single-flighted, and never on the refresh/OTP endpoints.
|
|
8. No derived money. The client never computes commission, VAT, refund amounts or payout dates.
|