Portal Web

Browser-first (tablet-first responsive) operator and SME interface.

Vite reference for this repo:

• ../../documentation/portal/vite-mental-model.md

Run locally

Node runtime: Node.js 20.x (any patch release in the v20 LTS line is acceptable).

1. Install dependencies:
   • npm --prefix apps/portal-web install
2. Start local backend stack first (core API on 50102), then run:
   • npm --prefix apps/portal-web run dev -- --host 0.0.0.0 --port 5173
3. Open:
   • http://127.0.0.1:5173/ for the new portal landing page (six cards, including Admin).
   • http://127.0.0.1:5173/stats/ for the statistics workspace.
   • http://127.0.0.1:5173/cashier/ for the cashier workspace.
   • http://127.0.0.1:5173/admin/ for statistics and cashier company-map setup, connection testing, database discovery, and live-vs-mock runtime diagnostics.
   • http://127.0.0.1:5173/under-development/ for explicit placeholder pages while unfinished workspaces are being rebuilt.

Recommended on Linux/Windows:

• Use any Node version manager (nvm, nvm-windows, asdf, fnm) that can install Node 20.x.
• For reproducibility, this repo also includes .nvmrc and .node-version at root with 20.18.0.

The local Vite dev server proxies these API routes to the running backend: /apps, /companies, /ingest, /responses, /operations, /contracts, /sessions, /ready, /state, /sender, and /dbcore.

/dbcore is a local-development proxy only. Production nginx intentionally returns 404 for /dbcore so database-abstraction-core stays an internal adapter service; production browser flows should use published capetown-faas-core routes.

Write-safety controls in the UI:

• Session write lock controls mutating actions for the active card session (the active app token/session).
• System right lock is a global write freeze across all cards and is controlled from the top toolbar.
• Session write lock starts enabled by default so write actions are initially blocked per-card.
• Uncheck Session write lock in the toolbar to allow writes for the active card.
• Use Enable System Right Lock for a global emergency write freeze.
• Cashier day_end still requires backend-side runtime enablement with CASHIER_ENABLE_DAY_END_WRITE=1; the frontend alone cannot turn that write path on.

Operational controls:

• Request Shutdown submits a control intent through routing_key: system and follows /system/shutdown for live state.
• Each control/workflow response includes metadata.system_shutdown when backend workers complete, enabling in-flight sessions to show shutdown status immediately.
• Operator UI state (active card, selected company, read-only mode, and session tokens) is persisted in browser cookies for continuity across reloads.

Planned stack

• Shared components with portal-mobile
• Auth + message compose + status feed
• Queue-backed submission and response polling
• Card runtime scaffold for six apps: Debtors, CashierClient, Creditors, ICAPV, Statistics, and Admin setup.
• Tablet-first layout default, with desktop scaling handled via responsive breakpoints
• Single ingress endpoint: automation contracts and /ingest queue path

Structure

• index.html portal landing entry.
• admin/index.html admin setup entry.
• cashier/index.html cashier workspace entry.
• stats/index.html statistics workspace entry.
• under-development/index.html explicit under-development workspace entry.
• src/ application source (app.ts for legacy-route retirement redirects, landing.ts for landing flow, cashier.ts for cashier, stats.ts for statistics, admin.ts for admin setup, debtors.ts for debtors, under-development.ts for unfinished workspaces).