Local Dev Runtime

This document describes the local development and smoke-test setup that is currently used for capetownmarket-faas.

The current local runtime is centered on the portal web app plus the backend services it depends on:

• apps/portal-web for the browser surface
• automation-core on 50001
• capetown-faas-core on 50102
• database-abstraction-core on 50103
• documentation-core on 50101

Because documentation-core is now TypeDoc-backed, local startup also assumes the repo-root Node dependencies are installed with npm install or npm ci before the docs service is started.

Portal Web

apps/portal-web is the browser entrypoint for the active workspace experience. The Vite config targets the local backend and database abstraction services and serves the portal on 5173.

The Vite /dbcore proxy is local-development only. It allows the browser workspace to exercise database-backed flows against database-abstraction-core on 50103, but that route is intentionally not published by production nginx.

The main local portal commands are:

• npm --prefix apps/portal-web run dev
• npm --prefix apps/portal-web run build
• npm --prefix apps/portal-web run test:portal-web

The live browser entrypoints still boot from the slim workspace route files, and the active workspace lane is alpha3-only.

Smoke Paths

The repository currently uses a few explicit smoke entrypoints for the local stack:

• scripts/alpha3-frontend-smoke.mjs
• scripts/alpha3-frontend-smoke.ps1
• scripts/cashier-frontend-smoke.mjs
• scripts/stats-frontend-smoke.mjs
• scripts/stats-stack-up.ps1
• scripts/demo-run.ps1

The browser smoke defaults still point to http://127.0.0.1:5173, and the helper scripts use the current local service ports listed above.

Local Stack Shape

The local stack is not just a single frontend preview. It is a small multi-service development topology:

• portal web on 5173
• automation control on 50001
• documentation core on 50101
• capetown FaaS core on 50102
• database abstraction core on 50103

That topology is also reflected in the local dev scripts and smoke harnesses, so local development should be treated as a coordinated system rather than isolated app servers.

For the docs service specifically, a healthy local process is not the full success condition. The useful checks are:

• http://127.0.0.1:50101/ready
• http://127.0.0.1:50101/typedoc-status
• http://127.0.0.1:50101/

Current Behavior Notes

The active workspace runtime is now alpha3-only, so local workspaces boot through the isolated alpha3 lane instead of the retired alpha0/alpha1/alpha2 model.

Portal cards are manifest-driven and use shared login/session behavior, so local smoke and manual testing should focus on:

• card connection and disconnect behavior
• browser credential autocomplete
• workspace handoff links
• alpha3 shell theming and inspector toggles

Rebuild Notes

This is the current local-dev baseline for the rebuilt docs:

• the active local service ports
• the portal browser port and smoke defaults
• the main dev/test entrypoints
• the alpha3-only workspace runtime

Older runbooks and smoke matrices now belong in the external documentation archive.