docs(decisions): record 0020–0025

0020 server organisms take labels from the app, 0021 the channel feed starts from the server page, 0022 post rules live in the API, 0023 the desktop composer is an intercepted dialog (publishing over the own channel goes back), 0024 home is the investor's browser feed, 0025 the investor's dashboard is a tabbed section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Amiram_se 2026-10-07 20:29:33 +04:00
parent 7949eb0d64
commit 9877d7bf14
7 changed files with 114 additions and 0 deletions

View File

@ -0,0 +1,18 @@
# 0020 Server organisms take their text as labels from the app
Status: Proposed · Area: architecture · Date: 2026-10-07 · Decided by: agent
## Context
The channel header and the track record are the same for every visitor and should render on the server with no client JavaScript. The platform has no i18n instance of its own; each app owns one, and React context (`useTranslation`) doesn't reach server components.
## Decision
- A platform organism that renders on the server takes its text as a `labels` prop. The app's template builds it with the platform's label builder and its server i18n: `channelHeaderLabels(i18n.getFixedT(null, 'channel'), i18n.getFixedT(null, 'common'))`, `creatorStatsLabels(i18n.getFixedT(null, 'content'))`.
- Label builders live beside the organism (`labels.ts`) or, for island organisms several screens use, in `platforms/market/src/shared/labels/`, and take `t` fixed to one namespace, so the same builder works with `useTranslation(ns).t` in client components.
- Client organisms keep calling `useTranslation` themselves.
## Alternatives
- Make the organisms client components with `useTranslation`: rejected; CreatorStats and the header would ship and hydrate for nothing.
- A platform-owned i18n instance: not chosen; it would duplicate each app's instance.
## Consequences
Templates in both apps pass one labels prop per server organism. Builders return functions, so labels never cross into a client component as props.

View File

