Development¶
Use Python 3.12 with uv for the backend and Node.js 24 for frontend development. Run commands from the repository root unless a different directory is shown. The getting started guide covers the full local Kubernetes deployment.
Source map¶
| Directory | Responsibility |
|---|---|
backend/ |
Gateway, sessions, permissions, registry, chat and migrations |
upstreams/ |
WooCommerce adapter, policy server and shipping server |
dashboard/ |
React and TypeScript dashboard |
docker/wordpress/ |
Store image, original product artwork and repeatable seed |
deploy/ |
Helm resources and local/production values |
scripts/ |
Cluster, release, backup and verification commands |
tests/ |
Unit, protocol, browser and deployed acceptance checks |
examples/ |
Independent MCP reference agent |
docs/ and mkdocs.yml |
Public documentation content and navigation |
Read the system design before changing cross-service behavior. The API and environment reference describes the frontend/backend contract. Generated .venv, .tools, .runtime, build outputs and private .secrets are local support directories, not application source.
Install and check¶
uv sync --frozen
uv run pytest -q
uv run ruff check backend upstreams tests scripts examples
Set-Location dashboard
npm ci
npm run build
Set-Location ..
.tools/helm.exe lint deploy/chart -f deploy/values-local.yaml
.tools/helm.exe lint deploy/chart -f deploy/values-prod.yaml
Helm is installed under .tools by bootstrap or scripts/install-tools.ps1. The frontend build type-checks before bundling. Its font preparation step downloads Switzer on a fresh installation; visual provenance documents the font source and licensing.
The PostgreSQL concurrency and activity-aggregation cases need TEST_POSTGRES_URL pointing to a disposable PostgreSQL database. They are skipped when that variable is absent. CI supplies a dedicated PostgreSQL service. Do not point test fixtures at the deployed application's database. Linux-specific schema memory checks run on Linux; Windows checks still exercise input and deadline guards.
Work on the dashboard¶
With the local deployment running:
Vite proxies API requests to the local console ingress. Use the complete deployment for final verification and demonstrations.
After source changes, rebuild the images and roll out the chart:
These commands change the running local release. Follow the operations guide for backups, upgrades, migrations and rollback. A Helm rollback does not rewind database contents.
Run deployed checks deliberately¶
The integration harnesses require the running cluster and private credentials in .secrets. They are not read-only checks. Acceptance tests create users and keys, alter registry state and exercise real services; the checkout harness creates a product and order. Run them while other clients are idle, with synthetic store data.
uv run python -m tests.acceptance
uv run playwright install chromium
uv run python -m tests.browser_ui
uv run python -m tests.browser_invitation
uv run python -m tests.browser_visual
The acceptance harness calls all three upstreams over MCP and checks hidden writes, disabled servers, SSRF, revocation and audit isolation. UI regression tests combine real sign-in with browser response fixtures for reproducible failure and race conditions, without calling Gemini. Visual checks inspect the deployed pages at widths from 320 to 1440 px. Runtime evidence stays private under .runtime; harness-created API keys are revoked during cleanup.
The invitation check accepts real invitations and changes the browser session. Use a separate browser profile for an interactive administrator session while it runs.
For accessibility checks with browser-local API fixtures:
$env:HARBOR_URL = 'http://harbor.localhost:8080'
uv run python -m tests.browser_accessibility
uv run python -m tests.browser_observability
Remove-Item Env:HARBOR_URL
These harnesses can also target a running frontend preview. They do not send application mutations or provider requests. The Activity checks cover metrics, filtering, personal scope and failure recovery.
The following checks use a live Gemini API key and consume quota. The browser acceptance flow also submits a real test checkout:
tests.browser_acceptance --audit-only writes a separate activity-only report. It does not establish that the complete checkout and chat journey passed.
Testing a public deployment¶
Use the public console and store URLs together. Copy that server's private development.json into a protected, Git-excluded local directory; the example uses .secrets/oci/production. This file contains the live credentials, so do not substitute the local development file or publish it with the reports.
$env:HARBOR_URL = 'https://harbor.satwiksps.site'
$env:HARBOR_STORE_URL = 'https://store.harbor.satwiksps.site'
$env:HARBOR_TEST_CREDENTIALS = (Resolve-Path '.secrets/oci/production/development.json').Path
$env:HARBOR_TEST_OUTPUT_DIR = Join-Path (Get-Location) ('.runtime/public-' + (Get-Date -Format yyyyMMdd-HHmmss))
uv run python -m tests.acceptance
uv run python -m tests.browser_invitation
uv run python -m tests.browser_visual
uv run python -m tests.external_agent --inspector-only
Run the Gemini/checkout commands above afterward when a synthetic product and order are appropriate. The harnesses create test members, revoke temporary keys and keep reports separate from local checks. Checkout records remain in the demonstration store. Run suites sequentially and retain failed reports alongside successful reruns.
These settings apply to the deployed Python harnesses, not every operational script. Local recovery and failure scripts still target the local cluster; review their context before using any operation against a VPS. Clear the four environment variables when returning to local testing.
External client verification¶
The external client guide describes MCP Inspector and an independent SDK agent with no backend imports. The sanitized evidence records a successful run across all three upstreams for order 25. Gemini CLI is not a claimed passing client.
The verification record lists executed checks, their environment and limitations. The audit record maps corrections to reported findings. Historical passing results are evidence for those runs, not a substitute for checking a new change.
CI and scope¶
The application CI job runs locked dependency installation, Python checks, disposable PostgreSQL cases, recovery and credential-preparation guards, the dashboard build, and Activity/accessibility browser fixtures against that build. Separate jobs lint/render the Helm chart and build all three images. The image job also probes the authentication memory budget in a constrained container.
The system deliberately uses one store, one gateway replica and process-local rate limits. The public deployment uses TLS, secure cookies, cluster Secret encryption and protected backups. Production values remain a template that must be adapted for each target. Schema migrations are forward-only until an explicit rollback migration exists.
Keep credentials, raw runtime evidence, recordings and private project material outside commits. Before sharing a demo, use the walkthrough checklist to review it for passwords, keys and invitation tokens.