Decisions
Each decision records what we chose and why. They live in docs/adr in the repository.
- Blog citations live in frontmatter, not Markdown footnotes
- One generated Database type, owned by libraries
- Notification-email renderers live in packages/emails; the edge functions run a generated copy
- Admin access is declared on each server function, and services take the Manager context instead of implementing Repository interfaces
- Edge functions enter through
serve(declaration, handler), and their logic lives in a unit-testedhandler.ts - Team route access is declared once in a map and enforced by a render gate, not in route
beforeLoad - The status page is a self-hosted Uptime Kuma, off Cloudflare and Supabase
- The daily Digest is built from Activities at send time, not held in the queue
- Platform fees come from a Rate card where the most specific rate wins, and no plan can buy a lower fee (accepted)
- A Public page's language goes in
?lang=, not an/en/prefix (accepted) - The app and the marketing site share one language cookie and one Bangla code,
bn(accepted) - Unpaid cash-on-delivery fees pause cash on delivery, not the shop (accepted)
- The COD limit follows how reliably a Creator pays us, not what they sell (accepted)
- Reference data lives in schemas and migrations, seeds are local fixtures only (accepted)
- Admin alerts are not Activities (accepted)
- Creator funds sit in their own bank account from day one (accepted)
- We collect as the Creator's agent, never as merchant of record (accepted)
- The ledger is append-only (accepted)
- A captured payment we cannot book is held, not a ledger row (accepted)
- We do not own Supabase's default privileges (accepted)
- Elements are fenced JSON in a Markdown body, rendered by one shared package (accepted)
- Unchecked Bio edits stay private (accepted)
- Rich Bios only link to YouTube (accepted)
- Shared moderation approves exact content revisions (accepted)
- Content feedback keeps one browser choice per page and language
- The Public page and Onboarding preview share presentation (superseded)
- The desktop app is a Tauri shell around the hosted app (accepted)
- The onboarding appearance example is owned by the App (accepted)
- Connected app tokens run as their own Postgres role (accepted)
- Actions take the Page language from the Referer (accepted)
- The Paywall break is a marker in the body, cut in SQL
- Uploaded images are checked before they have a public URL (accepted)
- Product videos are reviewed with their product draft (accepted)
- File removal purges the edge, and browsers cache uploads for a day (accepted)
- One shared brand and SEO head for every web app (accepted)
- Blog posts ask for Google preferred source with a plain link (accepted)
- Docs images are served from the marketing CDN bucket, not committed (accepted)
- AI connections limit prompt injection with layers, not server-side confirmation (accepted)
- Connected app logos come from a known-client list matched by name and host (accepted)
- Every Waitlist joiner before sign-up opens is a Founder (accepted)
- Marketing pages are served from Workers Cache (accepted)
- Share kit images draw text as HarfBuzz outlines, in the browser or an Edge Function (accepted)
- Coffee gifts may earn Rewards and stay gifts (accepted)
- The app shares marketing's Google Tag Manager container (accepted)
- Profile preferences are written as a server-side merge (accepted)
- Marketing stays open during maintenance releases (accepted)
- Public pages are shared through Workers Cache and purged by tag (accepted)
- Each worktree tests against its own Headless database (accepted)
- Looping motion is removed off screen on every marketing page (accepted)
- SQL failures reach Sentry through private.failure_reports
- Manager authority is read live, not from the JWT claim
- Edge user mode accepts only live, first-party, non-impersonated sessions
- The MCP worker is its own OAuth server; Supabase Auth is its only upstream (accepted)
- Marketing sends a hash-based, report-only Content-Security-Policy (accepted)
- Developer docs are Explainers and Runbooks, not change logs (accepted)
- A repo path in the docs links to the file on GitHub (accepted)
- The app session cookie is set by the browser, so it is not HttpOnly (accepted)
- Auth emails are sent by our own function, not by Supabase templates (accepted)
- Main deploys trust the PR gate on an up-to-date branch (accepted)
- The LLM leaderboard runs a frozen suite under fixed fairness and safety rules (accepted)
- Merges deploy Staging, and Production gets promoted commits nightly (accepted)
- Features launch by Feature flag, not by deploy (accepted)
- Migrations stay compatible with the code live before them (accepted)
- The Factory merges its own pull requests, one at a time, behind a Human-needed check (accepted)
- The Factory runs from its own worktree of
origin/main(accepted) - A hold the Factory's agent can clear goes back to the agent first (accepted)
- The Console changes the Factory only through a command inbox, and the owner can clear a Hold (accepted)
- Visual checks move to the QA issue, and every human step gets an issue (accepted)
- Images in gated posts stay in the public bucket (accepted)
- QA passes run beside the Factory and sign in to Staging through script-made sessions (accepted)
- One Finance manager approves and sends a Payout alone (accepted)
- The admin enforces a nonce Content-Security-Policy and falls back open on bad config (accepted)
- Creator pixels are IDs only, scoped per pixel, with payments sent server-side (accepted)
- The Factory recovers a Held release by itself (accepted)