# watanabe3tipapa/okf-seedling architecture

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

- Interactive diagram: https://gitdiagram.com/watanabe3tipapa/okf-seedling
- Repository: https://github.com/watanabe3tipapa/okf-seedling

## Overview

okf-seedling is a Quarto template for growing OKF knowledge bundles from concept documents. The main workflow is authoring `.qmd` concepts, rendering human-readable HTML and a machine-readable `okf/` bundle, then checking the bundle for conformance and quality. Separate capabilities support browser-based editing, homepage previews, and optional extraction of rendered concepts into JSON knowledge records. The graph follows README-described workflows and sampled source; unsampled Quarto wiring and concept contents limit which internal render-time connections can be shown.

Main entry points: [`okf`](https://github.com/watanabe3tipapa/okf-seedling/tree/main/okf) (OKF bundle), [`pipeline/src/learn.mjs`](https://github.com/watanabe3tipapa/okf-seedling/blob/main/pipeline/src/learn.mjs) (Learning runner), [`_quarto.yml`](https://github.com/watanabe3tipapa/okf-seedling/blob/main/_quarto.yml) (Quarto render), [`tools/stamp-okf.mjs`](https://github.com/watanabe3tipapa/okf-seedling/blob/main/tools/stamp-okf.mjs) (Bundle generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Authoring and rendering"]
  node_author["Concept documents"]
  node_quarto["Quarto render<br/>[_quarto.yml]"]
  node_html["Human HTML site"]
  node_filter["OKF metadata filter<br/>[okf-meta.lua]"]
end

subgraph group_bundle["OKF bundle"]
  node_stamp["Bundle generator<br/>[stamp-okf.mjs]"]
  node_bundleout["OKF bundle"]
end

subgraph group_validation["Validation and previews"]
  node_registry["Concept type registry<br/>[okf-types.json]"]
  node_validator["OKF validator<br/>[validate-okf.mjs]"]
  node_peek["Homepage preview injection<br/>[gen-peek.mjs]"]
  node_siteindex["Homepage preview data"]
end

subgraph group_learning["Learning pipeline"]
  node_learn["Learning runner<br/>[learn.mjs]"]
  node_extract["Concept extractor<br/>[extract.mjs]"]
  node_knowledge[("Learned JSON records")]
end

subgraph group_editing["Online editing"]
  node_editorlink["Editor link generator<br/>[editor-link.mjs]"]
  node_editor["Quarto Editor PE"]
end

node_editoractor(("Bundle author"))

node_author -->|"renders from"| node_quarto
node_quarto -->|"generates HTML"| node_html
node_quarto -->|"generates bundle"| node_bundleout
node_filter -.->|"uses schema"| node_registry
node_stamp -->|"reads concepts"| node_author
node_stamp -->|"writes bundle"| node_bundleout
node_validator -->|"checks bundle"| node_bundleout
node_validator -->|"reads types"| node_registry
node_peek -->|"reads concepts"| node_bundleout
node_peek -->|"injects preview"| node_siteindex
node_editoractor -->|"requests links"| node_editorlink
node_editorlink -->|"prints edit links"| node_editor
node_editoractor -->|"edits and commits"| node_editor
node_learn -->|"reads rendered concepts"| node_html
node_learn -->|"calls extractor"| node_extract
node_learn -->|"writes records"| node_knowledge

click node_author "https://github.com/watanabe3tipapa/okf-seedling/tree/main/concepts"
click node_quarto "https://github.com/watanabe3tipapa/okf-seedling/blob/main/_quarto.yml"
click node_filter "https://github.com/watanabe3tipapa/okf-seedling/blob/main/_extensions/okf/okf-meta.lua"
click node_registry "https://github.com/watanabe3tipapa/okf-seedling/blob/main/tools/okf-types.json"
click node_stamp "https://github.com/watanabe3tipapa/okf-seedling/blob/main/tools/stamp-okf.mjs"
click node_bundleout "https://github.com/watanabe3tipapa/okf-seedling/tree/main/okf"
click node_validator "https://github.com/watanabe3tipapa/okf-seedling/blob/main/tools/validate-okf.mjs"
click node_peek "https://github.com/watanabe3tipapa/okf-seedling/blob/main/tools/gen-peek.mjs"
click node_editorlink "https://github.com/watanabe3tipapa/okf-seedling/blob/main/tools/editor-link.mjs"
click node_learn "https://github.com/watanabe3tipapa/okf-seedling/blob/main/pipeline/src/learn.mjs"
click node_extract "https://github.com/watanabe3tipapa/okf-seedling/blob/main/pipeline/src/extract.mjs"

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_author,node_quarto,node_html,node_filter toneBlue
class node_stamp,node_bundleout toneAmber
class node_registry,node_validator,node_peek,node_siteindex toneMint
class node_learn,node_extract,node_knowledge toneRose
class node_editorlink,node_editor,node_editoractor toneIndigo
```

## Components

### Authoring and rendering

- [Concept documents](https://github.com/watanabe3tipapa/okf-seedling/tree/main/concepts): `concepts`
- [Quarto render](https://github.com/watanabe3tipapa/okf-seedling/blob/main/_quarto.yml): `_quarto.yml`
- **Human HTML site**
- [OKF metadata filter](https://github.com/watanabe3tipapa/okf-seedling/blob/main/_extensions/okf/okf-meta.lua): `_extensions/okf/okf-meta.lua`

### OKF bundle

- [Bundle generator](https://github.com/watanabe3tipapa/okf-seedling/blob/main/tools/stamp-okf.mjs): `tools/stamp-okf.mjs`
- [OKF bundle](https://github.com/watanabe3tipapa/okf-seedling/tree/main/okf): `okf`

### Validation and previews

- [Concept type registry](https://github.com/watanabe3tipapa/okf-seedling/blob/main/tools/okf-types.json): `tools/okf-types.json`
- [OKF validator](https://github.com/watanabe3tipapa/okf-seedling/blob/main/tools/validate-okf.mjs): `tools/validate-okf.mjs`
- [Homepage preview injection](https://github.com/watanabe3tipapa/okf-seedling/blob/main/tools/gen-peek.mjs): `tools/gen-peek.mjs`
- **Homepage preview data**

### Learning pipeline

- [Learning runner](https://github.com/watanabe3tipapa/okf-seedling/blob/main/pipeline/src/learn.mjs): `pipeline/src/learn.mjs`
- [Concept extractor](https://github.com/watanabe3tipapa/okf-seedling/blob/main/pipeline/src/extract.mjs): `pipeline/src/extract.mjs`
- **Learned JSON records**

### Online editing

- [Editor link generator](https://github.com/watanabe3tipapa/okf-seedling/blob/main/tools/editor-link.mjs): `tools/editor-link.mjs`
- **Quarto Editor PE**

### Other components

- **Bundle author**

## Connections

- Concept documents → Quarto render: renders from (evidence: `README.md`)
- Quarto render → Human HTML site: generates HTML (evidence: `README.md`)
- Quarto render → OKF bundle: generates bundle (evidence: `README.md`)
- OKF metadata filter → Concept type registry: uses schema
- Bundle generator → Concept documents: reads concepts (evidence: `tools/stamp-okf.mjs`)
- Bundle generator → OKF bundle: writes bundle (evidence: `tools/stamp-okf.mjs`)
- OKF validator → OKF bundle: checks bundle (evidence: `tools/validate-okf.mjs`)
- OKF validator → Concept type registry: reads types (evidence: `tools/validate-okf.mjs`)
- Homepage preview injection → OKF bundle: reads concepts (evidence: `tools/gen-peek.mjs`)
- Homepage preview injection → Homepage preview data: injects preview (evidence: `tools/gen-peek.mjs`)
- Bundle author → Editor link generator: requests links (evidence: `tools/editor-link.mjs`)
- Editor link generator → Quarto Editor PE: prints edit links (evidence: `tools/editor-link.mjs`)
- Bundle author → Quarto Editor PE: edits and commits (evidence: `README.md`)
- Learning runner → Human HTML site: reads rendered concepts (evidence: `pipeline/src/learn.mjs`)
- Learning runner → Concept extractor: calls extractor (evidence: `pipeline/src/learn.mjs`)
- Learning runner → Learned JSON records: writes records (evidence: `pipeline/src/learn.mjs`)