Start Here — Reading the Labyrinth
How this handover wiki is organized and how to read it — a map of the sections, reading paths by goal (onboarding, firefighting, tracing an order, following the money, touching a vendor, changing the API, deploying), the conventions (file:line citations, Callouts, the 🔴🟠🟢 Known-Issues index, the Memory Appendix), and the trust rules.
This wiki is dense on purpose — it's an offboarding handover meant to make the next maintainer self-sufficient, so it traces almost every claim to a file:line. That thoroughness makes it a labyrinth if you read it front-to-back. Don't. Read by goal. This page is the map and the compass.
What this is (and isn't)
It's an exhaustive reference, assembled by deep reads of the codebase, current as of mid-2026. It is not live state. Every page is a point-in-time snapshot: where a page and the code disagree, the code wins. We already caught the repo's own frontend/client/ARCHITECTURE.md describing a Cloudflare-Pages deploy that had migrated to systemd — so verify a file:line before you act on it.
The map
The nav follows that flow top to bottom. Eleven sections:
| Section | What lives there |
|---|---|
| Start Here | this guide, onboarding, and the Known Issues triage |
| Architecture & Data | the one-binary architecture, the database, the table catalog |
| Catalog & Clients | products & pricing, the three catalog schemas, per-client config |
| Orders, Money & Fulfilment | order lifecycle, top-up/eSIM flows, state machines, inventory (FEFO), wallet & ledger, jobs, crons |
| Vendors | the adapter model, vendor config/secrets, per-vendor adapters |
| API & Access | the /api/v1 reference, error codes, auth surfaces, payouts, notifications, webhook payloads |
| Sales Channels | inbound Shopify and G2A |
| Frontends & Admin | the frontends index, the client portal, the Grasshopper claim worker, the admin panel |
| Infrastructure & Ops | servers, tracing, Cloudflare, secrets, env vars, deploy, ops runbooks, symptom troubleshooting |
| Testing & Fixtures | how tests run, the test catalog, adapter tests, the mocky-balboa mock, the seeders |
| Appendix | the Memory Appendix — verbatim house rules & spec-drift notes |
Reading paths by goal
Pick the row that matches why you're here and read those pages in order.
| If you're… | Read in this order |
|---|---|
| Brand new to Octopus | Onboarding → Architecture → Order Lifecycle → Known Issues |
| Answering a support ticket ("recharge not complete", "can't see the product", "stuck PENDING", "can't log in", "can't pay in this currency") | Troubleshooting Runbooks — jump to the symptom, then follow it into the subsystem page |
| Firefighting a prod incident | Known Issues → Operations → Troubleshooting for the symptom → the subsystem page → Metrics & Tracing |
| Tracing how an order becomes a code | Order Lifecycle → State Machines → Vendors → Vendor Adapters → Inventory Flow |
| Following the money | Wallet & Ledger → Products & Catalog (pricing) → Payouts → Error Codes |
| Adding or fixing a vendor | Vendors → Vendor Config → Vendor Adapters → Vendor Adapter Tests → Mocky-Balboa |
| Changing the client API | API Reference → Auth & Access → Error Codes → Webhook Payloads |
| Working on the client portal | Client Portal → Auth & 2FA → Settings |
| Working on the claim page | Grasshopper → UI & HTMX → API & Provisioning |
| Understanding a Shopify/G2A sale | Shopify or G2A (both link back into the order engine) |
| Deploying / on-call | Deploy & Release → Operations → Env Reference → Secrets & Config |
| Writing or running tests | Testing → Test Catalog → Seed Catalog |
Conventions
file:linecitations — pages point at exact code (e.g.create_voucher_order.go:3347). They're the ground truth; the prose summarizes. Verify before acting — this is a snapshot.- Callouts carry the signal — info = context or a key fact to hold onto; warn = a gotcha, divergence, or stale-comment trap; error = a real bug, security risk, or fund-loss hazard.
- Known Issues is the master index of what's broken — every finding across the wiki, ranked 🔴 critical / 🟠 high-med / 🟢 low, each row linked to its detail page, with a suggested first sprint. If you want the "what's wrong and what to fix first" view, start there, not here.
- The Memory Appendix is the previous maintainer's verbatim notes — house rules, decisions, and spec-drift that aren't in the code. It's point-in-time and may be stale; treat it as leads to verify, not gospel.
The three rules that never bend
Reproduced from the home page because they matter most:
- Never run ad-hoc
INSERT/UPDATE/DELETEon any database — local, sandbox, or prod.SELECTfor investigation only; all changes go through the app or migrations. - Migrations are applied by a human, never on app start — both Goose (Postgres) and D1 (Cloudflare).
- To the customer, Octopus does everything itself — never expose vendor topology (brand names or the words vendor/upstream/supplier) in any client-facing surface. See the rule.
When in doubt about what's safe to touch, that's what Operations and Known Issues are for.