This repo provisions isolated WooCommerce stores on Kubernetes from a control-plane API and dashboard.

• Control plane API: backend-node (Node.js + Fastify)
• Dashboard UI: dashboard (Vite + React)
• Platform chart: charts/platform

• Docker Desktop (running)
• Minikube
• kubectl
• helm
• Node.js 20+
• npm

Quick version checks:

minikube version
kubectl version --client
helm version
node -v
npm -v

minikube start
minikube addons enable ingress
kubectl config current-context
kubectl get ns

Expected context: minikube.

Build API image into Minikube:

minikube image build -t store-platform/api-node:dev backend-node

Install or upgrade chart:

helm upgrade --install platform ./charts/platform -n platform --create-namespace -f ./charts/platform/values-local.yaml --set api.image=store-platform/api-node:dev

Verify:

kubectl -n platform get pods
kubectl -n platform get svc

API pod should be Running and ideally 1/1 Ready.

Terminal A (API port-forward):

kubectl -n platform port-forward svc/platform-api 8080:80

Terminal B (dashboard dev server):

npm --prefix dashboard install
npm --prefix dashboard run dev -- --host 0.0.0.0 --port 5173

Open:

• http://127.0.0.1:5173

If you run in a remote IDE/codespace, forward both ports:

• 5173 (dashboard)
• 8080 (API)

For local development, put backend secrets and overrides in the repo root .env.local.

Example:

STRIPE_SECRET_KEY=sk_test_...
STRIPE_PRICE_ID=price_...
STRIPE_PLAN_LABEL=Growth
ADMIN_EMAILS=you@example.com

Then rerun either:

powershell -ExecutionPolicy Bypass -File .\ops\up.ps1

or:

powershell -ExecutionPolicy Bypass -File .\ops\resume.ps1

The scripts now read the root .env.local automatically and apply those values to the API deployment. Do not put STRIPE_SECRET_KEY in dashboard/.env or dashboard/.env.local.

API health:

curl.exe -s http://127.0.0.1:8080/healthz

Create store:

curl.exe -s -X POST http://127.0.0.1:8080/stores -H "content-type: application/json" -d "{\"engine\":\"woocommerce\"}"

List stores:

curl.exe -s http://127.0.0.1:8080/stores

Events for one store:

curl.exe -s http://127.0.0.1:8080/stores/<storeId>/events

Links:

curl.exe -s http://127.0.0.1:8080/stores/<storeId>/links

Delete store:

curl.exe -s -X DELETE http://127.0.0.1:8080/stores/<storeId>

A store moves to Ready only after:

1. Namespace + guardrails are applied.
2. Secret is created.
3. Helm install job succeeds.
4. Workload availability gate passes.
5. In-cluster WordPress service health check succeeds.

Only then does URL get written in the store row and dashboard.

Transient infrastructure errors (for example ingress webhook/controller hiccups or API timeouts) are retried automatically with backoff while the store remains in Provisioning (up to a retry cap), instead of failing immediately on first transient fault.

1. Confirm port-forward is running:

kubectl -n platform port-forward svc/platform-api 8080:80

2. Confirm API:

curl.exe -s http://127.0.0.1:8080/healthz

3. Confirm API pod:

kubectl -n platform get pods -l app=platform-api -o wide
kubectl -n platform logs deploy/platform-api --tail=100

Check events first:

curl.exe -s http://127.0.0.1:8080/stores/<storeId>/events

Then inspect namespace resources:

kubectl -n store-<storeId> get jobs,pods,svc,ingress

If Helm job is failing:

kubectl -n store-<storeId> get pods -l job-name=helm-install-<storeId>
kubectl -n store-<storeId> logs <helm-job-pod-name>

Symptom from helm job logs:

• failed calling webhook "validate.nginx.ingress.kubernetes.io"... connect: connection refused

Fix:

kubectl -n ingress-nginx get pods,svc
kubectl -n ingress-nginx rollout restart deploy ingress-nginx-controller
kubectl -n ingress-nginx get endpoints ingress-nginx-controller-admission

