TCG Commerce Operations Platform¶
The TCG Commerce Operations Platform is a Medusa-powered operations system for a single trading card game merchant selling across Shopee, Lazada, Telegram, Carousell, Instagram, a physical store, and event booths. It combines a standard commerce core with a custom application layer so the merchant can manage orders, inventory, costing, pricing, POS operations, and finance from one place instead of relying on spreadsheets and disconnected scripts.
The platform is designed around a clear architectural split: Medusa handles generic commerce capabilities (orders, inventory, stock locations, fulfillment, returns, workflow orchestration), while a custom application layer handles connectors, TCG-specific product semantics, DCA costing, finance, and operational tooling.
Status: Phase 7 complete — post-closeout dashboard hardening in flight (2026-05-18)
Phases 0–7 are done on tcg-platform/main. Phase 4 DCA + PO flow is stable on staging with partial receipts and the post-merge follow-ups closed. Phase 6's env-filtered order / exception lists and active-env home stats shipped in #131. The latest dashboard hardening after the Phase 7 closeout covers the staging import-picker regression (#130), floating UI viewport clamps (#132), and new-product placeholder copy polish (#133).
Single-tenant only
v1.0 is intentionally a single-tenant operations platform for one merchant. Multi-tenancy, subscriptions, and all SaaS control-plane features are explicitly deferred — see the "Deferred: SaaS & Multi-Tenancy" section of the Project Plan. Do not introduce tenant-aware data models, routing, or auth flows into MVP work.
Documents¶
| Document | Purpose |
|---|---|
| Product Requirements | What the product must do — personas, functional requirements, workflows, success metrics, release strategy. |
| Project Plan | How it will be built — system architecture, Medusa-vs-custom boundaries, module specs, infrastructure, testing, team structure, phase roadmap, risk register. |
| Data Model | Cross-phase data model — Phase 2/3/4/5/6 shipped tables plus Phase 7 Shopee profile tables documented, remaining Phase 4 tables (consolidation_event, order_status_event, sales_channel_config) + Phase 8 entities sketched, Module Links, workflows, profit derivation, and CSV-to-schema column mapping. |
| Phase 0 Notes | Findings from the Medusa local-spike — what surprised us, what felt right, what felt wrong, and the TypeScript-only architecture decision that followed. |
| Phase 1 Kickoff Plan | Foundation phase — scope, module scaffold, D1/D2/D3 task split, open decisions, exit-criteria checklist. (complete) |
| Phase 2 Kickoff Plan | Medusa fit validation — design for src/modules/tcg/, two DML models, two Module Links, seed plan. (complete) |
| Phase 2 Implementation Plan | Task-by-task implementation guide for the Phase 2 scaffold + seed + integration test. (complete) |
| Phase 2 Findings | Validation results from staging — what works, 10 gaps recorded (incl. 4 new Medusa 2.13.6 findings), and open questions for Phase 3+. (complete) |
| Phase 3 Kickoff Plan | Shopee slice — connector module, data model, ingestion + status + escrow flows, failure path, validation checklist. (complete) |
| Phase 3 Implementation Plan | Task-by-task implementation guide for the Phase 3 connector + jobs + signature verification + tests. (complete) |
| Phase 3 Findings | Validation results from staging — full cascade re-validated 2026-05-07 (READY_TO_SHIP → TO_CONFIRM_RECEIVE), cancellation + negative-SKU + real Shopee-signed push verified 2026-05-08, escrow / lost-push / reconcile gated on environmental triggers (production validation backlog). (complete) |
| Phase 4 Findings | DCA skeleton merge outcome (2026-05-14, PR #53) — 7 new tables, cost-allocation strategies, recomputeBatchCosts workflow, computeOrderLineProfit; consolidation, order-status, sales-channel-config, refund workflow, and admin UI carried into the wire-up pass. (complete) |
| Phase 4 Wire-up Plan | Kickoff plan for the operator-facing layer on top of Ivan's skeleton: PO admin module, DCA auto-recompute via subscriber, optional-fee workflow with late-fee auto-adjustment, manual receive-into-inventory button. Locks three design decisions. (design locked 2026-05-15) |
| Phase 4 Wire-up Implementation | PR-by-PR breakdown (PR-1 → PR-9): recompute subscriber, admin API for /imports, dashboard list + detail + create-PO flow, manual inventory hand-off, manual allocation strategy, CSV parity exit test. (implemented — see findings) |
| Phase 4 Wire-up Findings | Closeout for the operator-facing layer — 8 code PRs (#81 → #88) covering subscribers, admin API, dashboard list / detail / create / receive / manual-allocation surfaces, CSV-parity scaffold. (staging smoke green 2026-05-15; real-data parity + production UI smoke pending) |
| Phase 4 PO Flow Follow-up | Loyverse-style PO data entry + iterative partial receiving — variant picker on the line-item form, import_batch_receipt event table, snapshot-at-receipt asset valuation, po_date + expected_delivery_date header fields, partially_received status, overdue chip, supplier-overship force=true flag. (design locked 2026-05-15) |
| Phase 4 PO Flow Findings | Closeout: 7 design PRs (#94 → #99), 4 staging fixes, and 6 post-merge follow-ups closed by #127 + #129. (complete — CT 105 smoke green) |
| Phase 5 Kickoff Plan | Merchant Ops UI v1 — separate Next.js dashboard (Path B), monorepo restructure to apps/server/ + apps/dashboard/, Medusa user + custom user_role RBAC table. (complete — locks design) |
| Phase 5 Implementation Plan | Task-by-task implementation guide. Off-the-shelf stack locked (Medusa auth, RHF+Zod, TanStack Table+Query, shadcn/ui via UI/UX Pro Max). All PRs A–G + follow-up fixes #61 / #62 / #67 merged on main. Deploy target: Cloudflare Workers via @opennextjs/cloudflare. (complete — closed out 2026-05-12) |
| Phase 5 Findings | What shipped, gotchas (Edge-runtime middleware rename, CF Access service-token for Worker→Medusa, yarn hoist regression after PR G, disk maintenance), browser-verified route-by-route status, sidebar comingSoon affordance, open follow-ups. (complete) |
| Phase 6 Kickoff Plan | Multi-environment Shopee toggle — design decisions (login/logout semantics, single-Medusa internal toggle, AES-256-GCM at rest, path-routed webhook URLs). (complete — locks design) |
| Phase 6 Implementation Plan | PR-by-PR breakdown of the five PRs plus the boot-seeder hotfix. (complete — all PRs merged 2026-05-14 → 15) |
| Phase 6 Findings | Validation results from staging — browser smoke on both tabs, server-side curl coverage of webhook routing + OAuth callbacks + Phase 3 cascade regression, gotchas captured in flight (live-row 500 bug, credential cache, JWT_SECRET load-bearing). Env filters + active-env home stats closed by #131. (complete) |
| Phase 7 Kickoff Plan | Shopee Connector overhaul — N-profile model, region/URL derivation, pg_advisory_lock-guarded token refresh, metadata-only diagnostic UI, API-driven default-location dropdown. Locks 7 design decisions (D1–D7); implementation notes now capture the public OAuth callback path correction and immediate plaintext-token cleanup. (implemented) |
| Phase 7 Findings | Closeout report — what shipped across 7 feature PRs + 5 hotfix PRs, smoke results from CT 105, gotchas captured in flight (react/react-dom ABI mismatch, MikroORM JSONB deep-merge on model.json() columns, Cloudflare Insights SHA-512 red herring), open follow-ups. (complete 2026-05-17) |
| Development Workflow | AI-assisted dev methodology — the four-skill Claude Code stack (UI/UX Pro Max, Impeccable, Vercel plugin, optional frontend-design), per-region build cadence, anti-patterns (no auth replacement, no Vercel deploy), setup for collaborators. |
Development methodology¶
Phase 5 onward, the platform's UI work uses an explicit AI-assisted dev stack — not as incidental tooling, but as a load-bearing methodology. The design system gets generated once (ui-ux-pro-max → apps/dashboard/design-system/MASTER.md), every subsequent UI region is built against that north star, then audited region-by-region (impeccable's /audit → targeted-fix commands → /polish → commit). This is what stops AI-driven UI work from drifting toward the "statistical-average" aesthetic that gives generated interfaces their generic feel. Full doc: Development Workflow.
At a glance¶
- Commerce core + custom modules: Medusa v2 (TypeScript, single codebase —
src/modules/,src/api/,src/subscribers/,src/jobs/) - Frontend: Next.js 16 (admin dashboard, POS UI, Telegram Mini App)
- Database: PostgreSQL 16 (single instance — Medusa core tables, custom module tables, and Module Links in one DB)
- Primary channels (v1.0): Shopee, Lazada, Telegram Bot/Mini App, POS, manual (Instagram/Carousell/in-person)
- Out of scope for v1.0: TikTok Shop, native mobile apps, loyalty/CRM, automated purchasing, multi-tenancy