Architecture and contributing
Trace the product by responsibility before changing it. The generator produces static reader files; the optional editor is a separate authenticated Node.js process. This is documentation of the pinned implementation, not a stable internal API promise.
Choose a trace
| Question | Source guide |
|---|---|
| How do files become routes? | Build internals |
| Where do nav and search come from? | Build internals |
| How is a request authorized? | Editor internals |
| What does Save or Publish change? | Editor internals |
| How do I reproduce a change? | Contributor workflow |
| What state needs preserving? | Storage and formats |
Build internals follows input selection, frontmatter, route registration, output clearing, page rendering, navigation, search, special pages and watching. Editor internals follows Host/Origin/body gates, sessions and CSRF, role/section access, file actions, management stores and staged publication. Contributor workflow connects those contracts to isolated fixtures and review.
Boundaries that affect a change
| Boundary | Review consequence |
|---|---|
| Title-derived routes | Inspect real output and collisions |
| Shared private stores | Preserve validation and locking |
| Embedded editor controllers | Inspect actual editor HTML |
| Browser-local drafts | Test recovery in browser state |
| Reader/preview differences | Review final generated reader |
| Two publication renames | Preserve stage/live-state reporting |
| In-memory sessions/jobs | Do not assume durable clustering |
Do not infer a missing behavior from a module name. Ordinary Markdown Save and revision-aware metadata updates have different contracts. Publisher checks are narrower than a full artifact acceptance test. Watch targets do not include every runtime/configuration input. The detailed trace pages explain these differences.
Review a proposed change
First reproduce the issue in an isolated source/output fixture. Identify the source branch and existing assertions, add a focused test, then exercise the affected browser state when appearance or interaction changes. Retain the runtime, configuration and final results. A passing source-string assertion does not replace a behavior test, and a passing behavior test does not replace actual pixel inspection.
Changes to authoring permissions, outbound requests, stored state or output selection need a review of the adjacent boundary as well as the visible feature. Keep private sample accounts and unrelated runtime data out of shared fixtures. Validation limits identifies what the handbook’s local evidence does not certify.