Skip to content

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.md
index 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.md
deleted file mode 100644
index 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.