docs/startup-shutdown-playbook.md

NaturalCAD Startup / Shutdown Playbook

Scope

Operational runbook for local testing and hosted testing (HF Space + Modal worker).

---

A) Local startup (recommended)

1) Start/verify Modal worker

cd "apps/cad-worker"
modal deploy main.py

Copy endpoint URL (example): https://<user>--naturalcad-generate-cad-endpoint.modal.run

2) Run local UI against Modal backend

From repo root:

export NATURALCAD_BACKEND_URL="https://<user>--naturalcad-generate-cad-endpoint.modal.run"
export NATURALCAD_API_KEY="<same value as NATURALCAD_API_KEY secret>"
npm run frontend:local

Open: http://127.0.0.1:7860

3) Optional local backend contract test

npm run backend:local

Note: this currently falls back to archive/gradio-demo-backend-legacy.

---

B) Hugging Face startup (team/client staging)

Space settings:

• Variable: NATURALCAD_BACKEND_URL
• Secret: NATURALCAD_API_KEY

Worker-side required secrets:

• OPENROUTER_API_KEY
• NATURALCAD_API_KEY
• SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY
• SUPABASE_BUCKET

Then restart/rebuild Space.

---

C) Shutdown

Local UI

• Stop process with Ctrl+C in terminal that ran npm run frontend:local.

Local backend (if started)

• Stop process with Ctrl+C in terminal that ran npm run backend:local.

Modal worker

• No manual shutdown required after deploy; Modal scales with traffic.
• If needed, stop app in Modal dashboard/CLI (modal app stop <app-id>).

---

D) Quick troubleshooting

1. LLM provider unavailable (402)

   • OpenRouter credits missing or wrong API key/account.

2. Unauthorized from backend

   • NATURALCAD_API_KEY mismatch between caller and worker secret.

3. HF push rejected due to binaries

   • HF git policy may reject binary assets; use HF-safe deploy snapshot.

4. No preview

   • Verify STL exists; UI can generate GLB from STL when backend GLB storage is disabled.

---

E) Safe pre-push check

Before pushing changes:

./scripts/prepush-check.sh