epoch_forge/docs/architecture.md

37 lines
1.7 KiB
Markdown

# Architecture and development
```text
CLI (`bin_efo`) TUI (`tui_efo`)
│ │
└─────┬──────┘
▼
domain and persistence (`lib_efo`)
│
▼
`.epoch` and `epoch/*`
```
`bin_efo` defines the Clap command tree and presentation. `tui_efo` owns only
its input loop, view state, and terminal presentation. `lib_efo` owns entities,
statistics, identifiers, epochs, naming, and JSON persistence. New behavior
should be a testable library operation with thin CLI and TUI adapters.
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 approved 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. Versioned manifest and
snapshot types now isolate that future format from the active legacy reader.
The approved [first-pass TUI contract](tui-design.md) adds a separate read-only
format-2 browser without creating another persistence path.
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.