Skip to content

development.md

Latest commit

 

History

History
131 lines (107 loc) · 8.68 KB

development.md

File metadata and controls

131 lines (107 loc) · 8.68 KB
Raw

Development Guide

This map routes contributors and agents to the implementation and its authorities. AGENTS.md owns repository rules; CONTRIBUTING.md owns build gates and contribution workflow.

Choose context by task

Read the relevant row, then the specific service, migration, and test involved. ADRs record decisions; format documents specify portable bytes; source and tests show what is implemented. Roadmap owns milestone status.

Task Start in crates/consolebook-server/src/ Supporting context
Process, storage, diagnostics main.rs, data_dir.rs, storage.rs, doctor.rs Architecture, ADR 0003, ADR 0016
Backups and restore backup.rs, scheduler.rs, restore.rs, serve_lock.rs ADR 0006
Setup, login, recovery setup.rs, users.rs, sessions.rs, secrets.rs ADR 0004
Capabilities and assignments capabilities.rs, assignments.rs, draft_access.rs ADR 0010, Domain model
Program configuration programs.rs, programs/content.rs, programs/persistence.rs, program_export.rs ADR 0007, Program format
Enrollment and training sessions enrollments.rs, lifecycle.rs, training_sessions.rs, session_membership.rs, session_time.rs ADR 0008, ADR 0009, ADR 0018
Drafts and review evaluation_drafts.rs, draft_content.rs, draft_review.rs ADR 0008, ADR 0010
Finalization and canonical bytes finalization.rs, canonical.rs, record_envelope.rs Integrity, ADR 0011
Acknowledgments and amendments acknowledgments.rs, amendments.rs Domain model, ADR 0012
Summaries and signoffs summaries.rs, task_signoffs.rs ADR 0013, ADR 0021
Record exports record_export.rs, export_verify.rs, zip_container.rs ADR 0014, Export format
Trainee packets trainee_packet.rs, packet_verify.rs ADR 0015, ADR 0017, Packet format
Retention policy and holds retention.rs, retention/, retention_http.rs ADR 0020, Operator guide; disposition execution remains #64
Web shell and HTTP http.rs, web_assets.rs, notices.rs, domain *_http.rs modules ADR 0005, web map below
Preview operations Separate host installation Preview runbook

lib.rs exposes the library modules. Integration tests in crates/consolebook-server/tests/ are named by capability; migration files in crates/consolebook-server/migrations/ own schema, constraints, and triggers. Read both when changing a persisted contract.

Packet membership and timeline verification tests live in tests/trainee_packet/pin_history.rs; the parent packet test module owns shared fixtures and archive-editing helpers.

tests/enrollment_event_schema.rs covers fresh and upgraded lifecycle-event storage, retained-history preservation, and fail-closed migration of malformed legacy rows. ADR 0018 explains the migration 0014 diagnostic and repair boundary.

Runtime flow

Svelte route -> web/src/lib/api.ts -> /api/* HTTP adapter
             -> domain service -> SQLx -> SQLite constraints and triggers

main.rs owns the CLI. serve resolves the data directory, acquires the serve lock, opens and migrates SQLite, verifies connection invariants, starts the backup scheduler, and serves Axum. http.rs owns router registration, the current-user extractor, and error translation. Larger handler groups live in programs_http.rs, training_http.rs, drafts_http.rs, and exports_http.rs. Policy belongs in services; persisted constraints also have database backstops. audit.rs owns typed audit events; notices.rs owns recipient-scoped notices.

sessions.rs owns login sessions; training_sessions.rs owns periods of training. Do not infer policy from a role name or a UI guard.

Application-owned write transactions use storage::write_tx and await rollback on refusal through storage::refuse (or directly for outcome/optional returns). Read-only snapshots remain deferred. ADR 0019 owns the transaction discipline and contention limits; tests/write_transactions.rs and its domain child modules own concurrency proof.

programs.rs owns policy and transaction orchestration; programs/content.rs owns configuration vocabulary and validation; programs/persistence.rs owns content persistence and caller-transaction inserts. Public imports remain under programs. A transaction's presence alone does not prove authorization shares its snapshot; check where the decision is evaluated. See the domain-model qualification.

Web map

The UI is a client-routed SPA. web/src/routes/+layout.ts guards setup and authentication; +layout.svelte owns navigation and shared styling. web/src/lib/api/transport.ts owns shared same-origin requests and typed errors. web/src/lib/api.ts keeps compatible legacy imports and domain calls; web/src/lib/api/retention.ts owns retention contracts. web/src/lib/retention/ owns policy editing, hold editing, and authority controls. web/src/lib/api/signoffs.ts owns the task-signoff read contract (#49) and web/src/lib/signoffs/ its read-only presentation. web/src/lib/editor/ contains program-authoring components.

web/e2e/fixtures.ts supplies each scenario's server, base URL, and setup code. server.ts owns process startup and scratch-data cleanup; server.spec.ts checks startup failures, listener ownership, and shutdown. Keep scenario data and assertions in their own specs.

Route Ownership
/setup, /login, /reset Installation and authentication entry
/ Capability-sensitive status, notices, administration, session/review queues, installation exports
/programs/** Program authoring, comparison, publishing, enrollment
/enrollments/[id] Lifecycle, assignments, sessions, summaries, signoffs, exports
/drafts/[id] Authoring, review, finalized presentation, acknowledgment, amendments
/records Trainee's own timeline, packet downloads, and their own complete task-signoff history
/retention Explicit authority, versioned policies, and attributed holds; no disposition execution

Local workflow

From the repository root:

(cd web && npm ci && npm run build)
cargo run -p consolebook-server -- --data-dir ./data serve

Open http://127.0.0.1:7770 on the same machine. For a fresh installation, use the setup code printed by the server, create invented agency/admin data, then sign in. Use a separate empty data directory for a disposable preview. The published preview already occupies port 7770 on its host; choose another serve --bind 127.0.0.1:PORT there.

For live UI editing, run npm run dev in web/ with a local Rust server. vite.config.ts proxies /api to port 7770; adjust the target when using a different local port. Check that target before using the dev UI on a shared host. npm run preview alone serves static files without that API proxy.

web_assets.rs uses the build in web/build/: release builds embed it; debug builds read it from disk. A missing build serves the explicit "interface not embedded" notice. Rebuild web then Rust for release packaging. Node.js is never required by the deployed binary.

See CONTRIBUTING.md for the full verification sequence and browser prerequisites. cargo run -p consolebook-server -- --help lists CLI operations; export verify <archive> reads a file without opening an installation.