Open source CapCut alternative.
TypeScript
docs: move the config and experiments guide to su
David Le8e2394871f56
diff --git a/docs/README.md b/docs/README.mdindex 1a57a50c..0e177c8a 100644--- a/docs/README.md+++ b/docs/README.md@@ -24,7 +24,6 @@ Supported product and engineering guides live in `docs/guides/`. This list is th**Site and backend**- [Backend API Guide](guides/backend-apis.md) — the hosted routes the app and site call for model-backed work.-- [Configuration and Experiments](guides/config-and-experiments.md) — the settings registry with its runtime override, and experiments with audiences, per-account overrides and computed verdicts.- [Frontend and Next.js Guidelines](guides/frontend-nextjs-guidelines.md) — route structure, server/client boundaries, styling, and data access in the site app.- [The Blog](guides/blog.md) — the posts on donkeycut.com/blog: where a post lives, and how it reaches the page through the cache.- [Backlit Icon](guides/backlit-icon.md) — the dark treatment that lights the donkey mark from behind: the layer stack, the tokens, and the rules that keep the mark clean.diff --git a/docs/guides/config-and-experiments.md b/docs/guides/config-and-experiments.mddeleted file mode 100644index a013c6d3..00000000--- a/docs/guides/config-and-experiments.md+++ /dev/null@@ -1,159 +0,0 @@-# Configuration and Experiments--How the product is tuned at runtime, and how an experiment enrols accounts,-varies what they get, and reads its own result. A fork runs the same work with-its own numbers, and none of it needs a deploy to change.--**The one rule:** configuration is code with a runtime override. Every tunable-is declared once in the settings registry with a default and a schema, and-overridden by a database row; env holds secrets and nothing else. An experiment is a set of variants over settings, drawn by an audience.--## Settings--The registry is one file that lists every setting the product has. Each entry-carries a schema, a default, a title, a description, and whether the value is public. A public setting reaches the browser through the-account config route; a server setting is read only by handlers, webhooks and-jobs.--A value resolves in three layers, later ones winning:--```text-default (code)- │- ▼-override (SettingOverride row)- │- ▼-variant (the experiment the account is assigned to)-```--The registry parses every default against its schema when the module loads,-so a wrong default fails the process at boot. A stored override that no longer-parses after a schema change is skipped and logged. An internal admin app-writes overrides, experiments and promotions.--**Every tunable is a setting.** A threshold, a switch, a mode: if an operator-might want it different, it is a registry entry, and a feature that people-might tune ships its setting in the same change. A bare constant is right only-when one value fits every install.--## Experiments--An experiment has an audience, variants, and metrics. The variants each carry-a full value for every setting they change; the first variant is the control-the others are measured against. A variant may change nothing, in which case-the app reads the variant key itself. Its status walks draft to running,-running to paused and back, and either to ended.--### Audience--The audience is a set of rules over facts about the account, all optional; an-empty audience admits everyone. The rules cover where the assigning request-came from, when the account was created, whether it holds Pro, whether it has-ever paid, how recently it was active, and how much of its storage quota and-its credits it has used. Rules combine; every rule set must hold.--Facts are collected only when a running experiment the account does not yet-hold asks for them, and only the facts its rules read, so an experiment over-countries costs no billing query and an account that already holds every-running experiment costs none. A new rule is a field in the audience schema,-a fact, a line in the matcher, and the query that collects the fact.--### Assignment--Assignment is deterministic. The account id is hashed with the experiment key-under two salts: one decides whether the account is in the enrolled share,-the other picks the variant by weight. Raising the share only adds accounts,-and an account's variant never moves. The first read writes the assignment-row, and from then on the row is what the account reads, whatever the-audience says later. A paused experiment keeps its rows and applies nothing;-resuming picks up where it left off.--```text-app loads signed in- │- ▼-GET /api/account/config- │ assigns any running experiment the account is eligible for- │ marks first exposures- ▼-browser registers $feature/<key> = variant on every later event- │ first exposure → experiment_exposed- ▼-the app reads public settings and variant keys from the response-```--A variant reaches the product through the account's own config read, so an-experiment varies a public setting. A setting only the server reads resolves-without a user and is changed with an override.--Country comes from the platform's request header at assignment time and is-stored on the assignment row, so a report can say where each cohort was.--### Overrides by account--An account can be placed by hand: a manual assignment row names a variant, or-none to hold the account out, and stands in place of the hash. A holdout list, kept beside the-experiments, keeps an account out of every experiment: it is never assigned,-reads the plain configuration even where it holds a row, and never counts in a-result. Rows written by hand are never counted either.--### Results--A metric is something an exposed account does after its exposure: a PostHog-event by name, or a purchase recorded in the credit grants. An experiment-lists its metrics, and the first one decides the verdict.--A nightly job computes each live experiment's read and stores it on the row.-For every metric-and variant it counts exposed accounts and how many converted, then compares-each variant to the control two ways: a classical two-proportion test for the-p-value, and a Beta-Binomial posterior for the chance the variant beats the-control. The verdict is one of four:--| Verdict | Means |-|---|---|-| Too early | an arm is under the minimum exposures, or too few conversions have landed |-| Keep running | enough data, no clear difference; shown with the exposures each arm needs to read a planned lift |-| Ship it | a variant beats the control with p under 0.05 on a full sample |-| Stop it | every variant is very unlikely to beat the control, called on a small sample so a loser is stopped early |--The bars behind those verdicts are themselves a setting, so an operator can-ship at a looser p-value or demand a larger sample without a deploy. The-exposure property rides every PostHog event, so any funnel there breaks down-by variant as well.--## Promotions--A promotion is one email to an audience, minus anyone an earlier promotion reached; the Pro offers behind it (subscribe bonus, allowance multiplier) are settings. A copy sent to one person by hand carries the same per-person outbox key, so it counts in the promotion and a later segment send skips them.-Promotions, like every other email and background job, are written, queued and sent by the back office: a separate deployment that shares this database. This site holds the settings that shape the offers and the claim flow that lands them.--A credit promotion is a credit offer: one row that promises an account an-amount, the credit's life, and the window it can be claimed in, then records-the grant that lands. Every kind shares that row, and a kind is a setting and-code: what opens the offer and what claims it. A manual credit sent by email-is one kind, and its link closes a few days after the send; the subscribe bonus, offered when an account has spent a-share of its signup grant and landed by a Pro subscription created inside the-window, is another. A promotion's offer is landed by its link or, when the-promotion says so, by a Pro subscription started inside the window; a checkout-carries the largest open offer of that kind, so one lands per subscription.-An outreach note to one person carries the same offer terms. A new promotion-adds no table.--## Verification--The registry, audience, assignment, experiment schema, statistics and verdict-are pure and covered by unit tests. On a dev server, with an experiment of two-variants and a metric running, load the app as two accounts and confirm the-assignment rows and the exposure event; confirm a hand-placed account reads-its variant, a held-out account reads the plain configuration, and the results-job reads too early.--## Source Map--The framework is the abexp package under the site's packages folder: registry-shape and resolution, audience, assignment, the experiment schema, and the-statistics and verdict, with no host code inside. The site binds it in its-config library, which holds the product's registry, collects the audience-facts, and stores assignments; the results job runs in the back office with-the other background jobs.