Victor Wiebe
ade2b10033
Some checks failed
Release production image / production-image (push) Has been cancelled
48 lines
2.4 KiB
Markdown
48 lines
2.4 KiB
Markdown
# 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
|
|
|
|
```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`.
|