Skip to content

Router.Africa — Execution Plan

The step-by-step build from today’s scaffold to a public launch. Backlog item #9.

Each task is small enough for one person or one coding agent to pick up on its own. It names the spec it implements, the tasks it needs first, and what “done” means. The specs live in ../architecture/ and ../product/. The plan never restates a spec. Where a task and a spec disagree, the spec wins, and decisions-log.md wins over both.

Launch means a public launch with open sign-up, with the full build inventory in scope (decisions log, Launch shape). Friendly customers are onboarded at launch, on the same public product.

Updated 2026-11-03, after every open code PR was merged (2026-11-02). Task-level status, with PR links, is in each phase file; this is the summary. merged means in main but not yet verified in staging: nothing deploys until the self-hosted runner (P0.09) exists.

Phase Done or merged In review Blocked or left Next
0 — Foundations 6 done (P0.01–P0.04, P0.08, P0.10 installed); 3 merged (P0.06, P0.07, P0.12); P0.11 not needed 0 — (review fixes on the droplet applied 2026-11-05) You: P0.09 runner, custom domains (P0.07), P0.05; then P0.13, P0.14
1 — Data and contracts 8 merged, P1.06 done 0 P1.07: the staging seed P1.07 seed
2 — Pricing 6 merged 0 P2.01 needs the multi-provider FX update (Q3.7, after the Maansa scope) Q3.7
3 — Request path 10 merged (P3.10 local part) 0 P3.10 staging part, P3.11: need a deployed staging stack P0.13, then the staging checks
4 — Async and jobs 7 merged 0 — Verify in staging
5 — Accounts and keys 11 merged (P5.03–P5.13) 0 P5.01, P5.02 need P0.05 P0.05
6 — Payments 0 0 — P6.01 on Niobi’s direct collections API (../architecture/niobi-integration.md)
7 — Dashboard 13 merged (P7.01–P7.13); P7.14 in part (#47) 0 P7.14: sign-up and a charged call against staging Top-up screen for direct collections (phase 6)
8 — Admin 7 merged 0 P8.07: Cloudflare rules and token (deferred) Verify in staging
9, 10 0 0 — Wait on the phases above
D — Developer docs 1 draft (D.01) 0 — Your screenshot pass on OpenRouter’s docs

Every screen (1–55), every dashboard and admin API, the request path and the Bifrost adapter are in main. Staging’s Workers use the mock gateway; production uses Bifrost. Nothing is verified in staging yet: the pipeline runs the gates on every merge (they pass, real Postgres included) and skips migrate and every deploy until SELF_HOSTED_RUNNER is set (P0.09).

Since then (2026-11-04 and 05): the reviewer’s money and performance fixes #95–#105 are in main (decisions log, Code review fixes, 2026-11-04 and 05), merged without CI: GitHub Actions is stopped by account billing. Staging’s database is behind main by migrations 0012–0015.

Open code PRs: #107 (per-org in-flight cap, a re-open of #106) and #108 (runbook copy step). The screens stack (#14, #20, #25–#30), #18, #19 and #24 were closed because their commits reached main through the integration branch (#65); #11, #16 and #66 were closed as superseded (decisions log, Code review fixes, P0–P4 and Code review fixes, 2026-11-02).

Where the detail is: run reports in runs/.

Phase Goal Milestone at the end Status
0 — Foundations Accounts, environments, the pipeline, the private path to the droplet, Bifrost verified M0: a Worker in staging reaches Bifrost privately, deployed by the pipeline in progress (6 done, 3 merged, 4 todo)
1 — Data layer and contracts Schema, roles, migrations, shared types, the API error contract Migrations apply to staging; contracts written in progress (8 merged, 1 done, 1 in part)
2 — Pricing core FX, model catalog, markup, daily published rates A published rate exists for one model and currency merged (6 of 6; P2.01 needs the FX provider update)
3 — Request path apps/api: key auth, hold, gateway call, settle M1: a real request in staging is charged correctly in progress (10 merged, 1 todo)
4 — Async and scheduled jobs Queue consumer, job dispatcher, reconciliations, audit writer Logs, rollups and reconciliations run in staging merged (7 of 7)
5 — Accounts, auth and keys Better Auth, orgs and workspaces, key lifecycle, dashboard APIs A user can sign up, create a key and call the API in progress (11 merged, 2 todo)
6 — Payments niobi-proxy, top-ups, webhooks, staff credit moves M2: sign up → key → call → top up → charged, in staging todo
7 — Customer dashboard Screens 1–36 Every customer screen works against staging in progress (13 merged, 1 in part)
8 — Admin console Screens 37–55 Every admin screen works against staging merged (7 of 7; P8.07’s Cloudflare part deferred)
9 — Pre-launch hardening Lockdown, observability, load test, security review, legal, docs, production build-out M3: launch-ready; production verified by staff todo
D — Developer docs Custom docs app, curated OpenAPI spec, Request Builder, llms.txt; runs alongside phases 1–9 Docs live before launch (D.09 = P9.13) started (D.01 draft merged)
10 — Launch v1.0.0 to production, first customers M4: live todo
Lane A (backend) 0 ─► 1 ─► 2 ─► 3 ─► 4 ─► 5 ─► 6 ─────────────► 9 ─► 10
Lane B (frontend) 7.01–7.02 ──► 7 (screens as their APIs land) ─┤
8 (screens as their APIs land) ─┤
Lane C (infra) 0 ─────────────────────────────────────────────── 9.01–9.06
Lane D (docs) D.01–D.05 ──► D.08 drafts ──► D.06–D.07 (after 3.08) ──► D.09
  • Lane A is the critical path. Phases 1 to 6 build on each other, and phase 3 is the riskiest code. It is the money path, so its concurrency test comes first.
  • Lane B can start once phase 1’s shared types exist. It builds the design-system components and the app shell first, then each screen as its API lands. This is the natural lane for the second developer.
  • Lane D is the developer docs, mostly in the website repo. The audit, design and app skeleton can start now. The reference waits for the API (P3.08) and the error contract (P1.08).
  • Lane C is mostly you. It is phase 0, then the lockdown in phase 9, which must happen before real provider keys carry real traffic.
  • Within a phase, any task whose “Needs” are done can be picked up in any order.

These are the only things not yet decided. Each one sits inside the task that needs it, placed before the work it blocks.

Decision Task Blocks
API error format — decided: OpenRouter’s envelope, our subset. Catalogue still to write P1.08 apps/api error handling (phase 3), API docs
Cost and balance in API responses — decided: no, use GET /v1/key P1.08 —
Country and ASN on the request log — decided: yes; IP deferred (empty column) P1.08 —
Whether /v1/messages (Anthropic format) and /v1/responses ship at launch — decided 2026-11-07: both ship; P0.13 verifies they work P0.13 P3.08, website copy
Status page tool P9.08 Status page
Ask AI model and monthly budget (nice to have) D.10 The docs assistant only; not launch
Policy for credits spent through a leaked key (api-key-security.md 10) P9.11 Support process
When production moves from the cluster Postgres to PlanetScale, and the Hyperdrive pool P9.10 (after the load test) Production database
Alert routing and on-call P9.07 Production alerting
The Cloudflare rule that refuses plain HTTP on api. P9.05 API transport hardening
Launch values: markup, hold parameters, minimum hold and rounding, top-up fees P10.01 Published production rates and top-up quotes
  1. Read before building. Read the task’s spec links and decisions-log.md. Don’t re-derive or reopen a decision. If something seems wrong, raise it in the PR description and don’t silently diverge.

  2. One task, one branch, one PR. Branch <task-id>-<short-name> (e.g. p3.04-hold), PR into main. The PR title starts with the task id.

  3. “Done when” is the acceptance test. A task is done when its criteria pass in staging, not only locally. Tests ship in the same PR as the code.

  4. Update status in the same PR. Each task’s status lives in its phase file:

    Status Meaning
    todo Not started
    in review PR open; link it, e.g. in review — [code #12](…)
    merged Merged to main, not yet verified in staging
    done Its “done when” passes in staging
    blocked Waiting on something; say what

    Set in review in the task’s own PR, and merged / done when it lands or is verified. Keep the Current status table below in step.

  5. Specs change through the context repo. If building reveals a needed change, update the spec, and the decisions log if it’s a decision, in a separate context-repo PR. Then bump the context/ submodule in the code repo.

  6. No scope creep. Anything not in the build inventory goes to the inventory’s “Later” list or future-optimizations.md, not into a task.

  7. Secrets never go in the repo, a log, a PR or a chat. New secrets get a row in ../infra/secrets-inventory.md.

Who does a task:

  • You: needs console access, an account, money, or a decision.
  • Agent: a coding agent can do it end to end.
  • You + agent: an agent does the work and you supply access or sign off.
Need Look in
What’s decided and why ../architecture/decisions-log.md
Services, flows, failure behaviour ../architecture/backend-scope.md
Tables and columns ../architecture/db-schema.md
Auth, sessions, API-key auth ../architecture/auth-security.md, ../architecture/api-key-security.md
Network and security gates ../architecture/network-security-map.md
Pipeline, releases, secrets ../architecture/cicd.md, ../infra/secrets-inventory.md
Alerts, canary, runbooks ../architecture/observability.md
Screens and features ../product/build-inventory.md, ../product/dashboard-scope.md
Pricing ../product/pricing-model.md
Public endpoints, API docs ../product/api-surface.md, ../product/api-docs-scope.md, track-d-developer-docs.md
The droplet as built ../infra/installation-as-built.md