Architecture

OpenCanon is a local service, isolated project runtimes, typed Project Canon, and clients that share one versioned API for human-readable docs, agent-ready context, and runtime enforcement.

Layout

project layout

tree

opencanon/

areas/

changes/

conventions/

specs/

fixtures/

docs/opencanon/

areas/

canon/

changes/

specs/

impact-surfaces.json

.gitignore

.opencanon/

state.sqlite

cache/

indexes/

~/.opencanon/

service.json

runtime/

Boundaries

Workspace packages are the development source for @opencanon/cli, @opencanon/core, @opencanon/runtime, @opencanon/service-contracts, @opencanon/distribution, @opencanon/engine, @opencanon/observability, and @opencanon/validators.
The installed runtime owns the CLI, updater, local service, project runtimes, native engine, and local API. Agent skills and entry files are text guidance over that runtime.
Repository definitions live in opencanon/. Generated Markdown is derived from those definitions and checked by Doctor for drift.

Discovery

Inside a Git repository, discovery is Git-backed. .gitignore is honored, then OpenCanon applies projectFilePatterns, ignore, maxFiles, and maxFileSizeKb. Filesystem discovery is available as an explicit mode for tests and benchmarks; OpenCanon does not silently hide discovery failures.

Graph Index

The engine extracts TS/JS symbols, references, calls, imports, literals, diagnostics, duplicates, and Python facts into local SQLite state. CLI graph commands and validators read the same index, so scoped searches, caller/callee inspection, and graph-backed validators share one source of repository facts. Rust crates, Cargo dependencies, npm dependencies, and Python dependency metadata are also discovered for generated authoring constants.

Generated authoring types

The project runtime keeps gitignored authoring files fresh under .opencanon/generated/. Generated files expose typed constants for workspace packages, import specifiers, npm dependencies, Rust crates, Cargo dependencies, and Python dependencies. Fixture virtual projects can still be type-checked in an editor without committing generated state.

These generated types are deliberately small. OpenCanon does not generate per-file symbol, literal, caller, or callee maps by default because those make TypeScript language servers slow in large repositories. Validators still read precise facts at runtime from ctx.facts and ctx.graph.

Strict prerequisites

Runtime-backed commands are strict about prerequisites: Node version, installed runtime layout, native engine binary, configured cache directory, Project Canon source, generated docs, and referenced Markdown headings. Invalid configuration is a hard failure for normal context and validate commands; doctor reports the same diagnostics and offers safe fixes.