Launch data model

Vocabulary (from spark-contracts)

Type	Values
LaunchPlatform	facebook, instagram, whatsapp, tiktok, snapchat, google_business, google_ads, youtube
CellTarget	a LaunchPlatform, or client for once-per-business items
CellStatus	done, reviewing, needs_client, needs_fix, not_started, not_needed
CheckMethod	api, staff, plan
LaunchStage	1 to 7

UI labels: done = Done, reviewing = Platform reviewing (or "Spark is checking" when the cell's reviewer is spark), needs_client = Needs you, needs_fix = Needs a fix, not_started = Not started, not_needed = Not needed.

The criteria catalogue

The catalogue is data, not code (modules/catalogue/data), versioned (criteria.v1). Adding a platform or a criterion is a data change plus, where needed, a checker.

A criterion has:

Field	Meaning
key, stage	e.g. business_verified, stage 3
title, description	English and Arabic text; variants override them per business type (services, products, both)
required	required items gate the launch; recommended items do not
perTarget	platform (one cell per platform) or client (one cell per business)
platforms	which platforms it can apply to
appliesTo	optional country and business-type rules
method	the check method per target, e.g. facebook: "api", snapchat: "staff"
typicalDays	[min, max], used for the estimate
glossary, sources	term keys and the platform or academic sources behind it

Stages follow SOSTAC order: 1 Presence, 2 Identity & brand, 3 Verification, 4 Strategy, 5 Catalogue, 6 Funnel & tracking, 7 Campaigns.

Guides are keyed criterion:target and hold numbered steps (English and Arabic, the build fails if they don't pair up), copy fields, downloadable assets (logo, cover), minutes, a responsible/accountable pair, sources, and verifiedAt. A guide never verified, or not re-verified for 180 days, is shown as "may be out of date".

Launches and cells

• A launch is unique per organization. It stores country, business type, chosen platforms, the primary asset per platform, a status (active, launched, offboarded), the assigned staff owner, an optional flows override (who, why, when) and whether self-serve setup is done.
• A cell is one criterion × one target. It stores the status, method, an optional reviewer (platform or spark), a detail and blocks content key, staff evidence, confirmedUntil, client claim and assist timestamps, check timestamps, a staff-only note, the strategy version that completed it, and a rev counter that guards concurrent writes.
• The event log is append-only: status_changed, client_claimed, assist_requested, staff_confirmed, note, assigned, override, document_viewed, document_downloaded, document_uploaded. Events marked staffOnly never reach the client view.

Check methods

• api: the evaluator reads a platform snapshot (Meta, TikTok/Snapchat, backend profiles). Runs nightly and on "check now"; a check too soon after the last one is skipped. A done cell that fails becomes needs_fix.
• staff: a staff member sets the status; done requires an evidence file. The confirmation expires after 90 days.
• plan: set by the approved strategy (method plan, strategyVersion set). Until a strategy exists, staff can confirm with the plan document as evidence (90-day expiry).

Readiness

readiness.compute() is pure (no I/O, no clock):

• percent = done ÷ cells that are neither not_needed nor stage 7, rounded.
• readyToLaunch = every required cell in stages 1–6 is done.
• missingRequired = the remaining required stage 1–6 cells.
• etaDays = [largest remaining minimum, sum per stage of the largest remaining maximum], or null when ready.

Identity and documents

• One business identity and one brand kit per organization.
• Verification documents use envelope encryption: each document gets its own random data key (AES-256-GCM), wrapped by a service key. The organization and document ids are bound into the authentication tag, so a blob moved to another record will not open. Every view, download, upload and deletion is written to an access log. Documents are kept while the launch is active and deleted 90 days after offboarding by a daily retention job.