Developer Guide

Architecture

The canonical ProjectDocument is shared by Visual Editor, JSON Editor, Preview, validation, persistence, and publication snapshots. React owns authoring and ephemeral runtime state; Express owns authentication, authorization, persistence, credential resolution, proxy policy, validation, and publication execution. SQLite is the v1.0.0 durable store.

Development uses two containers/processes for fast React/backend iteration. Production uses Dockerfile.production: a multi-stage build copies compiled frontend assets and compiled backend output into one minimal runtime image. Express serves API and SPA fallbacks from the same origin.

Local commands

cd frontend && npm ci && npm test -- --watchAll=false --runInBand && npm run build
cd ../backend && npm ci && npm test
cd .. && npm ci && npm run test:schema && npm run test:governance

Use the deterministic mock stack and Playwright commands in docs/RELEASE_VALIDATION.md for browser acceptance.

Database and migrations

backend/src/db/init.ts applies idempotent startup schema creation/migrations. New migrations must preserve existing data and have explicit downgrade/rollback implications. Tests select isolated databases through CONDUCTOR_DATA_DIR.

Never copy the live WAL database as a backup. backend/src/scripts/backupDatabase.ts uses better-sqlite3's online backup facility.

Security invariants

Every admin mutation requires an authenticated admin and CSRF validation.
Published execution resolves actions and credentials from server-owned snapshots.
Proxy destinations are default-deny for internal/private networks unless an exact reviewed origin is allowed.
Credential plaintext must not enter project JSON, browser responses, errors, or execution history.
Production refuses missing/invalid encryption and session keys.
New production files must work with a non-root UID/GID 10001 and read-only root filesystem.

Adding canonical behavior

Update together:

Shared JSON schema.
Frontend TypeScript model and authoring UI.
Backend semantic validation.
Preview and published runtime behavior.
Unit/integration/browser coverage.
Schema examples, user/operator docs, roadmap, and traceability.

Release artifacts

Run scripts/release-image.sh for immutable OCI tags. scripts/test-production.sh performs the disposable same-origin/backup/restore gate. Release publication details are in docs/RELEASE.md.

2.4 KiB Raw Blame History