# blackx16/okf-wiki-template architecture

> Architecture diagram of the GitHub repository blackx16/okf-wiki-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blackx16/okf-wiki-template
- Repository: https://github.com/blackx16/okf-wiki-template

## Overview

1. **What this repo is**
   - This is a **filesystem-first OKF wiki template**: the knowledge base lives entirely in Markdown/YAML files, not in a database or proprietary wiki backend.
   - The architecture is optimized for **LLM agents** to read, write, validate, and traverse knowledge deterministically.

2. **Core storage boundary**
   - The main boundary is between **immutable source material** in `raw/` and **curated knowledge** in `wiki/`.
   - `raw/` holds inbound documents by source type: `articles/`, `github/`, `notes/`, `papers/`, `tutorials/`, `youtube/`.
   - The repo treats `raw/` as write-protected input: agents read from it but do not edit it.

3. **Knowledge layers inside `wiki/`**
   - `wiki/sources/` contains processed reading notes derived from raw inputs.
   - `wiki/concepts/` contains synthesized abstractions that combine multiple sources into a durable concept page.
   - `wiki/entities/` stores structured metadata about people, organizations, products, or projects.
   - `wiki/queries/` is reserved for query-oriented artifacts or agent retrieval outputs.

4. **OKF schema as the organizing model**
   - Every note is expected to follow the OKF pattern with explicit frontmatter fields, especially a required `type`.
   - Relationships are declared explicitly through `related: []`, which makes the knowledge graph traversable without inference-heavy search.
   - The result is a **typed document graph** rather than a loose collection of notes.

5. **Templates as the content contract**
   - `templates/` contains the canonical shapes for new OKF pages: `concept-page.md`, `entity-page.md`, and `source-page.md`.
   - These templates act as a governance layer, ensuring new files conform to the repo’s schema and naming conventions.
   - In architecture terms, templates are the **content interface** between agent-generated knowledge and the vault.

6. **Ingestion and automation pipeline**
   - `setup.py` is the bootstrapper: it creates the folder structure, checks dependencies, and generates local config needed for agent operation.
   - `wiki_auto_ingest_manifest.py` suggests a manifest-driven ingestion step that tracks what has been processed into the wiki.
   - The readme describes a scheduled daemon workflow, driven by `run_daemon.sh` created during setup, to continuously ingest new raw files into curated wiki pages.

7. **Agent/runtime integration**
   - The repo is designed to work with external **MCP servers** so AI agents can interact with the vault and source material.
   - Key integrations called out in the readme are:
     - `obsidian` for direct markdown read/write access,
     - `markitdown` for converting PDFs/HTML/office docs into Markdown,
     - `youtube-transcript` for transcript extraction,
     - `github-official` for repository search/reference,
     - `context7` for developer documentation lookup.
   - These integrations form the repo’s **ingest and enrichment edge**.

8. **Operational control plane**
   - `AGENTS.md` is the operating manual for maintenance behavior: provenance rules, linting, and OKF compliance expectations.
   - `agent_prompt_template.md` is intended to configure a scheduled background agent or cron-like daemon.
   - `system-context.md` and `log.md` appear to support operational memory and audit/history for the maintenance process.

9. **Quality assurance and health checks**
   - `wiki_health_check.py` is the validation subsystem: it scans the vault for orphans, thin notes, stale files, broken links, and contradictions.
   - This provides a repository-level integrity check over the knowledge graph, complementing the ingestion pipeline.
   - Architecturally, it is the main guardrail preventing the curated wiki from drifting out of schema or becoming disconnected.

10. **Auxiliary assets and scaffolding**
   - `assets/` is for non-text resources that may support pages or diagrams.
   - `.gitkeep` files indicate that several directories are intentionally present as empty scaffolding so the vault structure is stable from the start.
   - `OBSIDIAN_MCP_SETUP.md` is a targeted setup guide for one important integration path, reinforcing that this repo is meant to be used inside an agent-enabled note-taking workflow.

11. **How data flows through the system**
   - External documents enter through `raw/` via manual drop-in or MCP-assisted acquisition.
   - The daemon/ingest workflow reads those inputs, converts or enriches them, and writes structured derivatives into `wiki/sources/`, `wiki/concepts/`, and `wiki/entities/`.
   - Validation then checks the resulting graph, while the agent uses explicit links and type metadata to navigate and extend the knowledge base.

12. **How to draw the architecture**
   - Model this repo as a **local knowledge vault with three planes**:
     - **Input plane:** `raw/` plus external MCP services,
     - **Processing plane:** `setup.py`, daemon/manifest logic, templates, health checks,
     - **Knowledge plane:** `wiki/` as the durable typed graph.
   - The key architectural constraint is that all state lives in plain files, with explicit schemas and relationships enabling deterministic agent behavior.

