# aiob3/ssot-okf architecture

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

- Interactive diagram: https://gitdiagram.com/aiob3/ssot-okf
- Repository: https://github.com/aiob3/ssot-okf

## Overview

#### Purpose and Repository Shape
This is a multi-language reference repository for governed context/intent workflows and Google Cloud Knowledge Catalog integrations. It combines: a Python reference agent that builds knowledge bundles, TypeScript tooling that synchronizes Markdown with catalog services, enrichment examples, and validation harnesses. The top-level README defines the SSOT-governed model: operator evidence is progressively promoted through interest, intent, objective, execution binding, loopback, and certified handoff.

#### Primary Entry Points
- Python reference-agent CLI/module: `okf/src/reference_agent/__main__.py`, `okf/src/reference_agent/cli.py`, `okf/src/reference_agent/runner.py`.
- Markdown synchronization tool and MCP endpoint: `toolbox/mdcode/src/tool/main.ts`, `toolbox/mdcode/src/tool/commands.ts`, `toolbox/mdcode/src/tool/mcp.ts`.
- TypeScript enrichment agent: `toolbox/enrichment/src/agent/main.ts`, `toolbox/enrichment/src/agent/enrich/command.ts`.
- Deja-vu validation scripts: `harness/deja_vu/scripts/homologate.py`, `harness/deja_vu/scripts/mcp_wrapper.py`.

#### Knowledge Bundle Model
The OKF package treats a filesystem of Markdown documents as a governed knowledge bundle. Document, path, indexing, and synthesis logic form the core bundle boundary in `okf/src/reference_agent/bundle/document.py`, `okf/src/reference_agent/bundle/index.py`, and `okf/src/reference_agent/bundle/synthesizer.py`. Bundles contain dataset/table metadata, joins, metrics, policies, computations, skills, attesters, and generated visualization pages; examples live under `okf/bundles/ga4/`, `okf/bundles/crypto_bitcoin/`, and `okf/bundles/acme_retail/`.

#### Reference-Agent Flow
The Python agent accepts user tasks through the CLI, assembles prompts and contextual bundle content, then operates through explicit tool layers. Agent orchestration is in `okf/src/reference_agent/agent.py`; tools expose bundle/context, source, and web capabilities in `okf/src/reference_agent/tools/bundle_tools.py`, `okf/src/reference_agent/tools/source_tools.py`, and `okf/src/reference_agent/tools/web_tools.py`. Prompt contracts are versioned Markdown in `okf/src/reference_agent/prompts/reference_instruction.md` and `okf/src/reference_agent/prompts/web_ingestion_instruction.md`. This separates agent reasoning from source access and filesystem mutations.

#### External Data and Presentation Boundaries
BigQuery is a first-class source adapter behind a source abstraction: `okf/src/reference_agent/sources/base.py` and `okf/src/reference_agent/sources/bigquery.py`. Web ingestion is isolated in `okf/src/reference_agent/web/fetcher.py`. Generated bundle visualization is handled separately by `okf/src/reference_agent/viewer/generator.py` and its static/template assets, rather than by an application server. Bundle `viz.html` files are output/artifact-style views.

#### mdcode Synchronization Platform
`toolbox/mdcode` is the TypeScript infrastructure layer for bidirectional catalog synchronization. It models layouts, manifests, source adapters, metadata, snapshots, and synchronization in `toolbox/mdcode/src/libts/layout.ts`, `toolbox/mdcode/src/libts/manifest.ts`, and `toolbox/mdcode/src/libts/sync.ts`. Source implementations include BigQuery datasets, Knowledge Catalog/Dataplex entry groups, and knowledge bases: `toolbox/mdcode/src/libts/sources/bq-dataset.ts`, `toolbox/mdcode/src/libts/sources/entrygroup.ts`, and `toolbox/mdcode/src/libts/sources/kb.ts`. Google Cloud integration code is bounded under `toolbox/mdcode/src/libts/gcp/`, including BigQuery, Dataplex, and CRM clients.

