epoch_forge/docs/architecture.md

33 lines
1.4 KiB
Markdown

# Architecture and development
```text
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](staging-design.md). 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](../AGENTS.md) for contributor rules.