diff --git a/docs/decisions/0015-a-view-with-its-own-frame-gets-its-own-route.md b/docs/decisions/0015-a-view-with-its-own-frame-gets-its-own-route.md new file mode 100644 index 0000000..db0739a --- /dev/null +++ b/docs/decisions/0015-a-view-with-its-own-frame-gets-its-own-route.md @@ -0,0 +1,16 @@ +# 0015 A view with its own frame gets its own route + +Status: Proposed · Area: architecture · Date: 2026-10-06 · Decided by: agent + +## Context +The suspended screen (S6 1.11, 2.1, 3.1) and the creator's end of registration (R2-CompleteProfile 1.8, 3.3) show a different header or card width than the step they follow. The frame renders on the server and can't know a browser-only state, so a view swap inside the step kept the wrong header and card. + +## Decision +- When a login, registration or onboarding view needs a different frame than its step, serve it on its own route: `/auth/login/suspended`, `/onboarding/creator-profile/done`. The step sends the person there with `router.replace`. +- What the view needs and the server can't give stays in memory (the flow store); a reload without it falls back to the step's start, as other flow steps do (0013). A view that can read its data from the API (the end of registration) reads it, so it survives a reload. + +## Alternatives +- A client header that reads a store: rejected; the server frame and the skeleton would still differ from the view. + +## Consequences +- Each such view has its own page, loading skeleton and metadata in both apps. diff --git a/docs/decisions/0016-unfinished-creators-stay-on-step-5.md b/docs/decisions/0016-unfinished-creators-stay-on-step-5.md new file mode 100644 index 0000000..634046f --- /dev/null +++ b/docs/decisions/0016-unfinished-creators-stay-on-step-5.md @@ -0,0 +1,18 @@ +# 0016 Unfinished creators stay on step 5, from the session + +Status: Proposed · Area: architecture · Date: 2026-10-06 · Decided by: agent + +## Context +R2-CompleteProfile 4.2: a creator's channel, publishing and prices stay unavailable until step 5 is done, and the next login opens step 5 again. Before, only a fresh login knew, through its own profile read. + +## Decision +- The API's session answers (login, session, refresh, registration) carry `needsProfile`, and the auth store keeps it; `completeCreatorProfile`, and step 5 or its end finding the profile complete, clear it. +- `OnboardingGuard`, rendered by the layouts of the locked routes (`compose`, `dashboard/pricing`), sends such a creator to step 5 with the current page as `?redirect=`; `GuestGuard` does the same on the auth pages. Neither changes the server render. Every other page, such as the terms, stays open. +- Step 5 sends a creator whose profile is already complete on to `?redirect=`, else their channel. The channel itself stays hidden by the back end (unapproved creators answer 404). + +## Alternatives +- Read the profile in the browser after each session read: rejected; an extra serial request per page load, and a failed read let the creator in. +- Guard every page outside onboarding: rejected; it locked pages the design keeps open, such as the terms linked from step 5's support. + +## Consequences +- The trader service answers one more call per creator session read; a failed call counts as not done. The back end still enforces the lock on posting and tiers (0014). diff --git a/docs/decisions/0017-each-step-owns-its-loading-skeleton.md b/docs/decisions/0017-each-step-owns-its-loading-skeleton.md new file mode 100644 index 0000000..2a07132 --- /dev/null +++ b/docs/decisions/0017-each-step-owns-its-loading-skeleton.md @@ -0,0 +1,16 @@ +# 0017 Each step owns its loading skeleton + +Status: Proposed · Area: architecture · Date: 2026-10-06 · Decided by: agent + +## Context +A route group's `loading.tsx` showed one frame for every step under it, so navigating to a step with another header or card width moved the page when it arrived. Next.js also shows the loading of the first new segment, so a parent step's `loading.tsx` covers its nested steps. + +## Decision +- Every login, registration and onboarding route has its own `loading.tsx` with its page's frame and fallback skeleton; the route groups have none. +- A route whose page has nested steps puts its page and loading in a route group of its own: `login/(number)`, `register/(type)`, `creator-profile/(form)`. + +## Alternatives +- One loading per group: rejected; its frame matches only some steps. + +## Consequences +- Page and loading repeat the frame; change them together. diff --git a/docs/decisions/0018-browser-calls-the-api-through-a-next-rewrite.md b/docs/decisions/0018-browser-calls-the-api-through-a-next-rewrite.md new file mode 100644 index 0000000..70026d8 --- /dev/null +++ b/docs/decisions/0018-browser-calls-the-api-through-a-next-rewrite.md @@ -0,0 +1,21 @@ +# 0018 The browser calls the API through a Next.js rewrite + +Status: Accepted · Area: architecture · Date: 2026-10-06 · Decided by: user + +## Context +The browser called the gateway on its own origin with credentials, so every call was cross-origin: CORS preflights, a CORS allowlist to keep in step, and session cookies that belonged to the API host. + +## Decision +- The browser calls the API on the app's own origin (bull :7000, bear :7001) under `/api` (`API_PROXY_PATH`): `/api/v1/…` and `/api/files/…`. Each app's `next.config.ts` rewrites `/api/:path*` to `${apiInternalUrl()}/:path*`, the gateway's `API_INTERNAL_ORIGIN`. +- Media and avatar URLs from the API go through the same path (`toApiUrl`, market env `apiBaseUrl`), so private media gets the session cookie. +- The server render still calls the gateway directly at `API_INTERNAL_ORIGIN` and still sends no session cookies. +- The gateway scopes the refresh cookie to `/api/v1/auth` (`AUTH_COOKIE_PATH_PREFIX=/api`), and keeps the apps' origins in `CORS_ORIGINS` for its origin check. + +## Alternatives +- Direct cross-origin calls with CORS: the previous setup, replaced. +- A route handler proxy reading the origin at run time: not chosen; the rewrite is simpler. + +## Consequences +- No `NEXT_PUBLIC_API_ORIGIN`. `next build` fixes the rewrite's destination at build time, so each environment's build needs its own `API_INTERNAL_ORIGIN`; `SKIP_ENV_VALIDATION` can't skip it, and a build without it fails. +- API traffic, uploads included, passes through the Next.js server. Its proxy waits `API_PROXY_TIMEOUT_MS` (120 s, `experimental.proxyTimeout`) instead of Next.js's 30 s. +- The proxy adds only `X-Forwarded-Host` and passes the browser's `X-Forwarded-For` on as sent; Next.js can't see the client's address. The client IP must come from the edge in front of the apps (it sets `X-Forwarded-For`), with the gateway trusting that chain (back end: 02-architecture, 08-devops). Without such an edge, the forwarded IP is the client's own claim. diff --git a/docs/decisions/0019-every-toast-closes-by-itself.md b/docs/decisions/0019-every-toast-closes-by-itself.md new file mode 100644 index 0000000..34560d7 --- /dev/null +++ b/docs/decisions/0019-every-toast-closes-by-itself.md @@ -0,0 +1,17 @@ +# 0019 Every toast closes by itself + +Status: Accepted · Area: design · Date: 2026-10-06 · Decided by: user + +## Context +Action-error toasts stayed until dismissed (`duration: Infinity`), so one could follow the person to the next pages and never leave. The user asked for every toast to disappear after a delay. + +## Decision +- Every toast closes on its own: success and info after 4 seconds (6 with an action), errors after 8 seconds (10 with their «تلاش دوباره» or reload button). +- Island's `showToast` sets these defaults by tone; callers pass `duration` only for a reason they can name, never `Infinity`. +- Hovering or focusing a toast, or leaving the tab, pauses its clock (sonner 2 does this itself). + +## Alternatives +- Errors stay until dismissed: the skill's default; replaced at the user's request. + +## Consequences +- What an error asks the person to do must also show on the page (a field error, the form alert or the state), not only in the toast, as the form rules already require. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 6c763d4..a5f65ff 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -4,12 +4,14 @@ - 0002 Render every tag through island `Element`, flex layouts through `FlexBox`, grid layouts through `GridBox`; never native JSX tags or `flex`/`grid` classes, island included. - 0011 Serve Yekan Bakh FaNum (`font-sans`, all UI text) and Yekan Bakh (`font-latin`, شبا and bank codes only) from `public/fonts/` under fixed names declared in island `fonts.css`; no version, never hashed, never `next/font`; a changed font gets a new name. +- 0019 Close every toast by itself: success and info after 4 s (6 with an action), errors after 8 s (10 with an action); hovering or a hidden tab pauses it; never `duration: Infinity`. ## Architecture (ADR) - 0001 Share one platform, `platforms/market`, between `apps/bull` and `apps/bear`; tag all three `scope:market`. - 0012 Wrap each app's `next.config` in island's `withIconSprite` and `withFontCopy`; they write `symbol-defs.svg` and the fonts into `public/` unhashed, served immutable; link the sprite as `?v=`. - 0013 Render every `(auth)` page's steps only in the browser behind `GuestGuard`: the server sends the frame, a same-size skeleton and `noindex`; flow state stays in memory, never in the URL or storage. +- 0018 Call the API from the browser only on the app's own origin under `/api`, rewritten by `next.config.ts` to `API_INTERNAL_ORIGIN`; media URLs use the same path, and the server render calls the gateway directly. ## Proposed @@ -17,3 +19,6 @@ - 0005 design: Island holds Lumina's product components and status-to-tone map; they take every text as props (`children` or `labels`) and never import i18next or platform code. - 0006 architecture: Make every non-app project a pnpm workspace package `@lumina/` with subpath `exports`; third-party dependencies stay in the root package.json. - 0014 architecture: Serve registration step 5 under `(onboarding)` behind `AuthGuard`; a creator's profile autosaves as a server draft (`PATCH`) and completes only through `POST …/profile/complete`. +- 0015 architecture: Serve a login or onboarding view whose frame differs from its step on its own route (`/auth/login/suspended`, `/onboarding/creator-profile/done`); browser-only data stays in memory. +- 0016 architecture: Keep a creator who hasn't finished step 5 out of publishing and pricing through the session's `needsProfile`, with `OnboardingGuard` in those routes' layouts and `GuestGuard`. +- 0017 architecture: Give every auth and onboarding route its own `loading.tsx` matching its frame; an index route with nested steps sits in its own route group.