Walking skeleton #4

Get one thin path working end to end through the platform: proxy and TLS, then the backend, the design-system basics and one storefront page.

Status

Appetite: none set (each step sets its own: 6h each for steps 2–4) · Estimate: — · Active so far: see the sub-issues' time comments

Steps 1–3 are done: the platform (commerce-platform#2), the backend v0.1.0 running at api. (commerce-backend#2, commerce-platform#7), and the design system's tokens and configs 0.1.0 (design-system#2).

Brief

Idea: Get one thin path working end to end before broadening any repo: browser → proxy → storefront → API → Postgres.

Problem and audience: Every stack is decided (commerce#3 and its six spikes), but no code exists. Scaffolding all seven repos side by side would put off integration risk until the end. A walking skeleton exposes the risky contracts early: local trust, digest-pinned images, the app compose fragments, the generated SDK, and private GitHub Packages.

Outcome: make bootstrap && make up on the platform serves a storefront page at https://rsl-commerce.test. The page shows data the backend read from Postgres, fetched through the generated SDK. The backend and storefront run from GHCR images pinned by digest.

Scope. In, one sub-issue per step:

1. platform: bootstrap, proxy, TLS and the infrastructure services (commerce-platform#2).
2. backend: a health endpoint and one catalog endpoint, the OpenAPI spec, the GHCR image and the compose fragment (commerce-backend#2), with the platform running app fragments (commerce-platform#7).
3. design-system: the config packages and tokens on GitHub Packages (design-system#2).
4. storefront: one page through the SDK (commerce-storefront#2).

• Each step also carries: its repo's ADR, landing as the first PR of the scaffold.
• The commerce ADR PR: also fixes the root README (eight hosts, Valkey).
• Out: checkout, admin, observability, the docs sites and ecosystem E2E. They follow once the skeleton stands.

Constraints:

• Repos meet only through contracts (AGENTS.md:11-17).
• Keep each change inside one repo (AGENTS.md:8-9).
• The decisions are in commerce#3 and its closed sub-issues.

Track: standard. The research is done, so each step goes brief → plan → execute. Appetite: set per step.

Assumptions: Steps run in the order above. Steps 2–4 were briefed together on 2026-10-08.

Spec

Not written yet.

Plan

Not written yet.

Decisions

Links

• Sub-issues:
  • Platform skeleton: bootstrap, proxy and local TLS commerce-platform#2 (step 1, closed)
  • Backend skeleton: health, one catalog endpoint, OpenAPI and image commerce-backend#2 (step 2, closed; v0.1.0 released)
  • Run applications from their compose fragments commerce-platform#7 (step 2, platform side: running app fragments; closed)
  • Design-system skeleton: tokens and config packages on GitHub Packages design-system#2 (step 3, closed; 0.1.0 published)
  • Storefront skeleton: one page through the SDK commerce-storefront#2 (step 4)
• Step 1 follow-ups (closed): Run the Linux bootstrap path in CI commerce-platform#4 (Linux bootstrap in CI) and Record the runtime and container ADRs and fix the README addresses #5 (system ADRs and README)
• Stack decisions: Choose the tech stacks #3 (closed) and its six spikes