Wiki Architecture

Wiki architecture is the part of CodeAlmanac that turns the committed almanac/ tree into a navigable local knowledge base. The pages in this folder explain how Markdown paths become page identity, how file evidence becomes searchable references, how the derived index powers read commands, how topics form a DAG, and how health and validation keep the graph trustworthy [@page-identity] [@path-refs] [@index-search] [@topics-dag] [@health-validation].

Read this hub when changing page parsing, page links, source metadata, search, topic mutation, validation, or any feature that depends on the wiki graph. The topic graph treats wiki as an architecture neighborhood with child topics for page format, pages, health, search, index, and topics [@topics-file].

Reading Order#

Start with Page identity. It explains the path-based route contract: ordinary Markdown files use their path under almanac/, and README.md files become folder landing pages [@page-identity].

Then read Path normalization and file refs when the change touches sources: entries, file evidence, or codealmanac search --mentions. That page owns the normalization and escaped GLOB behavior that keeps path matching precise [@path-refs].

Use Index refresh and search for read commands. It explains the derived SQLite index, implicit refresh before search, show, topics, and health, FTS query shape, topic filtering, and mention search [@index-search].

Use Topics DAG for topic browsing or mutation commands. It explains index-backed topic reads, deterministic topics.yaml edits, page frontmatter rewrites, and cycle prevention [@topics-dag].

Finish with Health and validation when changing graph checks or lifecycle quality gates. It explains how health reports indexed problems and how validate turns source-shape, runtime-state, and graph checks into a pass/fail boundary [@health-validation].

Neighboring Contracts#

The exact authored page format lives in Frontmatter and sources and Links and routes. The broader concept is Local repo wiki, which explains why committed Markdown is the durable source while runtime databases are rebuildable local state.