Main entry points: [`setup.py`](https://github.com/blackx16/okf-wiki-template/blob/main/setup.py) (Setup), [`README.md`](https://github.com/blackx16/okf-wiki-template/blob/main/README.md) (README), [`templates`](https://github.com/blackx16/okf-wiki-template/tree/main/templates) (Templates), [`mcp-config.json.template`](https://github.com/blackx16/okf-wiki-template/blob/main/mcp-config.json.template) (MCP services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input plane"]
  node_raw[("Raw inputs<br/>immutable source")]
  node_mcp["MCP services<br/>external integration"]
  node_okf_article["OKF article<br/>raw source note<br/>[what-is-okf.md]"]
  node_obsidian_setup["Obsidian setup<br/>integration guide"]
end

subgraph group_processing["Processing plane"]
  node_setup_py["Setup<br/>bootstrap<br/>[setup.py]"]
  node_ingest_manifest["Ingest manifest<br/>ingestion state"]
  node_health_check["Health check<br/>validation"]
  node_templates["Templates<br/>content contract"]
  node_concept_template["Concept template<br/>schema template<br/>[concept-page.md]"]
  node_entity_template["Entity template<br/>schema template<br/>[entity-page.md]"]
  node_source_template["Source template<br/>schema template<br/>[source-page.md]"]
end

subgraph group_knowledge["Knowledge plane"]
  node_wiki[("Wiki<br/>typed knowledge graph")]
  node_wiki_sources["Sources<br/>processed notes"]
  node_wiki_concepts{{"Concepts"}}
  node_wiki_entities["Entities"]
  node_wiki_queries["Queries<br/>retrieval artifacts"]
  node_source_note["Source note<br/>curated source page<br/>[what-is-okf.md]"]
  node_concept_page{{"OKF concept<br/>concept page"}}
  node_entity_page["OKF Foundation<br/>entity page"]
end

subgraph group_ops["Operations"]
  node_readme["README<br/>repo guide<br/>[README.md]"]
  node_agents_md["AGENTS.md<br/>operating manual<br/>[AGENTS.md]"]
  node_prompt_template["Agent prompt<br/>runtime prompt"]
  node_system_context["System context<br/>ops context<br/>[system-context.md]"]
  node_log_md["Log<br/>audit trail<br/>[log.md]"]
end

node_readme -->|"defines intake"| node_raw
node_readme -->|"describes"| node_wiki
node_readme -->|"introduces"| node_setup_py
node_readme -->|"documents"| node_health_check
node_readme -->|"integrates"| node_mcp
node_setup_py -->|"creates"| node_templates
node_setup_py -->|"creates tree"| node_raw
node_setup_py -->|"creates tree"| node_wiki
node_setup_py -->|"writes"| node_prompt_template
node_prompt_template -->|"drives"| node_ingest_manifest
node_mcp -->|"ingests"| node_raw
node_mcp -->|"writes"| node_wiki
node_raw -->|"feeds"| node_wiki_sources
node_wiki_sources -->|"supports synthesis"| node_wiki_concepts
node_wiki_sources -->|"extracts metadata"| node_wiki_entities
node_wiki_concepts -->|"references"| node_wiki_entities
node_wiki -->|"validated by"| node_health_check
node_ingest_manifest -->|"tracks"| node_wiki_sources
node_templates -->|"includes"| node_concept_template
node_templates -->|"includes"| node_entity_template
node_templates -->|"includes"| node_source_template
node_agents_md -->|"governs"| node_setup_py
node_agents_md -->|"governs"| node_health_check
node_system_context -->|"informs"| node_prompt_template
node_log_md -->|"records"| node_ingest_manifest
node_okf_article -->|"becomes"| node_source_note
node_source_note -->|"links to"| node_concept_page
node_concept_page -->|"mentions"| node_entity_page
node_obsidian_setup -->|"onboards"| node_mcp
node_wiki_queries -.->|"consumes findings"| node_health_check

click node_readme "https://github.com/blackx16/okf-wiki-template/blob/main/README.md"
click node_agents_md "https://github.com/blackx16/okf-wiki-template/blob/main/AGENTS.md"
click node_prompt_template "https://github.com/blackx16/okf-wiki-template/blob/main/agent_prompt_template.md"
click node_system_context "https://github.com/blackx16/okf-wiki-template/blob/main/system-context.md"
click node_log_md "https://github.com/blackx16/okf-wiki-template/blob/main/log.md"
click node_setup_py "https://github.com/blackx16/okf-wiki-template/blob/main/setup.py"
click node_ingest_manifest "https://github.com/blackx16/okf-wiki-template/blob/main/wiki_auto_ingest_manifest.py"
click node_health_check "https://github.com/blackx16/okf-wiki-template/blob/main/wiki_health_check.py"
click node_templates "https://github.com/blackx16/okf-wiki-template/tree/main/templates"
click node_concept_template "https://github.com/blackx16/okf-wiki-template/blob/main/templates/concept-page.md"
click node_entity_template "https://github.com/blackx16/okf-wiki-template/blob/main/templates/entity-page.md"
click node_source_template "https://github.com/blackx16/okf-wiki-template/blob/main/templates/source-page.md"
click node_raw "https://github.com/blackx16/okf-wiki-template/tree/main/raw"
click node_mcp "https://github.com/blackx16/okf-wiki-template/blob/main/mcp-config.json.template"
click node_wiki "https://github.com/blackx16/okf-wiki-template/tree/main/wiki"
click node_wiki_sources "https://github.com/blackx16/okf-wiki-template/tree/main/wiki/sources"
click node_wiki_concepts "https://github.com/blackx16/okf-wiki-template/tree/main/wiki/concepts"
click node_wiki_entities "https://github.com/blackx16/okf-wiki-template/tree/main/wiki/entities"
click node_wiki_queries "https://github.com/blackx16/okf-wiki-template/tree/main/wiki/queries"
click node_okf_article "https://github.com/blackx16/okf-wiki-template/blob/main/raw/articles/what-is-okf.md"
click node_source_note "https://github.com/blackx16/okf-wiki-template/blob/main/wiki/sources/what-is-okf.md"
click node_concept_page "https://github.com/blackx16/okf-wiki-template/blob/main/wiki/concepts/open-knowledge-format.md"
click node_entity_page "https://github.com/blackx16/okf-wiki-template/blob/main/wiki/entities/open-knowledge-foundation.md"
click node_obsidian_setup "https://github.com/blackx16/okf-wiki-template/blob/main/OBSIDIAN_MCP_SETUP.md"

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_raw,node_mcp,node_okf_article,node_obsidian_setup toneBlue
class node_setup_py,node_ingest_manifest,node_health_check,node_templates,node_concept_template,node_entity_template,node_source_template toneAmber
class node_wiki,node_wiki_sources,node_wiki_concepts,node_wiki_entities,node_wiki_queries,node_source_note,node_concept_page,node_entity_page toneMint
class node_readme,node_agents_md,node_prompt_template,node_system_context,node_log_md toneRose
```

## Components

### Input plane

Inbound documents and external acquisition/enrichment services.

- [Raw inputs](https://github.com/blackx16/okf-wiki-template/tree/main/raw): immutable source · Write-protected inbound documents organized by source type. · `raw`
- [MCP services](https://github.com/blackx16/okf-wiki-template/blob/main/mcp-config.json.template): external integration · Agent-facing connectors for vault access, conversion, transcript extraction, code search, and docs lookup. · `mcp-config.json.template`
- [OKF article](https://github.com/blackx16/okf-wiki-template/blob/main/raw/articles/what-is-okf.md): raw source note · Example raw article about OKF in the inbound area. · `raw/articles/what-is-okf.md`
- [Obsidian setup](https://github.com/blackx16/okf-wiki-template/blob/main/OBSIDIAN_MCP_SETUP.md): integration guide · Targeted setup guide for one important MCP path. · `OBSIDIAN_MCP_SETUP.md`

### Processing plane

Bootstrapping, ingestion orchestration, templates, and validation.

- [Setup](https://github.com/blackx16/okf-wiki-template/blob/main/setup.py): bootstrap · Creates the folder structure, checks dependencies, and prepares local runtime config. · `setup.py`
- [Ingest manifest](https://github.com/blackx16/okf-wiki-template/blob/main/wiki_auto_ingest_manifest.py): ingestion state · Tracks what content has been processed into the wiki. · `wiki_auto_ingest_manifest.py`
- [Health check](https://github.com/blackx16/okf-wiki-template/blob/main/wiki_health_check.py): validation · Scans the vault for orphans, thin notes, broken links, and contradictions. · `wiki_health_check.py`
- [Templates](https://github.com/blackx16/okf-wiki-template/tree/main/templates): content contract · Canonical page shapes for new OKF notes. · `templates`
- [Concept template](https://github.com/blackx16/okf-wiki-template/blob/main/templates/concept-page.md): schema template · Frontmatter and structure for concept pages. · `templates/concept-page.md`
- [Entity template](https://github.com/blackx16/okf-wiki-template/blob/main/templates/entity-page.md): schema template · Frontmatter and structure for entity pages. · `templates/entity-page.md`
- [Source template](https://github.com/blackx16/okf-wiki-template/blob/main/templates/source-page.md): schema template · Frontmatter and structure for source pages. · `templates/source-page.md`

### Knowledge plane

Durable typed wiki content organized as source, concept, entity, and query layers.

- [Wiki](https://github.com/blackx16/okf-wiki-template/tree/main/wiki): typed knowledge graph · Durable curated knowledge stored as plain Markdown with explicit relationships. · `wiki`
- [Sources](https://github.com/blackx16/okf-wiki-template/tree/main/wiki/sources): processed notes · Reading notes derived from raw inputs. · `wiki/sources`
- [Concepts](https://github.com/blackx16/okf-wiki-template/tree/main/wiki/concepts): synthesized concepts · Cross-source abstractions and durable concept pages. · `wiki/concepts`
- [Entities](https://github.com/blackx16/okf-wiki-template/tree/main/wiki/entities): structured entities · People, organizations, products, and projects with explicit metadata. · `wiki/entities`
- [Queries](https://github.com/blackx16/okf-wiki-template/tree/main/wiki/queries): retrieval artifacts · Query-oriented artifacts and agent retrieval outputs. · `wiki/queries`
- [Source note](https://github.com/blackx16/okf-wiki-template/blob/main/wiki/sources/what-is-okf.md): curated source page · Example processed source note in the wiki. · `wiki/sources/what-is-okf.md`
- [OKF concept](https://github.com/blackx16/okf-wiki-template/blob/main/wiki/concepts/open-knowledge-format.md): concept page · Curated concept page for Open Knowledge Format. · `wiki/concepts/open-knowledge-format.md`
- [OKF Foundation](https://github.com/blackx16/okf-wiki-template/blob/main/wiki/entities/open-knowledge-foundation.md): entity page · Structured entity page for Open Knowledge Foundation. · `wiki/entities/open-knowledge-foundation.md`

### Operations

Runtime guidance, prompts, and audit memory for agent maintenance.

- [README](https://github.com/blackx16/okf-wiki-template/blob/main/README.md): repo guide · Explains the filesystem-first OKF wiki workflow and overall usage model. · `README.md`
- [AGENTS.md](https://github.com/blackx16/okf-wiki-template/blob/main/AGENTS.md): operating manual · Repository maintenance rules, provenance expectations, and OKF compliance guidance. · `AGENTS.md`
- [Agent prompt](https://github.com/blackx16/okf-wiki-template/blob/main/agent_prompt_template.md): runtime prompt · Template for scheduled background agent or daemon behavior. · `agent_prompt_template.md`
- [System context](https://github.com/blackx16/okf-wiki-template/blob/main/system-context.md): ops context · Shared operational memory and environment context for the maintenance process. · `system-context.md`
- [Log](https://github.com/blackx16/okf-wiki-template/blob/main/log.md): audit trail · Operational history and notes for maintenance runs. · `log.md`

## Connections

- README → Raw inputs: defines intake · Describes raw as the inbound write-protected boundary.
- README → Wiki: describes · Frames the wiki as the durable knowledge plane.
- README → Setup: introduces · Explains bootstrap and local environment preparation.
- README → Health check: documents · Covers repository integrity checks and validation behavior.
- README → MCP services: integrates · Lists external services used for acquisition and enrichment.
- Setup → Templates: creates · Bootstraps the canonical note scaffolding.
- Setup → Raw inputs: creates tree · Initializes the input folder structure.
- Setup → Wiki: creates tree · Initializes the curated wiki structure.
- Setup → Agent prompt: writes · Generates local daemon or agent configuration.
- Agent prompt → Ingest manifest: drives · Schedules or guides ongoing ingestion runs.
- MCP services → Raw inputs: ingests · Provides acquisition and conversion paths into raw inputs.
- MCP services → Wiki: writes · Enables agent-mediated markdown read/write access.
- Raw inputs → Sources: feeds · Inbound documents are processed into source notes.
- Sources → Concepts: supports synthesis · Source notes are combined into durable abstractions.
- Sources → Entities: extracts metadata · Source material informs structured entity records.
- Concepts → Entities: references · Concept pages link to people, organizations, products, or projects.
- Wiki → Health check: validated by · The curated graph is checked for structural and content health.
- Ingest manifest → Sources: tracks · Records which raw items became curated source pages.
- Templates → Concept template: includes · Provides the concept page contract.
- Templates → Entity template: includes · Provides the entity page contract.
- Templates → Source template: includes · Provides the source page contract.
- AGENTS.md → Setup: governs · Defines expected bootstrap and maintenance behavior.
- AGENTS.md → Health check: governs · Sets compliance and quality expectations.
- System context → Agent prompt: informs · Supplies operational context for background agents.
- Log → Ingest manifest: records · Supports auditability of ingestion activity.
- OKF article → Source note: becomes · Example raw article is curated into a source page.
- Source note → OKF concept: links to · Processed notes point to higher-level concepts.
- OKF concept → OKF Foundation: mentions · Concepts connect to entity records.
- Obsidian setup → MCP services: onboards · Documents one key integration path for vault access.
- Queries → Health check: consumes findings · Retrieval artifacts can be used to support inspection and review.
