Phase 1: Foundation — Kickoff Plan¶

Status: Complete ✅ (staging deployed 2026-04-22) Predecessor: Phase 0 Notes (complete — 2026-04-21) Successor: Phase 2 Kickoff Plan (complete — 2026-04-22) Exit criterion (from Project Plan): "A developer can run the Medusa application locally and in staging." — met.

This plan breaks Phase 1 (Foundation) into concrete, sequenced tasks with owners and deliverables. It is the first of ten sequential phases defined in the Project Plan roadmap.

Goal¶

Stand up the baseline environment: a clean Medusa v2 application repo with the custom module scaffold in place, Docker Compose running locally and in staging, CI/CD green, and the first Admin user able to log in. No business logic yet.

When Phase 1 exits, Phase 2 (Medusa fit validation) can start by dropping TCG product records into a working, deployed app.

Scope¶

In scope¶

Create ExzenTCG/tcg-platform GitHub repo.
Promote the Phase 0 spike repo as the Phase 1 starting commit (saves re-doing Docker/Podman/Yarn Berry patches — see "Scaffold rationale" below).
Scaffold src/modules/ skeleton with placeholder index.ts in each planned module directory.
Enable Medusa's built-in auth stack: @medusajs/user + @medusajs/auth with the emailpass provider.
Seed one Admin user in staging.
Local Docker Compose runs clean end-to-end (migrations + boot + admin login) in < 60 s from docker compose up.
CI/CD pipeline skeleton: lint, type-check, unit-test stub, Docker build per PR.
Staging environment (CT 105) provisioned and reachable at https://tcg-staging.exzentcg.com.
Developer onboarding doc in the repo (README.md) covering local boot, Podman socket caveat, and first-login flow.

Out of scope — deferred to later phases¶

Deferral	Phase
RBAC roles (Admin / Ops / Finance / Event Staff), role middleware	Phase 5 (work-split already lists "RBAC wiring" as D1 Phase-5 task)
Sensitive-action audit log table + subscriber	Phase 5
TCG metadata module (`TCGVariantMetadata`) implementation	Phase 2
Shopee connector	Phase 3
DCA / import batch module	Phase 4
Merchant ops UI (Next.js)	Phase 5
Lazada connector	Phase 6
Event / POS flows	Phase 7
Finance / reporting	Phase 8
Customer auth (Telegram Mini App)	Phase 7 (uses `@medusajs/customer` + Telegram `initData` HMAC verification — custom, not built here)

Scaffold rationale¶

The Phase 0 spike already produced a working medusajs/medusa-starter-default clone with Docker/Podman patches, Yarn Berry v4, and a clean first boot. Rather than re-scaffolding from scratch, Phase 1 promotes that repo as commit 1 of ExzenTCG/tcg-platform. This preserves the Phase 0 learnings (Podman socket, Redis env-var ordering, Vite HMR config) without re-deriving them.

