# uengine-oss/ontology-studio architecture

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

- Interactive diagram: https://gitdiagram.com/uengine-oss/ontology-studio
- Repository: https://github.com/uengine-oss/ontology-studio

## Overview

Ontology Studio is a web application for designing ontology schemas, extracting entities and relationships from documents, and storing graph data in Neo4j. The principal workflow runs from the Vue interface through FastAPI and agent tools into ontology-building and quality-review stages; users can also manage files, data sources, and dashboards. A separate read-only MCP server exposes ontology search, while an agent bridge exposes mode-specific studio tools. The README documents these capabilities; some subsystem paths and internal links below are based on the tree and source index rather than sampled implementation.

Main entry points: [`backend/src/modules/ontology/tools.py`](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/ontology/tools.py) (Ontology tools), [`backend/src/host/app.py`](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/host/app.py) (FastAPI host), [`backend/src/modules/agent_session/service.py`](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/agent_session/service.py) (Agent runtime), [`desktop/src/main/index.js`](https://github.com/uengine-oss/ontology-studio/blob/main/desktop/src/main/index.js) (Desktop runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Studio interface"]
  node_frontend["Vue application<br/>[AppShell.vue]"]
  node_chat["Agent chat<br/>[ChatPanel.vue]"]
  node_ontology_ui["Ontology workspace"]
  node_quality_ui["Quality review<br/>[ReviewDeck.vue]"]
  node_board_ui["Dashboard workspace<br/>[useBoard.js]"]
  node_files_ui["File workspace<br/>[FilePanel.vue]"]
end

subgraph group_backend["Backend workflows"]
  node_api_host["FastAPI host<br/>[app.py]"]
  node_agent_api["Agent session API<br/>[api.py]"]
  node_agent_service["Agent runtime<br/>[service.py]"]
  node_agent_bridge["Agent MCP bridge<br/>[server.py]"]
  node_files["Workspace files<br/>[service.py]"]
end

subgraph group_domain["Ontology and data"]
  node_doc_index["Document indexing<br/>[service.py]"]
  node_ontology_tools["Ontology tools<br/>[tools.py]"]
  node_ontology_api["Ontology API<br/>[api.py]"]
  node_datasource["Data source access<br/>[datasource_api.py]"]
  node_quality["Quality pipeline<br/>[pipeline.py]"]
  node_quality_gate["Ingest gate<br/>[ingest_gate.py]"]
  node_board["Board services<br/>[service.py]"]
end

subgraph group_integrations["Runtime integrations"]
  node_mcp_search["Ontology search MCP<br/>[server.py]"]
  node_neo4j[("Neo4j graph")]
  node_model_api["OpenAI-compatible model"]
  node_desktop["Desktop runtime<br/>[index.js]"]
  node_desktop_engine["Container engine discovery<br/>[engine.js]"]
  node_desktop_files["Local workspace access<br/>[localfs.js]"]
  node_desktop_logs["Desktop logging<br/>[log.js]"]
end

node_user(("Studio user"))

node_user -->|"uses"| node_frontend
node_frontend -->|"calls API"| node_api_host
node_api_host -->|"registers"| node_agent_api
node_api_host -->|"registers"| node_ontology_api
node_api_host -->|"registers API"| node_files
node_api_host -->|"registers API"| node_board
node_api_host -->|"registers API"| node_quality
node_agent_api -->|"delegates to"| node_agent_service
node_agent_service -->|"uses workspace"| node_files
node_agent_service -->|"uses tools"| node_ontology_tools
node_agent_bridge -->|"registers tools"| node_agent_service
node_files -.->|"shares workspace concept"| node_desktop_files
node_doc_index -->|"reads files"| node_files
node_doc_index -->|"uses ontology tools"| node_ontology_tools
node_ontology_api -.->|"uses tools"| node_ontology_tools
node_ontology_tools -->|"queries graph"| node_neo4j
node_quality -->|"routes writes"| node_quality_gate
node_quality_gate -->|"writes candidates"| node_neo4j
node_quality -->|"uses ontology"| node_ontology_tools
node_datasource -.->|"uses data access"| node_ontology_tools
node_board -.->|"uses ontology tools"| node_ontology_tools
node_mcp_search -.->|"searches graph"| node_neo4j
node_agent_service -.->|"invokes model"| node_model_api
node_user -.->|"launches"| node_desktop
node_desktop -->|"resolves engine"| node_desktop_engine
node_desktop -->|"uses local files"| node_desktop_files
node_desktop -.->|"logs startup"| node_desktop_logs
node_desktop_engine -->|"reports status"| node_desktop_logs

click node_frontend "https://github.com/uengine-oss/ontology-studio/blob/main/frontend/src/host/AppShell.vue"
click node_chat "https://github.com/uengine-oss/ontology-studio/blob/main/frontend/src/features/chat/ChatPanel.vue"
click node_ontology_ui "https://github.com/uengine-oss/ontology-studio/blob/main/frontend/src/features/ontology/OntologyGraphPanel.vue"
click node_quality_ui "https://github.com/uengine-oss/ontology-studio/blob/main/frontend/src/features/quality/ReviewDeck.vue"
click node_board_ui "https://github.com/uengine-oss/ontology-studio/blob/main/frontend/src/features/board/useBoard.js"
click node_files_ui "https://github.com/uengine-oss/ontology-studio/blob/main/frontend/src/features/files/FilePanel.vue"
click node_api_host "https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/host/app.py"
click node_agent_api "https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/agent_session/api.py"
click node_agent_service "https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/agent_session/service.py"
click node_agent_bridge "https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/agent_bridge_mcp/server.py"
click node_files "https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/files/service.py"
click node_doc_index "https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/document_indexing/service.py"
click node_ontology_tools "https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/ontology/tools.py"
click node_ontology_api "https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/ontology/api.py"
click node_datasource "https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/ontology/datasource_api.py"
click node_quality "https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/quality/pipeline.py"
click node_quality_gate "https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/quality/ingest_gate.py"
click node_board "https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/board/service.py"
click node_mcp_search "https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/ontology_mcp/server.py"
click node_desktop "https://github.com/uengine-oss/ontology-studio/blob/main/desktop/src/main/index.js"
click node_desktop_engine "https://github.com/uengine-oss/ontology-studio/blob/main/desktop/src/main/engine.js"
click node_desktop_files "https://github.com/uengine-oss/ontology-studio/blob/main/desktop/src/main/localfs.js"
click node_desktop_logs "https://github.com/uengine-oss/ontology-studio/blob/main/desktop/src/main/log.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_frontend,node_chat,node_ontology_ui,node_quality_ui,node_board_ui,node_files_ui,node_user toneBlue
class node_api_host,node_agent_api,node_agent_service,node_agent_bridge,node_files toneAmber
class node_doc_index,node_ontology_tools,node_ontology_api,node_datasource,node_quality,node_quality_gate,node_board toneMint
class node_mcp_search,node_neo4j,node_model_api,node_desktop,node_desktop_engine,node_desktop_files,node_desktop_logs toneRose
```

## Components

### Studio interface

- [Vue application](https://github.com/uengine-oss/ontology-studio/blob/main/frontend/src/host/AppShell.vue): `frontend/src/host/AppShell.vue`
- [Agent chat](https://github.com/uengine-oss/ontology-studio/blob/main/frontend/src/features/chat/ChatPanel.vue): `frontend/src/features/chat/ChatPanel.vue`
- [Ontology workspace](https://github.com/uengine-oss/ontology-studio/blob/main/frontend/src/features/ontology/OntologyGraphPanel.vue): `frontend/src/features/ontology/OntologyGraphPanel.vue`
- [Quality review](https://github.com/uengine-oss/ontology-studio/blob/main/frontend/src/features/quality/ReviewDeck.vue): `frontend/src/features/quality/ReviewDeck.vue`
- [Dashboard workspace](https://github.com/uengine-oss/ontology-studio/blob/main/frontend/src/features/board/useBoard.js): `frontend/src/features/board/useBoard.js`
- [File workspace](https://github.com/uengine-oss/ontology-studio/blob/main/frontend/src/features/files/FilePanel.vue): `frontend/src/features/files/FilePanel.vue`

### Backend workflows

- [FastAPI host](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/host/app.py): `backend/src/host/app.py`
- [Agent session API](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/agent_session/api.py): `backend/src/modules/agent_session/api.py`
- [Agent runtime](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/agent_session/service.py): `backend/src/modules/agent_session/service.py`
- [Agent MCP bridge](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/agent_bridge_mcp/server.py): `backend/src/modules/agent_bridge_mcp/server.py`
- [Workspace files](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/files/service.py): `backend/src/modules/files/service.py`

### Ontology and data

- [Document indexing](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/document_indexing/service.py): `backend/src/modules/document_indexing/service.py`
- [Ontology tools](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/ontology/tools.py): `backend/src/modules/ontology/tools.py`
- [Ontology API](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/ontology/api.py): `backend/src/modules/ontology/api.py`
- [Data source access](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/ontology/datasource_api.py): `backend/src/modules/ontology/datasource_api.py`
- [Quality pipeline](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/quality/pipeline.py): `backend/src/modules/quality/pipeline.py`
- [Ingest gate](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/quality/ingest_gate.py): `backend/src/modules/quality/ingest_gate.py`
- [Board services](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/board/service.py): `backend/src/modules/board/service.py`

### Runtime integrations

- [Ontology search MCP](https://github.com/uengine-oss/ontology-studio/blob/main/backend/src/modules/ontology_mcp/server.py): `backend/src/modules/ontology_mcp/server.py`
- **Neo4j graph**
- **OpenAI-compatible model**
- [Desktop runtime](https://github.com/uengine-oss/ontology-studio/blob/main/desktop/src/main/index.js): `desktop/src/main/index.js`
- [Container engine discovery](https://github.com/uengine-oss/ontology-studio/blob/main/desktop/src/main/engine.js): `desktop/src/main/engine.js`
- [Local workspace access](https://github.com/uengine-oss/ontology-studio/blob/main/desktop/src/main/localfs.js): `desktop/src/main/localfs.js`
- [Desktop logging](https://github.com/uengine-oss/ontology-studio/blob/main/desktop/src/main/log.js): `desktop/src/main/log.js`

### Other components

- **Studio user**

## Connections

- Studio user → Vue application: uses
- Vue application → FastAPI host: calls API
- FastAPI host → Agent session API: registers (evidence: `backend/src/host/app.py`)
- FastAPI host → Ontology API: registers (evidence: `backend/src/host/app.py`)
- FastAPI host → Workspace files: registers API (evidence: `backend/src/host/app.py`)
- FastAPI host → Board services: registers API (evidence: `backend/src/host/app.py`)
- FastAPI host → Quality pipeline: registers API (evidence: `backend/src/host/app.py`)
- Agent session API → Agent runtime: delegates to (evidence: `backend/src/modules/agent_session/api.py`)
- Agent runtime → Workspace files: uses workspace (evidence: `backend/src/modules/agent_session/service.py`)
- Agent runtime → Ontology tools: uses tools (evidence: `backend/src/modules/agent_session/service.py`)
- Agent MCP bridge → Agent runtime: registers tools (evidence: `backend/src/modules/agent_bridge_mcp/server.py`)
- Workspace files → Local workspace access: shares workspace concept
- Document indexing → Workspace files: reads files (evidence: `backend/src/modules/document_indexing/service.py`)
- Document indexing → Ontology tools: uses ontology tools (evidence: `backend/src/modules/document_indexing/service.py`)
- Ontology API → Ontology tools: uses tools
- Ontology tools → Neo4j graph: queries graph (evidence: `backend/src/modules/ontology/tools.py`)
- Quality pipeline → Ingest gate: routes writes (evidence: `backend/src/modules/quality/pipeline.py`)
- Ingest gate → Neo4j graph: writes candidates (evidence: `backend/src/modules/quality/ingest_gate.py`)
- Quality pipeline → Ontology tools: uses ontology (evidence: `backend/src/modules/quality/pipeline.py`)
- Data source access → Ontology tools: uses data access
- Board services → Ontology tools: uses ontology tools
- Ontology search MCP → Neo4j graph: searches graph
- Agent runtime → OpenAI-compatible model: invokes model
- Studio user → Desktop runtime: launches
- Desktop runtime → Container engine discovery: resolves engine (evidence: `desktop/src/main/index.js`)
- Desktop runtime → Local workspace access: uses local files (evidence: `desktop/src/main/index.js`)
- Desktop runtime → Desktop logging: logs startup (evidence: `desktop/src/main/index.js`)
- Container engine discovery → Desktop logging: reports status (evidence: `desktop/src/main/engine.js`)