# jingw2/ontexus architecture

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

- Interactive diagram: https://gitdiagram.com/jingw2/ontexus
- Repository: https://github.com/jingw2/ontexus

## Overview

Ontexus turns connected or uploaded data into curated datasets and mapped domain ontologies, then exposes the resulting knowledge and actions to users and Agents. The main v2 path is connection and ingestion → pipeline transforms → curated review → ontology mapping and publication → graph, search, and executable actions. Separate branches provide document extraction, quality audits, and governed conversational Agent execution. Pipeline execution and step dispatch are supported by sampled source; several other capability links are documented in the README, while unsampled implementation details are not inferred.

Main entry points: [`backend/app/models/v2/dataset.py`](https://github.com/jingw2/ontexus/blob/master/backend/app/models/v2/dataset.py) (Datasets), [`backend/app/services/publication`](https://github.com/jingw2/ontexus/tree/master/backend/app/services/publication) (Ontology Lifecycle), [`backend/app/tasks/v2/pipeline_run.py`](https://github.com/jingw2/ontexus/blob/master/backend/app/tasks/v2/pipeline_run.py) (Pipeline Runner), [`frontend/src/pages/pipelines/builder/PipelineBuilderPage.tsx`](https://github.com/jingw2/ontexus/blob/master/frontend/src/pages/pipelines/builder/PipelineBuilderPage.tsx) (Pipeline Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data Pipelines"]
  node_pipeline_ui["Pipeline Builder"]
  node_pipeline_api["Pipeline API<br/>[pipelines.py]"]
  node_pipeline_task["Pipeline Runner<br/>[pipeline_run.py]"]
  node_transform_engine["Transform Engine<br/>[engine.py]"]
  node_transform_steps["Transform Steps"]
  node_datasets[("Datasets<br/>[dataset.py]")]
  node_curated_review["Curated Review<br/>[review_service.py]"]
  node_connections["Data Connections"]
end

subgraph group_ontology["Ontology Platform"]
  node_mapping["Ontology Mapping<br/>[mapping_service.py]"]
  node_ontology["Ontology Lifecycle"]
  node_knowledge_graph["Knowledge Graph"]
  node_search["Ontology Search"]
  node_quality_audit["Quality Audit<br/>[audit.py]"]
end

subgraph group_agents["Agent Runtime"]
  node_agent_runtime["Agent Execution"]
  node_agent_tools["Ontology Tools<br/>[ontology_tools.py]"]
end

subgraph group_platform["Platform Services"]
  node_document_extraction["LLM Extraction<br/>[extraction.py]"]
  node_prompts["Prompt Management<br/>[prompts.py]"]
  node_export["Data Export<br/>[export_service.py]"]
  node_auth["User Access<br/>[auth_service.py]"]
end

node_user(("User"))

node_user -->|"builds pipelines"| node_pipeline_ui
node_pipeline_ui -.->|"runs pipeline"| node_pipeline_api
node_pipeline_api -.->|"dispatches run"| node_pipeline_task
node_pipeline_task -->|"executes transforms"| node_transform_engine
node_transform_engine -->|"runs steps"| node_transform_steps
node_connections -->|"ingests data"| node_datasets
node_pipeline_task -->|"writes curated data"| node_datasets
node_datasets -->|"undergoes review"| node_curated_review
node_datasets -->|"maps datasets"| node_mapping
node_mapping -->|"discovers rules"| node_ontology
node_ontology -->|"publishes knowledge"| node_knowledge_graph
node_ontology -->|"enables search"| node_search
node_user -->|"requests audit"| node_quality_audit
node_quality_audit -->|"reviews quality"| node_ontology
node_user -->|"starts conversation"| node_agent_runtime
node_agent_runtime -->|"uses ontology tools"| node_agent_tools
node_user -->|"uploads documents"| node_document_extraction
node_document_extraction -->|"uses prompts"| node_prompts
node_user -->|"exports knowledge"| node_export
node_user -->|"authenticates"| node_auth

click node_pipeline_ui "https://github.com/jingw2/ontexus/blob/master/frontend/src/pages/pipelines/builder/PipelineBuilderPage.tsx"
click node_pipeline_api "https://github.com/jingw2/ontexus/blob/master/backend/app/routers/v2/pipelines.py"
click node_pipeline_task "https://github.com/jingw2/ontexus/blob/master/backend/app/tasks/v2/pipeline_run.py"
click node_transform_engine "https://github.com/jingw2/ontexus/blob/master/backend/app/services/v2/pipeline/engine.py"
click node_transform_steps "https://github.com/jingw2/ontexus/tree/master/backend/app/services/v2/pipeline/steps"
click node_datasets "https://github.com/jingw2/ontexus/blob/master/backend/app/models/v2/dataset.py"
click node_curated_review "https://github.com/jingw2/ontexus/blob/master/backend/app/services/v2/curated/review_service.py"
click node_connections "https://github.com/jingw2/ontexus/tree/master/backend/app/services/connection"
click node_mapping "https://github.com/jingw2/ontexus/blob/master/backend/app/services/v2/mapping/mapping_service.py"
click node_ontology "https://github.com/jingw2/ontexus/tree/master/backend/app/services/publication"
click node_knowledge_graph "https://github.com/jingw2/ontexus/tree/master/backend/app/services/v2/graph"
click node_search "https://github.com/jingw2/ontexus/tree/master/backend/app/services/v2/graph"
click node_quality_audit "https://github.com/jingw2/ontexus/blob/master/backend/app/routers/audit.py"
click node_agent_runtime "https://github.com/jingw2/ontexus/tree/master/backend/app/services/runtime"
click node_agent_tools "https://github.com/jingw2/ontexus/blob/master/backend/app/services/ontology_tools.py"
click node_document_extraction "https://github.com/jingw2/ontexus/blob/master/backend/app/routers/extraction.py"
click node_prompts "https://github.com/jingw2/ontexus/blob/master/backend/app/routers/prompts.py"
click node_export "https://github.com/jingw2/ontexus/blob/master/backend/app/services/export_service.py"
click node_auth "https://github.com/jingw2/ontexus/blob/master/backend/app/services/auth_service.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_pipeline_ui,node_pipeline_api,node_pipeline_task,node_transform_engine,node_transform_steps,node_datasets,node_curated_review,node_connections,node_user toneBlue
class node_mapping,node_ontology,node_knowledge_graph,node_search,node_quality_audit toneAmber
class node_agent_runtime,node_agent_tools toneMint
class node_document_extraction,node_prompts,node_export,node_auth toneRose
```

## Components

### Data Pipelines

- [Pipeline Builder](https://github.com/jingw2/ontexus/blob/master/frontend/src/pages/pipelines/builder/PipelineBuilderPage.tsx): `frontend/src/pages/pipelines/builder/PipelineBuilderPage.tsx`
- [Pipeline API](https://github.com/jingw2/ontexus/blob/master/backend/app/routers/v2/pipelines.py): `backend/app/routers/v2/pipelines.py`
- [Pipeline Runner](https://github.com/jingw2/ontexus/blob/master/backend/app/tasks/v2/pipeline_run.py): `backend/app/tasks/v2/pipeline_run.py`
- [Transform Engine](https://github.com/jingw2/ontexus/blob/master/backend/app/services/v2/pipeline/engine.py): `backend/app/services/v2/pipeline/engine.py`
- [Transform Steps](https://github.com/jingw2/ontexus/tree/master/backend/app/services/v2/pipeline/steps): `backend/app/services/v2/pipeline/steps`
- [Datasets](https://github.com/jingw2/ontexus/blob/master/backend/app/models/v2/dataset.py): `backend/app/models/v2/dataset.py`
- [Curated Review](https://github.com/jingw2/ontexus/blob/master/backend/app/services/v2/curated/review_service.py): `backend/app/services/v2/curated/review_service.py`
- [Data Connections](https://github.com/jingw2/ontexus/tree/master/backend/app/services/connection): `backend/app/services/connection`

### Ontology Platform

- [Ontology Mapping](https://github.com/jingw2/ontexus/blob/master/backend/app/services/v2/mapping/mapping_service.py): `backend/app/services/v2/mapping/mapping_service.py`
- [Ontology Lifecycle](https://github.com/jingw2/ontexus/tree/master/backend/app/services/publication): `backend/app/services/publication`
- [Knowledge Graph](https://github.com/jingw2/ontexus/tree/master/backend/app/services/v2/graph): `backend/app/services/v2/graph`
- [Ontology Search](https://github.com/jingw2/ontexus/tree/master/backend/app/services/v2/graph): `backend/app/services/v2/graph`
- [Quality Audit](https://github.com/jingw2/ontexus/blob/master/backend/app/routers/audit.py): `backend/app/routers/audit.py`

### Agent Runtime

- [Agent Execution](https://github.com/jingw2/ontexus/tree/master/backend/app/services/runtime): `backend/app/services/runtime`
- [Ontology Tools](https://github.com/jingw2/ontexus/blob/master/backend/app/services/ontology_tools.py): `backend/app/services/ontology_tools.py`

### Platform Services

- [LLM Extraction](https://github.com/jingw2/ontexus/blob/master/backend/app/routers/extraction.py): `backend/app/routers/extraction.py`
- [Prompt Management](https://github.com/jingw2/ontexus/blob/master/backend/app/routers/prompts.py): `backend/app/routers/prompts.py`
- [Data Export](https://github.com/jingw2/ontexus/blob/master/backend/app/services/export_service.py): `backend/app/services/export_service.py`
- [User Access](https://github.com/jingw2/ontexus/blob/master/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`

### Other components

- **User**

## Connections

- User → Pipeline Builder: builds pipelines (evidence: `README.md`)
- Pipeline Builder → Pipeline API: runs pipeline
- Pipeline API → Pipeline Runner: dispatches run (evidence: `backend/app/routers/v2/pipelines.py`)
- Pipeline Runner → Transform Engine: executes transforms (evidence: `backend/app/tasks/v2/pipeline_run.py`)
- Transform Engine → Transform Steps: runs steps (evidence: `backend/app/services/v2/pipeline/engine.py`)
- Data Connections → Datasets: ingests data (evidence: `README.md`)
- Pipeline Runner → Datasets: writes curated data (evidence: `backend/app/tasks/v2/pipeline_run.py`)
- Datasets → Curated Review: undergoes review (evidence: `README.md`)
- Datasets → Ontology Mapping: maps datasets (evidence: `README.md`)
- Ontology Mapping → Ontology Lifecycle: discovers rules (evidence: `README.md`)
- Ontology Lifecycle → Knowledge Graph: publishes knowledge (evidence: `README.md`)
- Ontology Lifecycle → Ontology Search: enables search (evidence: `README.md`)
- User → Quality Audit: requests audit (evidence: `README.md`)
- Quality Audit → Ontology Lifecycle: reviews quality (evidence: `README.md`)
- User → Agent Execution: starts conversation (evidence: `README.md`)
- Agent Execution → Ontology Tools: uses ontology tools (evidence: `README.md`)
- User → LLM Extraction: uploads documents (evidence: `README.md`)
- LLM Extraction → Prompt Management: uses prompts (evidence: `README.md`)
- User → Data Export: exports knowledge (evidence: `README.md`)
- User → User Access: authenticates (evidence: `README.md`)
