Memory Appendix
Memory Appendix
Verbatim dump of every persistent-memory file Claude accumulated on the Octopus project.
This appendix preserves every file from Claude Code's persistent project memory, verbatim, so nothing is lost in the handover. These notes were written incrementally while working on the codebase; they capture decisions, gotchas, and conventions that are often not obvious from the code alone.
Each note carries an original category: project/investigation facts, or feedback/working-preference conventions. Treat feedback notes as "house style / rules the previous maintainer asked to be followed."
Project & investigation notes
| Note | Summary |
|---|---|
| Client Portal Deploy | Client portal (frontend/client/, Next.js) is deployed to Cloudflare Pages, not via the systemd deploy scripts in deploy/ |
| G2A Import Integration | G2A Import API integration — Octopus as SERVER/sales-channel for G2A marketplace (inbound API), confirmed scope |
| Neocurrency Spec Drift | NeoCurrency production wire shapes contradict the OpenAPI spec in several places — the spec is unreliable. Prefer json.RawMessage for fields where prod/spec dis |
| Octopus Docs | How nav/sidebar/prev-next works in frontend/octopus-docs (Fumadocs), and the dev-mode cache gotcha when editing meta.json |
| Octopus Self Vendor | OCTO vendor — Octopus consuming its own /api/v1 gift-card API as a federated voucher vendor |
| Octopus Website | Next.js 16 static export at apex octopuscards.io — separate app from client portal, docs, backend; deployed to Cloudflare Pages |
| Orchestration Test Harness | End-to-end orchestration test harness in test/clientapi that drives real voucher orders through vendor adapters pointed at mocky-balboa with chaos injection — R |
| Runa Products Singular Vs Plural | Resolved — Runa docs are source of truth, all endpoints are SINGULAR. Both the Go client and the mock were wrong (plural) and have been corrected to match the O |
| Shopify Upgrade 2026 04 | Octopus Shopify integration upgrade plan to API 2026-04 — locked decisions for poll/ingest/email/fulfill/cancel scope |
| Vendor Architecture | Octopus has TWO distinct vendor concepts — topup vendors (suppliers) and the Grasshopper vendor (sales surface). All gift card products live under vendor.code=' |
Feedback & working-preference notes
| Note | Summary |
|---|---|
| Api Doc Format | Strict format for every API endpoint documentation page — path, request JSON, request params table, response JSON, enums, response table, error tabs |
| Autoreveal Animation | User prefers AutoReveal (timed, one-by-one float-up) over ScrollReveal for product cards and step sequences |
| Category In Query | When filtering variants by category, do it in the SQL query (WHERE clause), not in Go code loops |
| Cloudflare Pages Extensionless Routes | Any Next.js metadata route or route handler emitting binary content at an extensionless URL must be pinned via public/_headers — Cloudflare Pages + nosniff will |
| Deep Before Wide | User prefers exhaustive depth on one resource over breadth across many. Especially true for testing/correctness work. |
| Email Design System | Conventions, palette tokens, state-to-color mappings, and email-client constraints for transactional emails (vouchers, topups, eSIMs) |
| Metrics Dimensions | All business metrics must include client_id and product_id attributes for Grafana drill-down |
| No Alert Use Toast | All user-facing notifications in views/admin/ must go through the canonical showToast(message, type) helper, never browser alert() |
| No Confirm Use Modal | All destructive/state-changing prompts in views/admin/ must go through the canonical confirmAction(opts) Bootstrap modal helper, never browser confirm() |
| No Git Commands | Read-only git commands (status, diff, log, show, blame) are fine. Never run mutating ones (add, commit, push, reset, checkout, stash, etc.). |
| No Running Migrations | Never run migrations yourself — write them, let the user apply |
| No Sequential Ids In Urls | Never expose sequential/enumerable IDs in user-facing URLs — use UUIDs instead |
| No Speculative Vendor Paths | When fixing a vendor mapper bug, only handle the product types we actually receive — don't add untested branches for types we may never encounter |
| No Vendor In Customer Facing | Octopus must appear as a monolithic, standalone platform to clients. Vendor topology — including the word "vendor" itself, brand names of suppliers (Bamboo, Til |
| No Webhooks In Flight Substatus | Notifications (email + webhook) only fire at terminal (status, sub_status) pairs. In-flight sub-statuses like VendorOrderPending must not trigger any customer-f |
| Notification Scope Discipline | When working on the order notification system (OrderNotifier, email/webhook fanout), keep changes strictly to notification dispatch. Don't refactor wallet refun |
| Og Image Per Page Routes | When adding /blog/[slug], /cards/[slug], or similar shareable page types to octopus-website, ensure the corresponding /og/<section>/[slug] route handler exists |
| Repo Test Coverage | Every new function added to database/repo/ must ship with extensive tests covering happy path, error branches, and edge cases |
| Secret Row Column Stack | Client-portal MUI theme defaults Stack to direction=row; set direction=column explicitly for vertical layouts |
| Ui Layout | User prefers well-designed card UIs but gets frustrated when cards render horizontally instead of as a vertical list. Always verify layout direction. |
| Use Bun Not Npm | For all JS/TS package management and test running in this repo (grasshopper, client, octopus-website, mocky-balboa, octopus-docs), use bun -- never npm. |
| Vendor Amount Discount | Every direct_topup vendor mapper must populate MinAmount, MaxAmount, and VendorDiscount on types.Product — these fields drive pricing, margin, and the variant U |
| Vendor Chaos And Tests | Every new vendor adapter (direct_topup, vouchers, esim, payouts) must add a mocky-balboa route with chaos hooks AND ship contract + service tests in the same PR |
Seed Catalog
Every database seeder in the platform — the framework (Seeder interface, runner, seed all/fresh/list/info, the load-bearing cache flush, and the absence of any prod guard), all 41 registered seeders in dependency order, the 11 unregistered test-invoked orchestration seeders that wire vendors→tests, the no-op Grasshopper D1 seed, and the committed dev credentials worth rotating.
Api Doc Format
Strict format for every API endpoint documentation page — path, request JSON, request params table, response JSON, enums, response table, error tabs