#### Enrichment and Governance Validation
The Python and TypeScript enrichment samples demonstrate ingestion, metadata snapshot/catalog handling, documentation generation, and publishing: `samples/enrichment/src/enrichment/enrich.py`, `samples/enrichment/src/enrichment/metadata/snapshot.py`, and `toolbox/enrichment/src/agent/enrich/agent.ts`. The Deja-vu harness independently validates historical evidence and explicitly gates real-source or MCP binding, centered on `harness/deja_vu/scripts/validate_binding.py` and `harness/deja_vu/scripts/preview_real.py`. This is the repository’s main control boundary for preventing uncertified external context from becoming governed execution input.

Main entry points: [`okf/src/reference_agent/tools/bundle_tools.py`](https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/tools/bundle_tools.py) (Agent tool boundary), [`toolbox/mdcode/src/libts/sync.ts`](https://github.com/aiob3/ssot-okf/blob/main/toolbox/mdcode/src/libts/sync.ts) (Sync engine), [`okf/src/reference_agent/agent.py`](https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/agent.py) (Agent orchestration), [`harness/deja_vu/scripts/validate_binding.py`](https://github.com/aiob3/ssot-okf/blob/main/harness/deja_vu/scripts/validate_binding.py) (Real-source binding gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_okf["OKF reference agent"]
  node_agent_cli["Reference-agent CLI<br/>Python entry point<br/>[cli.py]"]
  node_agent_runner["Task runner<br/>Python runtime<br/>[runner.py]"]
  node_agent["Agent orchestration<br/>Python agent<br/>[agent.py]"]
  node_prompt_contracts["Prompt contracts<br/>Markdown prompts"]
  node_bundle_core["Knowledge bundle core<br/>Python bundle model<br/>[document.py]"]
  node_bundle_examples["Example bundles<br/>Markdown knowledge bundles"]
  node_agent_tools["Agent tool boundary<br/>Python tools<br/>[bundle_tools.py]"]
  node_source_adapter["Source abstraction<br/>Python source adapter<br/>[base.py]"]
  node_web_ingestion["Web ingestion<br/>Python fetcher<br/>[fetcher.py]"]
  node_bundle_viewer["Bundle visualization<br/>Static page generator<br/>[generator.py]"]
end

subgraph group_mdcode["mdcode platform"]
  node_mdcode_cli["mdcode CLI<br/>TypeScript entry point<br/>[main.ts]"]
  node_mdcode_mcp["MCP endpoint<br/>TypeScript MCP server<br/>[mcp.ts]"]
  node_sync_engine["Sync engine<br/>TypeScript synchronization<br/>[sync.ts]"]
  node_catalog_sources["Catalog source adapters<br/>TypeScript sources<br/>[bq-dataset.ts]"]
  node_gcp_clients["Google Cloud clients<br/>TypeScript GCP integration"]
end

subgraph group_enrichment["Enrichment examples"]
  node_enrichment_agent["Enrichment agent<br/>TypeScript agent<br/>[agent.ts]"]
  node_python_enrichment["Python enrichment sample<br/>Python enrichment flow<br/>[enrich.py]"]
end

subgraph group_validation["Governance validation"]
  node_binding_gate{{"Real-source binding gate<br/>Validation control"}}
  node_homologation["Evidence homologation<br/>Validation harness<br/>[homologate.py]"]
end

node_bigquery[("BigQuery<br/>Google Cloud data source<br/>[bigquery.py]")]

node_agent_cli -->|"runs"| node_agent_runner
node_agent_runner -->|"executes task"| node_agent
node_agent -->|"uses instructions"| node_prompt_contracts
node_agent -->|"uses explicit tools"| node_agent_tools
node_agent_tools -->|"reads and mutates"| node_bundle_core
node_bundle_examples -->|"provide governed content"| node_bundle_core
node_agent_tools -->|"accesses sources"| node_source_adapter
node_source_adapter -->|"queries"| node_bigquery
node_agent_tools -->|"fetches web context"| node_web_ingestion
node_bundle_core -->|"generates views"| node_bundle_viewer
node_mdcode_cli -->|"invokes"| node_sync_engine
node_mdcode_mcp -->|"serves synchronization"| node_sync_engine
node_sync_engine -->|"synchronizes adapters"| node_catalog_sources
node_catalog_sources -->|"uses cloud APIs"| node_gcp_clients
node_gcp_clients -->|"accesses metadata"| node_bigquery
node_python_enrichment -.->|"parallels enrichment flow"| node_enrichment_agent
node_enrichment_agent -->|"publishes catalog content"| node_sync_engine
node_homologation -->|"checks evidence before binding"| node_binding_gate
node_binding_gate -.->|"gates MCP binding"| node_mdcode_mcp
node_binding_gate -.->|"gates real-source use"| node_source_adapter

click node_agent_cli "https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/cli.py"
click node_agent_runner "https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/runner.py"
click node_agent "https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/agent.py"
click node_prompt_contracts "https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/prompts/reference_instruction.md"
click node_bundle_core "https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/bundle/document.py"
click node_agent_tools "https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/tools/bundle_tools.py"
click node_source_adapter "https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/sources/base.py"
click node_bigquery "https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/sources/bigquery.py"
click node_web_ingestion "https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/web/fetcher.py"
click node_bundle_viewer "https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/viewer/generator.py"
click node_mdcode_cli "https://github.com/aiob3/ssot-okf/blob/main/toolbox/mdcode/src/tool/main.ts"
click node_mdcode_mcp "https://github.com/aiob3/ssot-okf/blob/main/toolbox/mdcode/src/tool/mcp.ts"
click node_sync_engine "https://github.com/aiob3/ssot-okf/blob/main/toolbox/mdcode/src/libts/sync.ts"
click node_catalog_sources "https://github.com/aiob3/ssot-okf/blob/main/toolbox/mdcode/src/libts/sources/bq-dataset.ts"
click node_enrichment_agent "https://github.com/aiob3/ssot-okf/blob/main/toolbox/enrichment/src/agent/enrich/agent.ts"
click node_python_enrichment "https://github.com/aiob3/ssot-okf/blob/main/samples/enrichment/src/enrichment/enrich.py"
click node_binding_gate "https://github.com/aiob3/ssot-okf/blob/main/harness/deja_vu/scripts/validate_binding.py"
click node_homologation "https://github.com/aiob3/ssot-okf/blob/main/harness/deja_vu/scripts/homologate.py"

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_agent_cli,node_agent_runner,node_agent,node_prompt_contracts,node_bundle_core,node_bundle_examples,node_agent_tools,node_source_adapter,node_web_ingestion,node_bundle_viewer toneBlue
class node_mdcode_cli,node_mdcode_mcp,node_sync_engine,node_catalog_sources,node_gcp_clients toneAmber
class node_enrichment_agent,node_python_enrichment toneMint
class node_binding_gate,node_homologation toneRose
class node_bigquery toneNeutral
```

## Components

### OKF reference agent

Python governed knowledge-bundle workflow.

- [Reference-agent CLI](https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/cli.py): Python entry point · `okf/src/reference_agent/cli.py`
- [Task runner](https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/runner.py): Python runtime · `okf/src/reference_agent/runner.py`
- [Agent orchestration](https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/agent.py): Python agent · Assembles prompts, context, and explicit tool use. · `okf/src/reference_agent/agent.py`
- [Prompt contracts](https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/prompts/reference_instruction.md): Markdown prompts · `okf/src/reference_agent/prompts/reference_instruction.md`
- [Knowledge bundle core](https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/bundle/document.py): Python bundle model · Governed Markdown documents, index, and synthesis. · `okf/src/reference_agent/bundle/document.py`
- **Example bundles**: Markdown knowledge bundles · GA4, Bitcoin, and retail governed metadata.
- [Agent tool boundary](https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/tools/bundle_tools.py): Python tools · Separates bundle, source, and web access from reasoning. · `okf/src/reference_agent/tools/bundle_tools.py`
- [Source abstraction](https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/sources/base.py): Python source adapter · `okf/src/reference_agent/sources/base.py`
- [Web ingestion](https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/web/fetcher.py): Python fetcher · `okf/src/reference_agent/web/fetcher.py`
- [Bundle visualization](https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/viewer/generator.py): Static page generator · Generates bundle viz.html artifacts. · `okf/src/reference_agent/viewer/generator.py`

### mdcode platform

TypeScript catalog synchronization and MCP tooling.

- [mdcode CLI](https://github.com/aiob3/ssot-okf/blob/main/toolbox/mdcode/src/tool/main.ts): TypeScript entry point · `toolbox/mdcode/src/tool/main.ts`
- [MCP endpoint](https://github.com/aiob3/ssot-okf/blob/main/toolbox/mdcode/src/tool/mcp.ts): TypeScript MCP server · `toolbox/mdcode/src/tool/mcp.ts`
- [Sync engine](https://github.com/aiob3/ssot-okf/blob/main/toolbox/mdcode/src/libts/sync.ts): TypeScript synchronization · Models layouts, manifests, snapshots, and bidirectional sync. · `toolbox/mdcode/src/libts/sync.ts`
- [Catalog source adapters](https://github.com/aiob3/ssot-okf/blob/main/toolbox/mdcode/src/libts/sources/bq-dataset.ts): TypeScript sources · BigQuery datasets, entry groups, and knowledge bases. · `toolbox/mdcode/src/libts/sources/bq-dataset.ts`
- **Google Cloud clients**: TypeScript GCP integration · BigQuery, Dataplex, and CRM clients.

### Enrichment examples

Python and TypeScript metadata enrichment flows.

- [Enrichment agent](https://github.com/aiob3/ssot-okf/blob/main/toolbox/enrichment/src/agent/enrich/agent.ts): TypeScript agent · Generates and publishes enriched catalog documentation. · `toolbox/enrichment/src/agent/enrich/agent.ts`
- [Python enrichment sample](https://github.com/aiob3/ssot-okf/blob/main/samples/enrichment/src/enrichment/enrich.py): Python enrichment flow · Ingests metadata and creates snapshots. · `samples/enrichment/src/enrichment/enrich.py`

### Governance validation

Independent evidence and binding controls.

- [Real-source binding gate](https://github.com/aiob3/ssot-okf/blob/main/harness/deja_vu/scripts/validate_binding.py): Validation control · Prevents uncertified external context from entering governed execution. · `harness/deja_vu/scripts/validate_binding.py`
- [Evidence homologation](https://github.com/aiob3/ssot-okf/blob/main/harness/deja_vu/scripts/homologate.py): Validation harness · Validates historical evidence and MCP-mediated binding. · `harness/deja_vu/scripts/homologate.py`

### Other components

- [BigQuery](https://github.com/aiob3/ssot-okf/blob/main/okf/src/reference_agent/sources/bigquery.py): Google Cloud data source · `okf/src/reference_agent/sources/bigquery.py`

## Connections

- Reference-agent CLI → Task runner: runs
- Task runner → Agent orchestration: executes task
- Agent orchestration → Prompt contracts: uses instructions
- Agent orchestration → Agent tool boundary: uses explicit tools
- Agent tool boundary → Knowledge bundle core: reads and mutates
- Example bundles → Knowledge bundle core: provide governed content
- Agent tool boundary → Source abstraction: accesses sources
- Source abstraction → BigQuery: queries
- Agent tool boundary → Web ingestion: fetches web context
- Knowledge bundle core → Bundle visualization: generates views
- mdcode CLI → Sync engine: invokes
- MCP endpoint → Sync engine: serves synchronization
- Sync engine → Catalog source adapters: synchronizes adapters
- Catalog source adapters → Google Cloud clients: uses cloud APIs
- Google Cloud clients → BigQuery: accesses metadata
- Python enrichment sample → Enrichment agent: parallels enrichment flow
- Enrichment agent → Sync engine: publishes catalog content
- Evidence homologation → Real-source binding gate: checks evidence before binding
- Real-source binding gate → MCP endpoint: gates MCP binding
- Real-source binding gate → Source abstraction: gates real-source use