epoch_forge/docs/architecture.md

1.9 KiB

Architecture and development

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. It separates HEAD, the index, and the editable worktree, and defines the atomic transaction rules that implementation must preserve. The sole pre-release repository format is version 1.0; its structured major/minor discriminator leaves room for explicit 1.x migrations without retaining an unreleased prototype reader. The approved TUI browser contract adds a separate read-only repository browser without creating another persistence path.

Library tests cover parsing, statistics, display snapshots, entity/epoch behavior, and repository transactions. CLI behavior is covered by subprocess integration workflows; Tarpaulin excludes those thin adapters because its ptrace backend cannot reliably attribute child-process execution. 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.