vwiebe/conductor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
conductor/docs/DEVELOPER_GUIDE.md
Victor Wiebe ade2b10033
Some checks failed
Release production image / production-image (push) Has been cancelled
Details
Add production packaging and operations
2026-08-07 16:48:40 -04:00

2.4 KiB
Raw Blame History

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 v0.1.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:

  1. Shared JSON schema.
  2. Frontend TypeScript model and authoring UI.
  3. Backend semantic validation.
  4. Preview and published runtime behavior.
  5. Unit/integration/browser coverage.
  6. 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.