Medusa itself is consumed entirely as npm packages under node_modules/@medusajs/* — the framework, admin UI, and all commerce modules (product, order, inventory, pricing, fulfillment, sales-channel, user, auth) are versioned npm dependencies. Upgrading Medusa in later phases = bump package.json, yarn install, run migrations. The scaffold repo ships only config, Docker files, and the custom src/ tree.

Module scaffold at end of Phase 1¶

Each module lives in src/modules/<name>/ with — at minimum — a placeholder index.ts that exports an empty Module definition so Medusa's loader registers the namespace. No business logic. No data models yet (those land in the phase that owns them).

Path	Purpose	Phase that fleshes it out
`src/modules/connectors/`	Shopee, Lazada, manual-channel ingestion	Phase 3, 6
`src/modules/tcg/`	`TCGVariantMetadata` linked to `productVariant`	Phase 2
`src/modules/dca/`	Import batches, DCA costing	Phase 4
`src/modules/finance/`	Cashflow, P&L, stakeholder equity	Phase 8
`src/modules/rbac/`	Role / UserRole tables linked to `@medusajs/user`	Phase 5
`src/modules/audit/`	Sensitive-action audit log	Phase 5
`src/modules/ops/`	Raw event store, exception queue, replay tooling	Phase 3+ (grows over time)

auth/ is intentionally absent

Medusa provides @medusajs/user (staff user model) and @medusajs/auth (login, logout, password reset, JWT sessions) out of the box. Building a custom src/modules/auth/ would duplicate upstream. The role system Phase 5 will add lives in src/modules/rbac/ — a separate concern, Module-Linked to Medusa's User via defineLink().

Task split¶

Mirrors the Suggested Developer Work Split for Phase 1. D1 owns architecture and most of the scope; D2 handles Medusa POC and Docker; D3 does frontend scaffold and CI/CD config.

D1 — Lead (most)¶

[ ] Create ExzenTCG/tcg-platform GitHub repo.
[ ] Import Phase 0 spike as the first commit.
[ ] Decide final src/modules/ directory list and write placeholder index.ts in each.
[ ] Enable @medusajs/user + @medusajs/auth in medusa-config.ts with emailpass provider.
[ ] Write README.md with local dev boot instructions (including Podman socket + Yarn Berry caveats from Phase 0).
[ ] Seed first Admin user in staging and distribute temporary credentials to the team.
[ ] Architecture-decision doc for any non-obvious choice made during Phase 1.

D2 — Mid¶

[ ] Verify Phase 0 Docker Compose is clean on a fresh clone (no dev-machine-specific paths).
[ ] Add .env.example and .env.staging.example with every env var the app reads (including the REDIS_URL ordering caveat from Phase 0).
[ ] Provision CT 105 on Proxmox per the staging runbook.
[ ] Deploy Medusa + Postgres 16 + Redis 7 via Docker Compose on CT 105.
[ ] Walk through NPM proxy host, Cloudflare Tunnel route, and Access policy setup.

D3 — Support (low)¶

[ ] Stand up a CI workflow (.github/workflows/ci.yml in the new repo) that runs lint, type-check, unit-test stub, Docker build on PR.
[ ] Seed one dummy test (e.g. a trivial smoke test against a module placeholder) so CI has something green to report.
[ ] Draft homelab/00_secrets/Credentials Index.md entry for tcg-staging (owner adds the actual values — file is Claude-protected).
[ ] Update homelab/01_planning/Phase 1/Architecture Diagram.md to show CT 105.

Open decisions (must be resolved before first PR)¶

Decision	Options	Owner
Who is D1?	—	Owner
Repo visibility	Public (open-source Medusa ecosystem fits this) / Private (safer while TCG domain logic is green)	Owner
Phase 0 spike → new repo history	Squash to single commit / Preserve spike history as initial commits	D1
Production host (Phase 10)	Proxmox / Cloud VM / Decide later	Owner (safe to defer)
Team allowlist for `tcg-staging` Cloudflare Access policy	Exact email list	Owner
Test framework	Jest / Vitest (Project Plan says either — pick one)	D1

Exit criteria checklist¶

From the Project Plan Phase 1 row ("A developer can run the Medusa application locally and in staging"), expanded:

[x] git clone git@github.com:ExzenTCG/tcg-platform.git && cp .env.example .env && docker compose up runs to a healthy boot on a fresh developer laptop.
[x] docker compose exec medusa yarn medusa user --email ... --password ... creates an Admin user; login succeeds at http://localhost:9000/app.
[x] Staging at https://tcg-staging.exzentcg.com/app is reachable (through Cloudflare Access) and login succeeds with the seeded staging Admin.
[ ] src/modules/{connectors,tcg,dca,finance,rbac,audit,ops}/index.ts all exist and Medusa boots without loader errors. (Partial: only src/modules/tcg/index.ts shipped — added in Phase 2 because the module was needed there. The remaining placeholder modules (connectors, dca, finance, rbac, audit, ops) still hold README-only directories and will be scaffolded in their respective owning phases. Medusa boots cleanly without them.)
[x] CI pipeline is green on main and on an open PR.
[x] README documents: local boot, env vars, first-login flow, Podman socket caveat, Yarn Berry caveat.
[x] tcg-staging runbook flipped from "Planned" to "Deployed" with snapshot name recorded (initial-deploy, taken 2026-04-22).