# andrewyng/context-hub architecture

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

- Interactive diagram: https://gitdiagram.com/andrewyng/context-hub
- Repository: https://github.com/andrewyng/context-hub

## Overview

Context Hub is a curated, versioned documentation and agent-skill browser distributed as a CLI and MCP server. The main workflow is to search the registry, resolve a selected document’s language/version and reference files, fetch content, and return or save it; agents can add persistent local annotations and send feedback. The graph also includes content-index construction and optional telemetry. Relationships are limited to the README and supplied source excerpts/index; unsampled command internals are represented only where documented.

Main entry points: [`cli/src/lib/registry.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/registry.js) (Registry and resolver), [`cli/src/index.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/index.js) (CLI dispatcher), [`cli/src/commands/get.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/get.js) (Get command), [`cli/src/lib/telemetry.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/telemetry.js) (Feedback API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI dispatcher<br/>[index.js]"]
  node_mcp["MCP server<br/>[server.js]"]
  node_mcp_tools["MCP tools<br/>[tools.js]"]
end

subgraph group_content["Content discovery"]
  node_search["Search command<br/>[search.js]"]
  node_registry["Registry and resolver<br/>[registry.js]"]
  node_bm25["BM25 ranking<br/>[bm25.js]"]
  node_normalize["Language normalization<br/>[normalize.js]"]
  node_build["Content index builder<br/>[build.js]"]
  node_frontmatter["Frontmatter parser<br/>[frontmatter.js]"]
end

subgraph group_fetch["Fetch and learning"]
  node_get["Get command<br/>[get.js]"]
  node_annotations[("Local annotations<br/>[annotations.js]")]
  node_annotate["Annotation command<br/>[annotate.js]"]
end

subgraph group_runtime["Runtime services"]
  node_cache[("Registry and document cache<br/>[cache.js]")]
  node_config["Configuration<br/>[config.js]"]
  node_output["Output formatting<br/>[output.js]"]
end

subgraph group_feedback["Feedback and signals"]
  node_feedback["Feedback command<br/>[feedback.js]"]
  node_telemetry["Feedback API client<br/>[telemetry.js]"]
  node_analytics["Usage analytics<br/>[analytics.js]"]
  node_identity["Anonymous identity<br/>[identity.js]"]
end

node_developer(("Agent or user"))
node_feedback_api["Feedback service"]
node_analytics_service["PostHog"]
node_content_sources[("Content sources")]

node_developer -->|"runs commands"| node_cli
node_developer -->|"uses tools"| node_mcp
node_cli -->|"registers"| node_search
node_cli -->|"registers"| node_get
node_cli -->|"registers"| node_build
node_cli -->|"registers"| node_feedback
node_cli -->|"registers"| node_annotate
node_search -->|"searches entries"| node_registry
node_registry -->|"loads registries"| node_cache
node_registry -->|"reads sources"| node_config
node_registry -->|"ranks matches"| node_bm25
node_registry -->|"normalizes language"| node_normalize
node_build -->|"parses metadata"| node_frontmatter
node_build -->|"indexes content"| node_content_sources
node_get -->|"resolves entry"| node_registry
node_get -->|"fetches files"| node_cache
node_get -->|"reads notes"| node_annotations
node_get -->|"formats result"| node_output
node_annotate -->|"saves notes"| node_annotations
node_mcp -->|"registers tools"| node_mcp_tools
node_mcp_tools -->|"searches and resolves"| node_registry
node_mcp_tools -->|"fetches files"| node_cache
node_mcp_tools -->|"reads or writes"| node_annotations
node_feedback -->|"resolves entry"| node_registry
node_feedback -->|"sends rating"| node_telemetry
node_telemetry -->|"reads preferences"| node_config
node_telemetry -->|"gets client identity"| node_identity
node_telemetry -->|"posts feedback"| node_feedback_api
node_cli -->|"tracks usage"| node_analytics
node_search -->|"tracks searches"| node_analytics
node_analytics -->|"checks opt-out"| node_telemetry
node_analytics -->|"identifies events"| node_identity
node_analytics -->|"sends events"| node_analytics_service

click node_cli "https://github.com/andrewyng/context-hub/blob/main/cli/src/index.js"
click node_mcp "https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/server.js"
click node_mcp_tools "https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/tools.js"
click node_search "https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/search.js"
click node_registry "https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/registry.js"
click node_bm25 "https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/bm25.js"
click node_normalize "https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/normalize.js"
click node_build "https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/build.js"
click node_frontmatter "https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/frontmatter.js"
click node_get "https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/get.js"
click node_cache "https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/cache.js"
click node_config "https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js"
click node_annotations "https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/annotations.js"
click node_annotate "https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/annotate.js"
click node_output "https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/output.js"
click node_feedback "https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/feedback.js"
click node_telemetry "https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/telemetry.js"
click node_analytics "https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/analytics.js"
click node_identity "https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/identity.js"

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_mcp,node_mcp_tools,node_developer toneBlue
class node_search,node_registry,node_bm25,node_normalize,node_build,node_frontmatter,node_content_sources toneAmber
class node_get,node_annotations,node_annotate toneMint
class node_cache,node_config,node_output toneRose
class node_feedback,node_telemetry,node_analytics,node_identity,node_feedback_api,node_analytics_service toneIndigo
```

## Components

### User entry points

- [CLI dispatcher](https://github.com/andrewyng/context-hub/blob/main/cli/src/index.js): `cli/src/index.js`
- [MCP server](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/server.js): `cli/src/mcp/server.js`
- [MCP tools](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/tools.js): `cli/src/mcp/tools.js`

### Content discovery

- [Search command](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/search.js): `cli/src/commands/search.js`
- [Registry and resolver](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/registry.js): `cli/src/lib/registry.js`
- [BM25 ranking](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/bm25.js): `cli/src/lib/bm25.js`
- [Language normalization](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/normalize.js): `cli/src/lib/normalize.js`
- [Content index builder](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/build.js): `cli/src/commands/build.js`
- [Frontmatter parser](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/frontmatter.js): `cli/src/lib/frontmatter.js`

### Fetch and learning

- [Get command](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/get.js): `cli/src/commands/get.js`
- [Local annotations](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/annotations.js): `cli/src/lib/annotations.js`
- [Annotation command](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/annotate.js): `cli/src/commands/annotate.js`

### Runtime services

- [Registry and document cache](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/cache.js): `cli/src/lib/cache.js`
- [Configuration](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js): `cli/src/lib/config.js`
- [Output formatting](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/output.js): `cli/src/lib/output.js`

### Feedback and signals

- [Feedback command](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/feedback.js): `cli/src/commands/feedback.js`
- [Feedback API client](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/telemetry.js): `cli/src/lib/telemetry.js`
- [Usage analytics](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/analytics.js): `cli/src/lib/analytics.js`
- [Anonymous identity](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/identity.js): `cli/src/lib/identity.js`

### Other components

- **Agent or user**
- **Feedback service**
- **PostHog**
- **Content sources**

## Connections

- Agent or user → CLI dispatcher: runs commands (evidence: `README.md`)
- Agent or user → MCP server: uses tools (evidence: `README.md`)
- CLI dispatcher → Search command: registers (evidence: `cli/src/index.js`)
- CLI dispatcher → Get command: registers (evidence: `cli/src/index.js`)
- CLI dispatcher → Content index builder: registers (evidence: `cli/src/index.js`)
- CLI dispatcher → Feedback command: registers (evidence: `cli/src/index.js`)
- CLI dispatcher → Annotation command: registers (evidence: `cli/src/index.js`)
- Search command → Registry and resolver: searches entries (evidence: `cli/src/commands/search.js`)
- Registry and resolver → Registry and document cache: loads registries (evidence: `cli/src/lib/registry.js`)
- Registry and resolver → Configuration: reads sources (evidence: `cli/src/lib/registry.js`)
- Registry and resolver → BM25 ranking: ranks matches (evidence: `cli/src/lib/registry.js`)
- Registry and resolver → Language normalization: normalizes language (evidence: `cli/src/lib/registry.js`)
- Content index builder → Frontmatter parser: parses metadata (evidence: `cli/src/commands/build.js`)
- Content index builder → Content sources: indexes content (evidence: `README.md`)
- Get command → Registry and resolver: resolves entry (evidence: `cli/src/commands/get.js`)
- Get command → Registry and document cache: fetches files (evidence: `cli/src/commands/get.js`)
- Get command → Local annotations: reads notes (evidence: `cli/src/commands/get.js`)
- Get command → Output formatting: formats result (evidence: `cli/src/commands/get.js`)
- Annotation command → Local annotations: saves notes (evidence: `cli/src/commands/annotate.js`)
- MCP server → MCP tools: registers tools (evidence: `cli/src/mcp/server.js`)
- MCP tools → Registry and resolver: searches and resolves (evidence: `cli/src/mcp/tools.js`)
- MCP tools → Registry and document cache: fetches files (evidence: `cli/src/mcp/tools.js`)
- MCP tools → Local annotations: reads or writes (evidence: `cli/src/mcp/tools.js`)
- Feedback command → Registry and resolver: resolves entry (evidence: `cli/src/commands/feedback.js`)
- Feedback command → Feedback API client: sends rating (evidence: `cli/src/commands/feedback.js`)
- Feedback API client → Configuration: reads preferences (evidence: `cli/src/lib/telemetry.js`)
- Feedback API client → Anonymous identity: gets client identity (evidence: `cli/src/lib/telemetry.js`)
- Feedback API client → Feedback service: posts feedback (evidence: `cli/src/lib/telemetry.js`)
- CLI dispatcher → Usage analytics: tracks usage (evidence: `cli/src/index.js`)
- Search command → Usage analytics: tracks searches (evidence: `cli/src/commands/search.js`)
- Usage analytics → Feedback API client: checks opt-out (evidence: `cli/src/lib/analytics.js`)
- Usage analytics → Anonymous identity: identifies events (evidence: `cli/src/lib/analytics.js`)
- Usage analytics → PostHog: sends events (evidence: `cli/src/lib/analytics.js`)
