# timiagama/ecr architecture

> Architecture diagram of the GitHub repository timiagama/ecr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/timiagama/ecr
- Repository: https://github.com/timiagama/ecr

## Overview

ECR is a Markdown convention and TypeScript linter/CLI for checking stable document and section IDs, declared and inline references, and corpus consistency. The main workflow is a user running the CLI on a Markdown corpus: it loads documents, validates them through the public facade and per-document rules, then reports diagnostics or statistics. The README also describes agents using grep to navigate the resulting explicit references; this is a repository-text workflow, not a separate indexing service. Edges reflect shown imports/calls or README statements; unsampled CLI and validation details are not inferred.

Main entry points: [`src/cli.ts`](https://github.com/timiagama/ecr/blob/main/src/cli.ts) (CLI commands), [`src/per-document-visitor.ts`](https://github.com/timiagama/ecr/blob/main/src/per-document-visitor.ts) (Document visitor), [`src/identifier-grammar.ts`](https://github.com/timiagama/ecr/blob/main/src/identifier-grammar.ts) (Identifier grammar), [`src/ecr.ts`](https://github.com/timiagama/ecr/blob/main/src/ecr.ts) (ECR facade)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_cli["CLI commands<br/>[cli.ts]"]
  node_loader["Corpus loader<br/>[corpus-loader.ts]"]
  node_ignore["Ignore filtering<br/>[project-ignore.ts]"]
  node_statistics["Corpus statistics"]
  node_reporter["Diagnostic reporter"]
  node_supervisor["Process supervision<br/>[supervisor.ts]"]
end

subgraph group_engine["Validation engine"]
  node_ecr["ECR facade<br/>[ecr.ts]"]
  node_validator["Corpus validator"]
  node_visitor["Document visitor"]
end

subgraph group_rules["ECR rules"]
  node_identity["Document identity"]
  node_hierarchy["Section hierarchy"]
  node_references["References section"]
  node_inline["Inline references"]
end

subgraph group_support["Shared support"]
  node_grammar["Identifier grammar"]
  node_sourceform["Heading source form"]
  node_alignment["Source alignment"]
  node_metadata["Result schema<br/>[types.ts]"]
  node_meta["Meta-document filter<br/>[meta-documents.ts]"]
end

node_user(("CLI user"))
node_corpus["Markdown corpus"]
node_agent(("Coding agent"))

node_user -->|"runs"| node_cli
node_cli -->|"loads corpus"| node_loader
node_corpus -->|"provides Markdown"| node_loader
node_cli -->|"reads ignore rules"| node_ignore
node_cli -->|"validates corpus"| node_ecr
node_loader -->|"filters documents"| node_meta
node_ecr -->|"lints documents"| node_visitor
node_ecr -->|"validates corpus"| node_validator
node_validator -->|"checks inline references"| node_inline
node_visitor -->|"evaluates headings"| node_identity
node_visitor -->|"evaluates sections"| node_hierarchy
node_visitor -->|"evaluates declarations"| node_references
node_visitor -->|"evaluates prose"| node_inline
node_visitor -->|"parses identifiers"| node_grammar
node_identity -->|"parses DocIDs"| node_grammar
node_hierarchy -->|"checks SectionIDs"| node_grammar
node_references -->|"parses references"| node_grammar
node_inline -->|"parses inline IDs"| node_grammar
node_identity -->|"checks heading source"| node_sourceform
node_hierarchy -->|"checks heading source"| node_sourceform
node_references -->|"aligns source text"| node_alignment
node_cli -->|"computes statistics"| node_statistics
node_cli -->|"renders results"| node_reporter
node_cli -->|"manages execution"| node_supervisor
node_agent -->|"searches references"| node_corpus

click node_cli "https://github.com/timiagama/ecr/blob/main/src/cli.ts"
click node_loader "https://github.com/timiagama/ecr/blob/main/src/cli/corpus-loader.ts"
click node_ignore "https://github.com/timiagama/ecr/blob/main/src/cli/project-ignore.ts"
click node_statistics "https://github.com/timiagama/ecr/blob/main/src/cli/corpus-statistics.ts"
click node_reporter "https://github.com/timiagama/ecr/blob/main/src/cli/diagnostic-reporter.ts"
click node_supervisor "https://github.com/timiagama/ecr/blob/main/src/cli/supervisor.ts"
click node_ecr "https://github.com/timiagama/ecr/blob/main/src/ecr.ts"
click node_validator "https://github.com/timiagama/ecr/blob/main/src/corpus-validator.ts"
click node_visitor "https://github.com/timiagama/ecr/blob/main/src/per-document-visitor.ts"
click node_identity "https://github.com/timiagama/ecr/blob/main/src/document-identity-rule.ts"
click node_hierarchy "https://github.com/timiagama/ecr/blob/main/src/section-hierarchy-rule.ts"
click node_references "https://github.com/timiagama/ecr/blob/main/src/references-section-rule.ts"
click node_inline "https://github.com/timiagama/ecr/blob/main/src/inline-reference-rule.ts"
click node_grammar "https://github.com/timiagama/ecr/blob/main/src/identifier-grammar.ts"
click node_sourceform "https://github.com/timiagama/ecr/blob/main/src/heading-source-form.ts"
click node_alignment "https://github.com/timiagama/ecr/blob/main/src/source-alignment.ts"
click node_metadata "https://github.com/timiagama/ecr/blob/main/src/types.ts"
click node_meta "https://github.com/timiagama/ecr/blob/main/src/meta-documents.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_loader,node_ignore,node_statistics,node_reporter,node_supervisor,node_user toneBlue
class node_ecr,node_validator,node_visitor toneAmber
class node_identity,node_hierarchy,node_references,node_inline toneMint
class node_grammar,node_sourceform,node_alignment,node_metadata,node_meta toneRose
class node_corpus,node_agent toneIndigo
```

## Components

### CLI workflow

- [CLI commands](https://github.com/timiagama/ecr/blob/main/src/cli.ts): `src/cli.ts`
- [Corpus loader](https://github.com/timiagama/ecr/blob/main/src/cli/corpus-loader.ts): `src/cli/corpus-loader.ts`
- [Ignore filtering](https://github.com/timiagama/ecr/blob/main/src/cli/project-ignore.ts): `src/cli/project-ignore.ts`
- [Corpus statistics](https://github.com/timiagama/ecr/blob/main/src/cli/corpus-statistics.ts): `src/cli/corpus-statistics.ts`
- [Diagnostic reporter](https://github.com/timiagama/ecr/blob/main/src/cli/diagnostic-reporter.ts): `src/cli/diagnostic-reporter.ts`
- [Process supervision](https://github.com/timiagama/ecr/blob/main/src/cli/supervisor.ts): `src/cli/supervisor.ts`

### Validation engine

- [ECR facade](https://github.com/timiagama/ecr/blob/main/src/ecr.ts): `src/ecr.ts`
- [Corpus validator](https://github.com/timiagama/ecr/blob/main/src/corpus-validator.ts): `src/corpus-validator.ts`
- [Document visitor](https://github.com/timiagama/ecr/blob/main/src/per-document-visitor.ts): `src/per-document-visitor.ts`

### ECR rules

- [Document identity](https://github.com/timiagama/ecr/blob/main/src/document-identity-rule.ts): `src/document-identity-rule.ts`
- [Section hierarchy](https://github.com/timiagama/ecr/blob/main/src/section-hierarchy-rule.ts): `src/section-hierarchy-rule.ts`
- [References section](https://github.com/timiagama/ecr/blob/main/src/references-section-rule.ts): `src/references-section-rule.ts`
- [Inline references](https://github.com/timiagama/ecr/blob/main/src/inline-reference-rule.ts): `src/inline-reference-rule.ts`

### Shared support

- [Identifier grammar](https://github.com/timiagama/ecr/blob/main/src/identifier-grammar.ts): `src/identifier-grammar.ts`
- [Heading source form](https://github.com/timiagama/ecr/blob/main/src/heading-source-form.ts): `src/heading-source-form.ts`
- [Source alignment](https://github.com/timiagama/ecr/blob/main/src/source-alignment.ts): `src/source-alignment.ts`
- [Result schema](https://github.com/timiagama/ecr/blob/main/src/types.ts): `src/types.ts`
- [Meta-document filter](https://github.com/timiagama/ecr/blob/main/src/meta-documents.ts): `src/meta-documents.ts`

### Other components

- **CLI user**
- **Markdown corpus**
- **Coding agent**

## Connections

- CLI user → CLI commands: runs
- CLI commands → Corpus loader: loads corpus (evidence: `src/cli.ts`)
- Markdown corpus → Corpus loader: provides Markdown (evidence: `src/cli/corpus-loader.ts`)
- CLI commands → Ignore filtering: reads ignore rules (evidence: `src/cli.ts`)
- CLI commands → ECR facade: validates corpus (evidence: `src/cli.ts`)
- Corpus loader → Meta-document filter: filters documents (evidence: `src/cli/corpus-loader.ts`)
- ECR facade → Document visitor: lints documents (evidence: `src/ecr.ts`)
- ECR facade → Corpus validator: validates corpus (evidence: `src/ecr.ts`)
- Corpus validator → Inline references: checks inline references (evidence: `src/corpus-validator.ts`)
- Document visitor → Document identity: evaluates headings (evidence: `src/per-document-visitor.ts`)
- Document visitor → Section hierarchy: evaluates sections (evidence: `src/per-document-visitor.ts`)
- Document visitor → References section: evaluates declarations (evidence: `src/per-document-visitor.ts`)
- Document visitor → Inline references: evaluates prose (evidence: `src/per-document-visitor.ts`)
- Document visitor → Identifier grammar: parses identifiers (evidence: `src/per-document-visitor.ts`)
- Document identity → Identifier grammar: parses DocIDs (evidence: `src/document-identity-rule.ts`)
- Section hierarchy → Identifier grammar: checks SectionIDs (evidence: `src/section-hierarchy-rule.ts`)
- References section → Identifier grammar: parses references (evidence: `src/references-section-rule.ts`)
- Inline references → Identifier grammar: parses inline IDs (evidence: `src/inline-reference-rule.ts`)
- Document identity → Heading source form: checks heading source (evidence: `src/document-identity-rule.ts`)
- Section hierarchy → Heading source form: checks heading source (evidence: `src/section-hierarchy-rule.ts`)
- References section → Source alignment: aligns source text (evidence: `src/references-section-rule.ts`)
- CLI commands → Corpus statistics: computes statistics (evidence: `src/cli.ts`)
- CLI commands → Diagnostic reporter: renders results (evidence: `src/cli.ts`)
- CLI commands → Process supervision: manages execution (evidence: `src/cli.ts`)
- Coding agent → Markdown corpus: searches references (evidence: `README.md`)