baya-monorepo/archive/post-phase/refinement/refinement-phase-0-bring-up.md

# Refinement Phase 0 — Local end-to-end bring-up & the integration seam

> **Mission:** make the client and the server actually talk to each other, once, on one machine, in a
> repeatable way — and prove it with one real authenticated round-trip. Today the two projects each run,
> but nothing wires them together: the browser can't call the API (no CORS), the API only starts against a
> remote database, and the frontend calls almost nothing real. This phase removes the three hard
> integration blockers and ends with a logged-in session backed by the real backend.
>
> **Track:** integration (both projects) · **Depends on:** nothing · **Unlocks:** every other refinement phase
> **Before you start, read [../../phases/_shared/agent-operating-rules.md](../../phases/_shared/agent-operating-rules.md).**

## 1. Context — where this sits

The 16-phase backend chain (b0–b15) and the 16-phase frontend chain (f0–f15) are both **complete against
their own specs**. But they were built in **parallel, decoupled** lanes that only ever met through the
`dev/contracts/` documents — they were **never run against each other**. As a result the app "runs" but is
not integrated:

- The frontend is **mock-primary**: 21 of its 22 service domains default to an in-browser mock
  (`USE_*_MOCK = true`), so a fresh `npm run dev` calls the backend for **auth only**. Everything you see —
  the customer home, search results, bookings — is fake in-memory data.
- The backend has **no CORS**, so even the calls the frontend *does* make (auth) would be blocked by the
  browser the moment the two run on different origins.
- The backend only starts against a **committed remote SQL Server** (see the security phase) — there is no
  local-database story, so a developer can't stand it up cleanly.

