# 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

```bash
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`.