Skip to content

Router.Africa — Planning & Documentation Backlog

A working to-do list for the 9 documentation/scoping items, with what each one actually requires, how they depend on each other, and a suggested execution order. This is the backlog itself — each item below becomes its own deliverable.


Historical index — partially superseded (annotated 2026-09-19, status refreshed 2026-09-20). The original text below is preserved unchanged for sequencing and dependency history. For current state, use the status table here; for decisions, ../architecture/decisions-log.md is the source of truth. Note the body still refers to apps/queue-consumer (item 4) — that Worker was folded into apps/dashboard-api as a queue() handler (decisions log → Queue consumer placement).

# Item Status Where it lives now
1 OpenRouter reverse-engineering Done (rev 2) ../product/openrouter-api-comparison.md
2 Tech stack doc Done ../architecture/tech-stack.md
3 Frontend scope Done — screens in dashboard-scope, stack in tech-stack ../product/dashboard-scope.md
4 Backend scope Done (short form, 2026-09-20). Service map, data map, request flows, scheduled jobs and failure behaviour. Small items to confirm before the schema (org vs workspace level of the content opt-in and hold toggle, spend cap counters, queue retry) are listed at its end ../architecture/backend-scope.md
5 Decisions log Done, living. No open decisions as of 2026-09-20; deferred work is in the future-optimizations register ../architecture/decisions-log.md
6 DB schema Done (2026-09-21). Column-level spec, ER diagrams and hot-path reasoning in db-schema.md, including the Better Auth tables. Checked end to end against the decisions log, backend scope, pricing model, build inventory, the hooks checklist and auth-security.md. Noted for the build: input_allowance unit, top-up fees per vendor and currency, per-currency minimum hold and rounding step, key rotation semantics, impersonation guardrails, and the Better Auth version checks (backlog #18) ../architecture/db-schema.md
7 Diagrams Done (2026-09-21). Topology (architecture.svg, regenerated 2026-09-19), request flow and the hold/settle state machine (with the idempotency row). Drawn from backend-scope.md section 3 and db-schema.md section 5; embedded in both ../product/architecture.svg, ../architecture/diagrams/request-flow.svg, ../architecture/diagrams/hold-settle-states.svg
8 Wiki Not started —
9 Execution plan Done (2026-10-26). 11 phases, 108 tasks, milestones M0–M4; status is tracked in the phase files ../execution/README.md
10 Developer API docs Scoped; approach revised (2026-10-26). A custom docs app (not Starlight) matching OpenRouter’s docs features, with the reference rendered from our curated OpenAPI spec; built in Track D of the execution plan ../product/api-docs-scope.md, ../execution/track-d-developer-docs.md
11 Billing / pricing model Done; launch markup values are set later in the admin app (not a blocker) ../product/pricing-model.md
12 Testing strategy Captured as a table in the tech stack doc; not yet split out. Add: Bifrost sync failure/rollback paths and the discrepancy view ../architecture/tech-stack.md
13 CI/CD pipeline Decided (revised 2026-10-26). One GitHub Actions pipeline, release-branch flow, GHCR, self-hosted runner, CI migrations, self-hosted Postgres for staging and, for now, production (PlanetScale later) ../architecture/cicd.md
14 Observability plan Drafted (2026-09-21), review pending. Signal catalogue with proposed thresholds, severity tiers, canary request, dashboards, runbooks to write. Thresholds are to be tuned after the load test; alert routing and on-call are not decided ../architecture/observability.md
15 API key security Drafted (2026-09-21), review pending. Generation, storage and authentication were already specified in auth-security.md; the new doc adds the lifecycle, blast radius, leak detection and response. The Bifrost virtual-key gap it raised is resolved (2026-10-25): value encrypted at rest; Bifrost unreachable from the internet via Workers VPC bindings and the pre-launch lockdown (decisions log) ../architecture/api-key-security.md
16 Launch scope Done. Markets decided (all Niobi markets live at launch); the v1 model list is admin-configured, with a model “on” only when it has a published rate and staff enable it ../architecture/decisions-log.md
17 Content-logging launch requirements (must not be forgotten) Decisions closed; build to-dos open across frontend, backend and website See the section below; decision in ../architecture/decisions-log.md → Audit trail & prompt/response retention
18 Cleanups and verifications Open, small See the section below

Goal: Extract everything publicly knowable about OpenRouter’s product surface (routing behavior, API contract, pricing model, failure handling) to inform what Router.Africa’s API needs to replicate or intentionally diverge from.

Note on scope, from earlier discussion: OpenRouter’s internal architecture (infra, DB, deployment) isn’t public and isn’t the useful target — their routing policy and API contract is, and that’s fully documented. This item should produce a comparison table: OpenRouter behavior → Router.Africa equivalent (via Bifrost) → gap, if any.

Depends on: nothing — can start immediately.


Goal: Single source of truth for every stack decision made so far, with the rationale, so it’s not scattered across chat history.

Should capture, per component: what was chosen, what alternatives were considered, why they were rejected, and any open caveats (e.g., cluster sizing still needs load-test data).

Depends on: nothing — this conversation already has the content; it’s a writing/organizing task.


Goal: Define what the dashboard actually needs to do — screens, data views, user flows — building on the existing Vite service once its stack details are shared.

Known requirements so far (from earlier scoping): usage analytics, request logs, cost breakdown by model/provider, billing/credit balance view, API key management, account/session auth (distinct from API-key auth).

Depends on: the Vite stack details (you said you’d share these) — worth starting the requirements/flows now and slotting in the technical specifics once that’s available.


Goal: Concrete service boundaries and responsibilities for the Node/TS Worker(s): what apps/api handles, what apps/queue-consumer handles, what data each touches.

Should resolve the open items flagged earlier: idempotency handling, mid-stream disconnect/settle policy, Bifrost timeout/retry policy, rate limiting.

Depends on: #5 (architecture decisions) should be finalized in parallel, since backend scope and open decisions are tightly coupled.


5. Open + finalized architecture decisions log

Section titled “5. Open + finalized architecture decisions log”

Goal: A living decisions record — separate from the tech stack doc (#2) — specifically tracking things that are decided (e.g., no queuing on the Bifrost call path, atomic UPDATE for hold/settle) versus still open (idempotency key design, disconnect/settle policy, rate limiting thresholds, CI/CD approach, data residency).

Format suggestion: simple two-column running log — Decided / Open — so nothing raised in conversation quietly gets lost (idempotency is the example of exactly this happening once already).

Depends on: nothing — start immediately, feed into #4.


6. Database schema / information architecture

Section titled “6. Database schema / information architecture”

Goal: What you’re describing is data modeling — the entities (accounts, API keys, holds, settlements, usage events, orgs/teams) and their relationships, before writing actual SQL. “Information architecture” more precisely refers to how information is organized/labeled/navigated (more of a UX term) — for this item you likely want schema design, plus a lighter IA pass for the dashboard’s navigation/data organization as part of #3.

Should cover: core tables (accounts, balances, holds, settlements, api_keys, usage_events), relationships, indexing strategy for the hold/settle hot path, and what goes in PlanetScale Postgres vs. what goes to the analytics store.

Depends on: #4 (backend scope) — schema follows from what the service actually needs to read/write.

Update (2026-09-20): the decisions #4 was meant to resolve are closed, so the schema is unblocked. Additional coverage it now needs: key rows with Bifrost sync status, allowed_models, admin and user spend caps, rate limits; the model “on” gate; markup rules and top-up fees; the content-logging flag with consent timestamp and terms version; request log and audit events (including reads of stored content) in one store; and the hooks checklist in ../architecture/future-optimizations.md.


Goal: Visualize the architecture — request flow (Worker → hold → Bifrost → settle → queue), system topology (Cloudflare + PlanetScale + K3s/Bifrost), and the hold/settle state machine.

Depends on: #2 and #5 being reasonably settled, so diagrams reflect final decisions rather than needing rework. Also feeds into #8 (the wiki should embed these).


Goal: A reference doc explaining the tools and concepts used across this stack (K3s, k6, Durable Objects, Hyperdrive, Bifrost’s routing model, etc.) — written for the team, not just for you, so onboarding doesn’t require re-deriving this conversation.

Should embed: the diagrams from #7 directly rather than duplicating explanations in prose.

Depends on: #7 for embedded visuals; otherwise can start in parallel with everything else as a glossary that grows over time.


Goal: Sequenced build plan — what gets built first, what blocks what, rough milestones.

Depends on: everything above. This is deliberately last — an execution plan built before the schema, scope, and open decisions are settled would just need to be rewritten.


Goal: External documentation a third-party developer reads to integrate — endpoints, auth, request/response shapes, error codes, rate limits, code samples. Distinct from everything above, which is internal planning.

Depends on: #4 (backend scope) and #1 (OpenRouter comparison, since the API contract likely mirrors it closely) — needs both settled to document accurately.

Update (2026-09-20): #4 and #1 are done, so drafting can start. Scope, content list, dependencies and the hosting decision are in ../product/api-docs-scope.md. Still needed before it can be finished: the error catalogue and rate-limit response contract (define with the apps/api build), the list of extra endpoints at launch, and the schema (#6) for any endpoint that returns ledger or key data. Decided: hand-written and curated (no generated reference), hosted at router.africa/docs, source in the website repo, built with Astro Starlight (a short spike first to check the site’s i18n, sitemap and Cloudflare adapter alongside it). Drift handling deferred. It also feeds work elsewhere: dashboard and website links.


Goal: How credits convert to local currency, margin over Bifrost/provider costs, top-up flows through Niobi’s payments rails, and FX handling if multiple African currencies are in scope. Currently assumed throughout the architecture but never actually specified.

Depends on: nothing technical — this is a business/product decision that the hold/settle mechanism (#4, #6) needs as an input, not the other way around. Worth resolving early since it shapes the schema.


Goal: Pull the testing approach (Vitest, @cloudflare/vitest-pool-workers, k6, the hold/settle concurrency-correctness test) out of the tech stack doc into its own standing reference for the team.

Depends on: #2 (tech stack doc) — split out once that exists.


Goal: How code moves from PR to deployed Worker / Bifrost config change / dashboard release.

Depends on: #9 (execution plan) is a reasonable pairing — sequencing and deployment mechanics are related decisions.


Goal: What signals surface a problem (queue consumer falling behind, PlanetScale write latency climbing, Bifrost errors) before customers notice.

Depends on: #4 (backend scope) and #6 (schema) — you need to know what’s being built before deciding what to monitor.


Goal: Ensure API keys never leak or get misused — generation, storage, rotation, scoping, and revocation.

Scope note: narrowed from a broader security/compliance review. Data residency and KYC/AML are explicitly out of scope here — Router.Africa relies on Niobi’s existing API signature/auth mechanism for that layer, so it isn’t a separate item for this backlog.

Should cover:

  • Key generation (sufficiently random, prefix sk-ra-, decided; see the decisions log, Public API authentication)
  • Storage — never store raw keys; store a hash (e.g. SHA-256) and match on hash at auth time, same principle as password storage
  • Scoping — per-key permissions/limits (e.g. spend cap per key, not just per account) so a leaked key has bounded blast radius
  • Rotation & revocation — how a user invalidates a compromised key without downtime, and whether old keys get a grace period or die immediately
  • Transmission — enforced HTTPS only, keys never logged (a real risk given the logging/analytics pipeline already in the design — worth an explicit rule that request logging redacts the key)
  • Detection — anomaly signals worth catching (sudden volume spike from one key, requests from unexpected patterns) that could indicate a leaked key in active misuse, tying into the rate-limiting item already flagged as open in #5

Depends on: #4 (backend scope) and #6 (schema) — key storage/scoping is part of the account/API-key table design.


Goal: Which markets ship first, which models are in the v1 list. Distinct from everything else in this backlog, which is how to build it — this is what ships first. Currently an open decision per existing project notes.

Depends on: #11 (billing/pricing, since currency support ties to market selection) and #15 (compliance, since market selection may be regulatory-constrained).

Update (2026-09-20): resolved. All markets live with Niobi at launch; the model list is admin-configured, not a fixed v1 list (decisions log → Launch scope, v1 model list).


17. Content-logging launch requirements (do not forget)

Section titled “17. Content-logging launch requirements (do not forget)”

Why this exists: prompt/response content is not saved by default; saving is opt-in per workspace (revised 2026-11-07, matching Terms 8.4 and Privacy 3.3/8), and what is saved is retained indefinitely for now (decisions log → Audit trail & prompt/response retention). These follow-ups must be closed before launch or consciously accepted.

  • Disclosure and consent for saving content (opt-in) — build in all three places:
    • Frontend (apps/dashboard): a toggle in Account Settings to opt in to saving prompts and responses (off by default), with a plain description of what is stored and who can read it.
    • Backend (apps/dashboard-api, apps/api): per-workspace content-logging flag defaulting to off; record the consent timestamp and terms version when it is turned on; audit-log every toggle change; turning it off stops future capture only (purging existing content is deferred); the content write path checks the flag.
    • Website (separate Astro repo): terms of service and privacy policy state plainly that content is not saved unless the customer opts in (already published: Terms 8.4, Privacy 3.3/8).
  • Access control (build requirement): stored content is readable only by admins, both Router.Africa staff admins and customer org admins; members and other roles get no access. Every read of stored content is audit-logged (confirmed).
  • Bifrost content logging off (backend/infra): set disable_content_logging in infra/bifrost and verify in staging that no content lands in Bifrost’s Postgres.
  • Datadog (backend/infra): confirm prompts and responses are not captured in traces.
  • Storage estimate: with indefinite retention, estimate R2 growth against expected traffic before launch.

Decided, no longer open: no PII redaction in v1 (bodies only, never headers or keys); audit trail shares the request-log store. Deferred to ../architecture/future-optimizations.md: retention window, customer deletion, purge on opt-out.


Small items surfaced while closing the decisions. None blocks the schema.

Doc cleanups

Auth setup (dashboard, before launch)

  • Create the three OAuth apps and note client id and secret: Google (Cloud console OAuth client), GitHub (OAuth app, user:email scope so the verified email is returned), GitLab (application on gitlab.com, read_user scope). Callback URL for each: https://app.router.africa/api/auth/callback/<provider>, plus the staging equivalent.
  • Cloudflare Turnstile site key and secret (free).
  • Resend (decided): create the account, verify the router.africa sending domain (SPF, DKIM, DMARC records in Cloudflare DNS), store the API key as a Worker secret, pick the from-address, and write the five templates (verify, reset, invite, low balance, receipt).
  • Auth conformance suite: implement the 20 tests in ../architecture/auth-security.md section 6 and run them in CI on every dependency bump. Verify the open items in its section 7 (cookie renaming to __Host-, one Better Auth instance versus two, sign-up enumeration, Cloudflare cache rules and response headers on staging).
  • Impersonation: settle the cross-origin hand-off (single-use token from admin. to app.) and write the test that proves a session with impersonated_by set can’t call any non-GET route or read stored content.
  • At the pinned Better Auth version, diff @better-auth/cli generate output against ../architecture/db-schema.md section 4.0 (including the two-factor and passkey tables), and confirm the GitLab provider config, account-linking behaviour with an unverified provider email, and whether stored OAuth tokens can be encrypted.

Verify against the running Bifrost instance

  • Usage reconciliation: confirm that an x-request-id header on a chat completion becomes the Bifrost log id, that GET /api/logs accepts start_time, end_time and min_tokens as expected, and that log rows carry the virtual key id (see the decisions log, Usage reconciliation).
  • The endpoint the admin app will read to list configured models (docs point to /api/models/details; not confirmed).
  • Whether BIFROST_MODEL_PARAMETERS_URL is the same setting as the pricing sheet URL (PricingURL). Only matters if egress is ever restricted.
  • Bifrost’s per-key allowed_models, rate-limit and budget fields, so the sync path pushes the right shape.
  • Whether Bifrost returns the virtual key’s value at creation (and only then), since it is stored encrypted (decisions log, Bifrost virtual key secret storage).

Security gaps to decide before launch (2026-10-26)

Verify for the private network path (decided 2026-10-25)

  • Workers VPC Service binding reaches an in-cluster Kubernetes Service through cloudflared (hostname resolution inside the tunnel), with streaming (SSE) passing through unbuffered and acceptable added latency.
  • Workers VPC is still free or acceptably priced when it leaves beta; if not, switch to the fallback (Tunnel hostname behind Cloudflare Access service tokens).
  • Niobi’s webhook source IPs (the full list) and whether they ever change; how Niobi announces changes.
  • The Cloudflare Queues HTTP push API from niobi-proxy, with a send-only token.
  • Before any Bifrost replicas: whether its rate-limit and budget counters are shared across replicas (future-optimizations.md).

Build reminders from decisions

  • Model “on” gate: a model needs a published rate and explicit staff enable; provider keys use explicit model lists, never ["*"].
  • Key creation order: pending row in Postgres, then Bifrost virtual key, then active, then show the key. Admin discrepancy view and periodic reconciliation job.
  • Admin spend cap is a fixed USD backstop in Bifrost and won’t follow FX moves; the user cap is enforced in Postgres in credits.

Where things stand (2026-09-20): #1, #2, #3, #5, #11 and #16 are done. The next chain is: #6 schema (the short #4 service map is done), then #7 diagrams (request flow, hold/settle state machine), then #14 observability plan, #10 developer API docs, #12 standalone doc (#13, #14 and #15 drafted 2026-09-21, review pending), #8 wiki and #9 execution plan. #17 build to-dos and #18 cleanups run alongside. The ordered list below is the original and is kept for history.

  1. #5 (decisions log) — start now, low effort, prevents further items like idempotency from getting lost
  2. #11 (billing/pricing model) — start now; shapes schema and market decisions downstream
  3. #2 (tech stack doc) — write up what’s already been decided in this conversation
  4. #1 (OpenRouter reverse-engineering) — independent, can run in parallel with 2/5
  5. #16 (launch scope) — once #11 has enough shape to constrain it
  6. #4 (backend scope) — resolves the open decisions from #5 into concrete service design
  7. #6 (DB schema) — follows directly from #4 and #11
  8. #15 (API key security practices) — alongside #6, since key storage/scoping is part of schema design
  9. #3 (frontend scope) — can start now on flows/screens, finalize once Vite stack details land
  10. #14 (observability plan) — once #4 and #6 exist
  11. #10 (developer-facing API docs) — once #4 and #1 are settled
  12. #12 (testing strategy doc) — split out of #2 once that exists
  13. #7 (diagrams) — once 2/4/5/6 are stable enough to draw accurately
  14. #8 (wiki) — folds in #7’s diagrams
  15. #13 (CI/CD & deployment pipeline) — pairs with #9
  16. #9 (execution plan) — last, once everything above exists

Status (2026-09-20): items 1, 2, 3, 4 (short form), 5, 11, 16 done; 12–15 decided but not yet written up as standalone docs; 7 partial; 6 next; 8–10 outstanding; 17 and 18 are open build to-dos and cleanups. See the status table at the top.