epoch_forge/docs/architecture.md

1.4 KiB

Architecture and development

CLI parsing and rendering (`bin_efo`)
                 │
                 ▼
domain and persistence (`lib_efo`)
                 │
                 ▼
        `.epoch` and `epoch/*`

bin_efo defines the Clap command tree and presentation. lib_efo owns entities, statistics, identifiers, epochs, naming, and JSON persistence. New behavior should be a testable library operation with a thin CLI handler.

The design direction is to make repository paths explicit; replace truncating writes with temporary-file plus rename; add locking; remove unsafe cache accessors; separate styling from semantic output; and retain unknown custom metadata as the model becomes organisation-agnostic.

Phase 4's proposed persistence boundary is specified in the staging, history, and recovery design. It separates HEAD, the index, and the editable worktree, and defines the atomic transaction and migration rules that implementation must preserve. The proposal requires user approval before repository-format code changes begin.

Library tests currently cover parsing, statistics, display snapshots, and parts of entity/epoch behavior. CLI integration coverage is the main gap. Routine CI should run formatting, all-target workspace tests, strict Clippy, and a release build. Tarpaulin and rust_autobadges remain local significant-release-only tools. See AGENTS.md for contributor rules.