Architecture

Architecture pages explain the system areas that future work must preserve or reshape before adding behavior. The repo manual makes this explicit: implementation work should evolve the codebase so the feature fits, and should stop when the current shape cannot hold the request cleanly [@manual]. This hub gives the shortest route through the architecture cluster instead of requiring readers to scan every page under architecture/.

The architecture topic has focused child neighborhoods for wiki behavior, lifecycle operations, agent runs, CLI behavior, repositories, local state, automation, setup, runtime resources, persistence, sources, and the viewer [@topics]. Read the page that owns the boundary you plan to change, then follow its links into guides, decisions, or reference pages.

Core Shape#

Start with Service boundaries. It explains the main dependency direction: CLI adapters enter through the app, workflows coordinate product operations, services own product verbs, stores own persistence, ports describe outside capabilities, and integrations implement those ports [@service-boundaries].

Composition root is the companion page for construction. It explains how src/codealmanac/app.py assembles stores, services, adapters, operation runners, and workflows into one application graph [@composition-root].

Request models explains the typed request objects that protect service and workflow boundaries from loose dictionaries and raw CLI shapes [@request-models].

Page-Writing Operations#

Lifecycle is the entry point for build, ingest, garden, sync, queued runs, operation execution, and mutation safety. Build, ingest, and garden are page-writing operation families; sync is a scanner that queues ingest work instead of writing pages itself [@lifecycle].

Use Operation runner when changing the shared run-execution path [@operation-runner]. Use Mutation safety when changing the checks that keep lifecycle writes inside the allowed wiki source files [@mutation-safety].

Read Side And Wiki Graph#

Wiki architecture is the entry point for page identity, path and file references, indexing, topics, health, and validation [@wiki-architecture].

Index refresh and search explains the derived SQLite read model, implicit refresh before read commands, FTS search, topic filters, and mention search [@index-search].

For authored wiki contracts, read Page identity, Path normalization and file refs, Topics DAG, and Health and validation. These pages define how Markdown routes, sources, topics, and validation fit together [@page-identity] [@path-normalization] [@topics-dag] [@health-validation].

Edges And Interfaces#

Use CLI adapter boundary and Terminal output for command entrypoints and rendering [@cli-adapter] [@terminal-output]. Use Agent runs for normalized harness execution and the Yoke harness boundary that serves Claude and Codex behind one adapter [@agent-runs]. Use Source resolution and runtime when changing ingest inputs or source adapters [@source-runtime].

Agents and manuals covers the packaged Yoke agents and writing references used by lifecycle runs, Setup automation and update covers setup-owned scheduler and update behavior, and Telemetry covers the narrow remote product-signal exception [@agents-manuals] [@setup-automation] [@telemetry]. Instruction installation covers the sibling setup concern: writing CLAUDE.md/AGENTS.md kernel instructions into a repository [@instruction-install].

Local state, Selection and root, and SQLite store boundaries explain repository selection, runtime paths, and persistence ownership [@local-state] [@selection-root] [@sqlite-stores]. Local viewer explains the browser UI that projects the same wiki, topics, files, and jobs [@local-viewer].