@ -0,0 +1,17 @@
# 0021 A channel's feed starts from the server's first page as initial data
Status: Proposed · Area: architecture · Date: 2026-10-07 · Decided by: agent
## Context
The channel feed and the post page must be in the server HTML for search and first paint, stay live in the browser (older pages, edits, deletes, a subscriber's unlocked posts), and the platform can't reach the app's per-request `getQueryClient()` to prefetch and dehydrate.
## Decision
- The server reads the first page (or the post) through its cache and passes it as a prop; the client part's model uses it as the query's `initialData` (`postKeys.channelFeed`, `postKeys.detail`).
- The server read carries no session, so premium posts arrive locked. When the viewer is the creator or an active subscriber, the model reads the loaded pages again in the browser and the posts open in place; until then their gates show the pending skeleton.
- Mutations update these queries in place (`replaceCachedPost`, `removeCachedPost`); a new post drops the channel's query so its next visit starts from a fresh server page.
## Alternatives
- Query hydration with `HydrationBoundary` (the skill's default for live data): not chosen; it needs the app's query client inside a platform server organism.
## Consequences
A cached feed outlives a later server render of the same channel until it is invalidated, so every action that changes a channel's posts must update or drop `postKeys.channelFeed`.

View File

@ -0,0 +1,16 @@
# 0022 Post rules live in the API; the composer mirrors them
Status: Proposed · Area: architecture · Date: 2026-10-07 · Decided by: agent
## Context
C4 and C5 set the composer's rules, and the API had none of them: any caption length, any number and type of images, edits at any time, and publishing by any creator with a complete profile.
## Decision
- The API enforces them (back `POST_LIMITS`): text up to 2000 characters, up to four JPG, PNG or WebP images of 5 MB each, a published post's text, images and access level editable for 15 minutes, and publishing only by an approved creator who isn't suspended. A text post becomes an image post when an image is added, and back when the last is removed; a prediction stays a prediction.
- The front mirrors the same numbers in `features/post` `POST_LIMITS` to check before sending, and treats the API's answer as final (a 403 on save means the window closed).
## Alternatives
- Front-only checks: rejected; another client could break the paywall's promise that a post stays as subscribers read it.
## Consequences
Changing a limit is a change in both repos. Existing posts longer than 2000 characters stay as they are; only new writes are checked.

View File

@ -0,0 +1,19 @@
# 0023 The desktop composer is an intercepted dialog
Status: Proposed · Area: architecture · Date: 2026-10-07 · Decided by: agent
## Context
C4 ۷.۳ opens «پست جدید» on desktop as a 640px dialog over the page the creator is on, while /compose/post is also a page of its own (a reload, a shared link, a login that returns there). Mobile keeps the pushed page.
## Decision
- bear's `(main)` layout has a `@modal` slot. `@modal/(.)compose/post` intercepts a soft navigation to /compose/post and renders the composer in island `Modal size="wide"`; a hard load gets the `(flow)` full page. The edit route is not intercepted.
- The slot is emptied by explicit null pages for the routes the dialog lands on (`@modal/channels/[username]`), never by a catch-all: a catch-all would match every unbuilt path, and a soft navigation there keeps the old page under the new URL.
- `(main)/default.tsx` reloads the URL when the intercept fires from outside `(main)` (the full composer's header, a login that returns there), so the full page takes over instead of a dialog over an empty frame.
- Closing the dialog goes back in history. Publishing over the creator's own channel also goes back, then refreshes, so the channel isn't in history twice; anywhere else it replaces the dialog's entry with the channel and refreshes. The refresh is needed because the channel under the dialog is reused, not fetched again.
## Alternatives
- Dialog state without a route: rejected; the URL would not say what is open, and the composer's deep link would need a second code path.
- A `[...catchAll]` slot page: rejected for the reason above.
## Consequences
Every new route the dialog can land on needs its own null `@modal` page. While the dialog is open `usePathname()` reads /compose/post, so the page under it sees that path.

View File

@ -0,0 +1,19 @@
# 0024 خانه is the investor's feed, read in the browser
Status: Proposed · Area: architecture · Date: 2026-10-07 · Decided by: agent
## Context
`/` (خانه) is drawn for investors only: their followed creators' posts, premium ones open when subscribed. A creator's home tab is their own channel, no board draws a guest's home, and the API answers 401 to a guest and 403 to a creator. Every link home (the brand, back with no history, «بازگشت به خانه», login with no return path) lands there.
## Decision
- The server sends only the frame (top bar or header, «خانه») and the feed's skeleton, the same for every visitor; the feed is read in the browser with the session (`feedKeys.home()`, no server read and no `initialData`, unlike 0021), so nothing is read again for a subscriber.
- In the browser, `HomeGuard` sends a guest to login with a return to `/`, a creator to their channel with `router.replace` (to step 5 first while `needsProfile`), and any other role to the no-access state; the skeleton stays until then.
- Page and loading sit in `(main)/(home)`, so its loading covers no other main route (0017); bear's `@modal/page.tsx` is the null page for `/` (0023).
## Alternatives
- A server read like the channel's (0021): rejected; the feed exists only for a signed-in investor.
- AuthGuard's no-access state for a creator: rejected; its «بازگشت به خانه» leads back to `/`.
## Consequences
- `/` is not indexed. A guest's «بازگشت به خانه» (error pages, a missing channel) lands on login.
- Follows change the feed: every follow or unfollow calls `syncFollowCaches`, which invalidates `feedKeys.all`.

View File

@ -0,0 +1,19 @@
# 0025 The investor's dashboard is a tabbed section, one route per tab
Status: Proposed · Area: architecture · Date: 2026-10-07 · Decided by: agent
## Context
U8 ۴.۱, ۶.۱ and U2 draw the investor's داشبورد as three sections («اشتراک‌ها» · «تراکنش‌ها» · «دنبال‌شده‌ها») under one 48px tab row, which stays live while a section loads; S1 makes each section its own Suspense. The creator's داشبورد (pricing, finance) has other tabs and lives under the same `/dashboard` path.
## Decision
- Each section is its own route (`ROUTES.dashboard.subscriptions`, `.transactions`, `.following`), so a section can be linked, reloaded and loaded on its own.
- The sections sit in the route group `dashboard/(investor)`. Its layout holds the frame: on mobile the tab top bar «داشبورد», on desktop the «داشبورد» heading in the 640 column, then `DashboardTabs` (island `TabLinks`, active from the URL). Each section page brings its own `loading.tsx` with the list skeleton only.
- A section renders in the browser behind `AuthGuard role="investor"` and its part boundary; the frame and the tabs render on the server for every visitor.
## Alternatives
- One page with tab state: rejected; the URL would not say which section is open, and every section's code would load with the first.
- Tabs inside each page: rejected; the row would unmount on every switch, and each loading would repeat it.
## Consequences
- A creator who opens an investor section sees the tabs over the no-access state.
- The subscriptions and transactions tabs link to routes that are still placeholders (`(investor)/subscriptions`, `(investor)/transactions`); they 404 until built.

View File

@ -22,3 +22,9 @@
- 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 «پست جدید» is a dialog over the page through bear's `@modal` intercept of /compose/post; slots are emptied by explicit null pages, never a catch-all, and a hard load gets the full page.
- 0024 architecture: `/` (خانه) is the investor's feed, read only in the browser with the session behind a same-size skeleton; a guest goes to login with a return to `/`, a creator to their own channel.
- 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.