Retry store creation after ingress controller is healthy.

This is usually Minikube control-plane instability.

minikube status
minikube stop
minikube start
kubectl get ns

Stop local foreground processes first (Ctrl+C in dashboard and port-forward terminals).

Uninstall platform:

helm uninstall platform -n platform

Optional cleanup of store namespaces:

kubectl get ns --no-headers | ForEach-Object { ($_ -split '\s+')[0] } | Where-Object { $_ -like 'store-*' } | ForEach-Object { kubectl delete ns $_ }

Stop Minikube:

minikube stop

Full reset (optional):

minikube delete

1. Show kubectl -n platform get pods.
2. Open dashboard (127.0.0.1:5173).
3. Click create store.
4. Open Activity panel and show lifecycle events.
5. Show namespace isolation:

kubectl get ns | findstr store-

6. Open resulting storefront/admin URL from the dashboard.
7. Delete store and show namespace cleanup.

• MAX_STORES: max active stores per client IP.
• TRUST_PROXY: trust proxy headers.
• RATE_LIMIT_ENABLED: global limiter on/off.
• RATE_LIMIT_CAPACITY + RATE_LIMIT_REFILL_PER_SEC: global bucket.
• CREATE_RATE_LIMIT_CAPACITY + CREATE_RATE_LIMIT_REFILL_PER_SEC: create endpoint limiter.
• CORS_ORIGINS: comma-separated allowlist (* supported).
• ADMIN_API_KEY: required for sensitive credential endpoints when set.

Note: The orchestrator/API used by the platform is backend-node (Node.js). The backend/ Python folder is not part of this control-plane runtime path.

Use this order so you understand both architecture and implementation details.

1. Read architecture and runbook:
   • SYSTEM_DESIGN.md
   • README.md (this file)
2. Understand backend API entrypoint and lifecycle:
   • backend-node/src/server.ts
   • backend-node/src/provisioner.ts
   • backend-node/src/kube.ts
3. Understand persistence and coordination:
   • backend-node/src/db.ts
   • backend-node/src/lease.ts
   • backend-node/src/leader.ts
4. Understand deployment config generation:
   • backend-node/src/engine.ts
   • backend-node/src/secrets.ts
5. Understand infrastructure chart:
   • charts/platform/values*.yaml
   • charts/platform/templates/*.yaml
6. Understand UI:
   • dashboard/src/App.tsx
   • dashboard/src/App.css
   • dashboard/vite.config.ts
7. Review helpers and demo scripts:
   • scripts/*.sh
   • scripts/*.md
8. Review legacy Python prototype only for historical context:
   • backend/app/*.py

Create store request path:

1. POST /stores in backend-node/src/server.ts
2. Row inserted in SQLite (stores) with Provisioning
3. Reconciler loop in backend-node/src/provisioner.ts claims row via lease
4. K8s guardrails applied via backend-node/src/kube.ts
5. Secret generated/stored via backend-node/src/secrets.ts
6. Helm install job launched (alpine/helm) via applyHelmJob
7. Deployment availability + in-cluster HTTP checks
8. Store row updated to Ready with URL + events written

Delete store request path:

1. DELETE /stores/:id marks Deleting
2. Reconciler runs Helm uninstall job
3. Namespace deletion and wait-for-gone
4. Store row removed

1. Why desired-state + reconciler is used instead of synchronous request-only provisioning.
2. Why per-store namespace isolation is combined with quota/limit/network policy.
3. Why leases and leader election are both present.
4. Why store creation is asynchronous and event-driven.
5. Why retries/backoff exist and how transient infra errors are handled.
6. Why Helm is run inside Kubernetes Jobs (and tradeoffs vs direct SDK-only deploys).
7. How RBAC is scoped and why bind on admin was needed for per-namespace rolebinding.
8. How UI handles API-base fallback and partial outages gracefully.