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.
Current status
Section titled “Current status”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/.
Phases
Section titled “Phases”| 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 |
Order and parallel work
Section titled “Order and parallel work”Lane A (backend) 0 ─► 1 ─► 2 ─► 3 ─► 4 ─► 5 ─► 6 ─────────────► 9 ─► 10Lane 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.06Lane 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.
Decisions still needed
Section titled “Decisions still needed”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 |
|---|---|---|
| P1.08 | apps/api error handling (phase 3), API docs |
|
GET /v1/key |
P1.08 | — |
| P1.08 | — | |
/v1/messages (Anthropic format) and /v1/responses ship at launch |
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 |
Working rules (people and agents)
Section titled “Working rules (people and agents)”-
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. -
One task, one branch, one PR. Branch
<task-id>-<short-name>(e.g.p3.04-hold), PR intomain. The PR title starts with the task id. -
“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.
-
Update status in the same PR. Each task’s status lives in its phase file:
Status Meaning todoNot started in reviewPR open; link it, e.g. in review — [code #12](…)mergedMerged to main, not yet verified in stagingdoneIts “done when” passes in staging blockedWaiting on something; say what Set
in reviewin the task’s own PR, andmerged/donewhen it lands or is verified. Keep the Current status table below in step. -
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. -
No scope creep. Anything not in the build inventory goes to the inventory’s “Later” list or
future-optimizations.md, not into a task. -
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.
Where things are
Section titled “Where things are”| 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 |