wealth/docs/decisions/README.md

64 lines
9.0 KiB
Markdown
Raw Normal View History

2026-10-04 18:03:42 +00:00
# Decisions
## Design (DDR)
2026-10-04 18:03:42 +00:00
- 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, focus or a hidden tab pauses it; callers never pass `duration: Infinity`.
- 0056 Set `maximum-scale=1` in bull's root viewport so iPhones never zoom into fields under 16px; bear keeps the default viewport.
2026-10-04 18:03:42 +00:00
## Architecture (ADR)
2026-10-04 18:03:42 +00:00
- 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=<ICON_SPRITE_VERSION>`.
- 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.
- 0026 Prerender the landing (`/`) with `force-static` and `revalidate = 600`; every other route keeps `force-dynamic` in its route group's layout, never the root's.
- 0027 Serve خانه at `/feed` and the landing at `/`; send a signed-in visitor of `/` to `homeRoute` in the browser with `LandingRedirect`, never in a proxy.
- 0051 Serve `/_next/static/` JS and CSS cache first in the service worker; `strategy` (default stale-while-revalidate) applies to fonts and the sprite only.
- 0052 Evict the service worker's least recently used entry first, with the key order kept in memory and older-half hits stored again.
- 0053 Ship bull and bear with the same worker options and `NEXT_PUBLIC_SERVICE_WORKER_ENABLED`; both serve the manifest from `platforms/market/src/app/manifest`.
- 0054 Set `htmlLimitedBots: /.*/` in both apps' `next.config.ts`, so every visitor gets metadata in `<head>`.
- 0055 Export static `metadata` from every layout and page; only the channel and post pages use `generateMetadata`, through the page's cached read.
- 0057 Back links to `parentHref` and traverses history only when that is the previous entry; `backToPrevious` pages (and pages without `parentHref`) accept any previous page.
- 0058 Opening notifications records "seen" and clears the bell; a row stays unread until tapped; creators filter one list by «همه · پیش‌بینی‌ها · مالی · حساب».
- 0059 Checkout and the channel save `?code=` into the per-creator checkout draft on arrival; checkout then strips it from the URL.
- 0060 Composers send a creator who can't publish to their own channel with the locked dialog; every publish carries a stable `Idempotency-Key`.
- 0061 Build the admin panel as `apps/wall-street-plaza` with `platforms/garden-roof`, tagged `scope:admin`; it calls only the back end's `admin-api`, through its own `/api` rewrite.
2026-10-04 18:03:42 +00:00
## Proposed
2026-10-04 18:03:42 +00:00
- 0003 design: Only semantic tokens, named as in the Lumina Design System, produce Tailwind utilities (`@theme inline`); primitives stay plain `:root` variables and Tailwind's defaults are removed.
- 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/<name>` 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.
- 0020 architecture: Server-rendered platform organisms take their text as `labels` built by the app's template from its server i18n; client organisms use `useTranslation`.
- 0021 architecture: A channel's feed and post page start from the server's read as query `initialData`, re-read in the browser for the creator or a subscriber, and update in place after mutations.
- 0022 architecture: The API enforces post rules (2000 characters, four JPG/PNG/WebP images of 5 MB, 15-minute edit window, approved creators only); the composer mirrors them in `POST_LIMITS`.
- 0023 architecture: On desktop «پست جدید», post edit and «پیش‌بینی جدید» are dialogs over the page through bear's `@modal` intercepts; slots are emptied by explicit null pages, never a catch-all, and a hard load gets the full page.
- 0025 architecture: The investor's داشبورد is a tabbed section, one route per tab in `dashboard/(investor)`, whose layout holds the top bar or heading and `DashboardTabs`; each tab has its own loading.
- 0028 design: Landing-only island tokens: `tablet` (720px, the landing's grids only), `hero` and `section` type, `container-page` and `image-shade`.
- 0029 architecture: End every payment on `/payment/result/[paymentId]`; the API's bank callback returns to `/payment/return`, which polls the payment until settled (30 s at most) and replaces itself.
- 0030 architecture: Keep the last checkout's period, invite code and bank payment in the persisted `session.checkout-draft` store from payment start until success, and restore them on the same creator's checkout.
- 0031 design: List renew and reactivate periods as island `TierOption` cards, as checkout does, instead of R3's chip grid.
- 0033 architecture: Keep the payment sent to the bank in the checkout draft and settle it through `POST /subscriptions/payments/:id/abandon` only on the page that came back from the bank (bfcache or a history load), triggered by the app shell and awaited by checkout's screen read.
- 0034 architecture: Serve the creator's داشبورد from `dashboard/(creator)` as `/dashboard/plans` (default), `/dashboard/predictions` and `/dashboard/finance`, and C7 at `/dashboard/pricing` in `(flow)`; the شبا form and ledger details open in place.
- 0035 design: Pick a promotion's Shamsi date and time with island `Select`s in a sheet or modal, not a drawn wheel.
- 0036 architecture: During the 7-day lock the save button reads «ذخیره تخفیف» and saves promotion changes; standing prices and period switches stay read-only.
- 0037 architecture: Open payout receipts from the API's session-authorized `/payouts/me/payouts/:id/receipt` through `/api`, not signed expiring URLs.
- 0039 design: Place toasts above whatever draws the bottom edge, declared by that part (nav 80, pinned footer 152, desktop 32, low in sheets).
- 0040 architecture: Render the connection bar under the sticky bars, inside their sticky box, never above or over content.
- 0041 architecture: Confirm sign-out, call `auth.logout`, then reload to the landing.
- 0042 architecture: When a session ends mid-use, show the session-ended state and keep drafts; only an explicit sign-out clears drafts and `session.*` keys.
- 0043 architecture: Freeze every network action offline with island `useOfflineFreeze`, showing the reason.
- 0045 architecture: The channel's server read carries the public follower count; the browser keeps it live and shows «مشترک فعال» only to the owner.
- 0046 architecture: Serve `/account/profile` in `(flow)` for both roles, switching investor form and creator profile edit in the browser.
- 0047 architecture: The pwa lib keeps the browser's install offer; offer install at `/account/install` and once on bull's خانه with a 30-day snooze; the manifest starts at `/feed`.
- 0049 design: A page error keeps the page's own bar, derived from the path; route groups without a frame pass `standalone`.
- 0050 design: A post being read shows an info toast when the reader's access ends mid-read (J05-4f), the one toast not tied to the reader's own action.
- 0062 architecture: Render every admin page in the browser behind `AdminGuard`; the server sends the frame, a same-size skeleton and `noindex`; no service worker, manifest, JSON-LD or caches.
- 0063 design: Serve the admin's desktop and phone layouts from one app, switched at 1024px with Tailwind breakpoints; boards without a phone version scroll sideways.