This phase is the foundation: it makes "run both and watch a real request succeed" a 5-minute, documented
procedure. It does **not** flip the frontend mocks (that's [Refinement Phase 4](refinement-phase-4-frontend-de-mock.md))
or build any missing endpoints (that's [Refinement Phase 3](refinement-phase-3-contract-batch.md)) — it
only removes the plumbing blockers and proves the seam works with the one domain that's already real: auth.

**What already exists (do not rebuild):**
- Real, wired phone-OTP auth on both sides — client `services/auth` (`USE_AUTH_MOCK = false`) ↔ server
  `AuthController`/`MeController` (`/api/v1/auth/*`, `/api/v1/me`).
- The client fetch layer (`client/src/lib/api/client.ts`) already reads `NEXT_PUBLIC_API_URL`, attaches the
  bearer, unwraps the `ApiResult` envelope, and does silent 401 refresh. It is correct — it just has nothing
  to talk to.
- On boot the server applies all 17 EF migrations and seeds roles + an admin user + a sandbox gateway
  (`Program.cs:99-104`). Migrations are **current**, not behind.

## 2. Required reading (do this first)

- **This directory's [README.md](README.md)** — the full problem inventory and how the 10 refinement phases
  fit together. Read it before anything.
- `server/src/API/Baya.Web.Api/Program.cs` — the startup pipeline (note: **no `UseCors`**).
- `server/src/API/Baya.Web.Api/appsettings.json` / `appsettings.Development.json` — the connection strings
  (identical; both point at the remote `87.107.152.16`).
- `server/src/API/Baya.Web.Api/Properties/launchSettings.json` — the API binds `https://localhost:5002` only.
- `client/src/lib/api/client.ts`, `client/src/config.ts`, `client/.env.development` — the client's API base
  URL wiring (`NEXT_PUBLIC_API_URL = https://localhost:5002`).
- `server/src/Infrastructure/Baya.Infrastructure.CrossCutting/Seams/LoggingSmsSender.cs` — OTP delivery is a
  **log statement**; the code you need to log in is printed to the server console, not sent by SMS.
- Root [CLAUDE.md](../../../CLAUDE.md) working agreement #6 (never commit secrets) — the local-DB change here
  must not add a new committed secret.

## 3. Scope — build this

### 3.1 CORS on the server (the #1 blocker)

There is **no CORS anywhere** in `server/` (verified: zero matches for `AddCors`/`UseCors`). A browser at
`http://localhost:3000` calling `https://localhost:5002` is blocked by the same-origin policy before the
request even reaches a controller.

- Add a CORS policy via an extension method (per the server's "expose it as an extension method, call it from
  `Program.cs`" rule — never inline). Suggested home:
  `Baya.WebFramework/ServiceConfiguration/CorsServiceExtension.cs` with `AddCorsPolicies(configuration)`.
- Read the allowed origins from configuration (`Cors:AllowedOrigins` string array), defaulting to
  `http://localhost:3000` in Development. **Do not** use `AllowAnyOrigin()` together with credentials.
- The client sends the token as a **bearer header** (not a cookie) on cross-origin calls, so
  `AllowCredentials()` is not strictly required — but allow the `Authorization`, `Content-Type`,
  `Accept-Language`, and `Idempotency-Key` headers (the client sets all four) and the methods the API uses.
- Register `app.UseCors(...)` in the pipeline **after `UseRouting()` and before `UseRateLimiter()`/
  `UseAuthentication()`** so a pre-flight `OPTIONS` is answered before auth/limits run.
- Keep it config-driven so a deployed environment lists its real web origin(s) and Development stays permissive
  to localhost only.

### 3.2 A local database story (so the API can start without the remote server)

Today both appsettings files hardcode the remote `87.107.152.16` SQL Server. A developer with no access to
that host cannot boot the API at all.

- Provide a **local** SQL Server for development. Recommended: a `server/docker-compose.yml` with
  `mcr.microsoft.com/mssql/server:2022-latest` (Developer edition, a dev-only `SA_PASSWORD`) exposing `1433`.
- Point the **Development** connection string at that local instance **via a non-committed mechanism** —
  `dotnet user-secrets` (the server project already supports it) or environment variables — and replace the
  committed remote string in `appsettings*.json` with a placeholder. (The full credential rotation is
  [Refinement Phase 5](refinement-phase-5-security-hygiene.md); here we only need a working, secret-free local
  default so the app boots.)
- Document the one-time HTTPS dev-cert trust: `dotnet dev-certs https --trust` — without it the browser (and
  `fetch`) rejects `https://localhost:5002` and every call fails with an opaque network error.
- On boot the server already runs `MigrateAsync()` + seeders, so pointing at an empty local DB is enough — it
  self-migrates and self-seeds roles/admin/gateway on first run. (Rich demo data is
  [Refinement Phase 1](refinement-phase-1-database-and-seed.md).)

### 3.3 A Development-only way to complete OTP login without an SMS gateway

OTP delivery is `LoggingSmsSender` — it **logs** the code (`server/.../Seams/LoggingSmsSender.cs`) instead of
sending it. A tester can already read the 6-digit code from the server console, but make this explicit and
frictionless:

- Document the "read the OTP from the server console" procedure in the client and server run docs.
- Optionally (Development/Testing-gated only) return the code in the `request_otp` response **or** expose a
  tiny `GET /api/v1/dev/last_otp/{phone}` behind an `IsDevelopment()` guard, so an automated/e2e flow can
  complete login. **This must be impossible to enable outside Development** and is superseded by the real SMS
  gateway in [Refinement Phase 8](refinement-phase-8-external-rails.md). Do not weaken the `otp` rate-limit or
  the per-phone resend window.

### 3.4 Client env & run docs

- Confirm `client/.env.development` (auto-loaded by `npm run dev`) has `NEXT_PUBLIC_API_URL =
  https://localhost:5002`. It already does — verify it matches the server's actual bound URL. If a developer
  runs the API on a different port/scheme, they set a `client/.env.local` override.
- Add a top-level **"Run the whole app locally"** section (root `README.md` or a new
  `dev/post-phase/refinement/RUNBOOK.md`) that ties the two `npm`/`dotnet` commands, the cert trust, the local
  DB, and the OTP-from-logs step into one copy-pasteable procedure.

**(DEFERRED here, done later):** flipping any `USE_*_MOCK` flag (Phase 4), building any missing endpoint
(Phase 3), rotating the leaked credentials (Phase 5), a reverse proxy / production CORS origins (Phase 5/9).

## 4. Mocks & seams in this phase

No new seams. This phase uses the existing `LoggingSmsSender` (OTP in logs) as the interim OTP channel and
touches no business logic. The only "mock" decision is the optional Development-only OTP echo (3.3), which is
a dev affordance, not a seam.

## 5. Critical rules you must not get wrong

- **CORS middleware order matters.** `UseCors` must sit after `UseRouting` and before the rate limiter / auth,
  or pre-flight `OPTIONS` requests get rejected (429/401) before the browser ever sends the real request.
- **Do not introduce a new committed secret.** The local DB password and connection string live in
  user-secrets/env/compose, never in a committed `appsettings*.json`. Replacing the remote string with a
  placeholder is in-scope; committing a new one is not.
- **The Development OTP shortcut is Development-only.** Gate it on `app.Environment.IsDevelopment()` and never
  log/return the code in any other environment. It is a bridge until real SMS (Phase 8).
- **Change nothing about the money path, auth crypto, or the envelope shape.** This is plumbing only.

## 6. Definition of Done

On top of the shared [definition-of-done.md](../../phases/_shared/definition-of-done.md):

- [ ] `server/`: CORS policy added (config-driven, localhost:3000 in Dev), registered in the correct pipeline
      position; `dotnet build Baya.sln` clean, `dotnet test Baya.sln` green.
- [ ] A developer with **no access to the remote server** can boot the API against a local SQL Server using
      only documented steps (compose/user-secrets), and the committed appsettings no longer carry a working
      remote credential as the default.
- [ ] `dotnet dev-certs https --trust` and the OTP-from-logs step are documented in the runbook.
- [ ] `client/`: `npm run check` green; the client points at the running API; no mock flags changed.
- [ ] The end-to-end proof in §7 passes.

## 7. How to test (what a human can verify after this phase)

1. `docker compose up` (or start local SQL Server) → set the Dev connection string via user-secrets.
2. `cd server && dotnet run --project src/API/Baya.Web.Api/Baya.Web.Api.csproj` → API boots, applies
   migrations, seeds, listens on `https://localhost:5002/swagger`.
3. `cd client && npm run dev` → `http://localhost:3000`.
4. Open `http://localhost:3000/fa/login`, enter a phone number, request the OTP.
5. **Read the 6-digit code from the server console** (the `LoggingSmsSender` line), enter it, submit.
6. **Expected:** you land on the customer home; the browser **Network tab shows real calls** to
   `https://localhost:5002/api/v1/auth/request_otp`, `/auth/verify_otp`, and `/api/v1/me` all returning
   `200` with the `ApiResult` envelope — **and no CORS error in the console**. This is the first real
   authenticated round-trip between the two projects.
7. Negative check: temporarily remove the CORS registration and confirm the same flow now fails with a CORS
   error in the console — proving the fix is what unblocked it.

## 8. Hand off & document (close the phase)

- Update `server/CLAUDE.md` "Startup wiring" to list the new CORS extension in the pipeline order.
- Write/append the local-run runbook (§3.4).
- Report per the operating rules: what was wired, the exact local-run procedure, and confirm auth is the only
  real domain until Phase 4. Save a memory note on the CORS + local-DB + OTP-in-logs bring-up so the next
  agent doesn't rediscover the blockers.