# modellismz/openskilltrace architecture

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

- Interactive diagram: https://gitdiagram.com/modellismz/openskilltrace
- Repository: https://github.com/modellismz/openskilltrace

## Overview

OpenSkillTrace is a governed AgentOps platform: operators build and preview workflows, then manage cases, approvals, audit, and operational fallbacks. Its flagship fraud-response flow collects a claim, gathers evidence, grounds decisions in RAG, classifies risk, and routes actions for human approval. The frontend talks to a FastAPI backend, which owns workflow execution, persistence, model routing, and integrations. MCP exposes backend operations to external clients; a separate worker processes queued RAG jobs. Some UI capabilities are README-documented but their implementation was not sampled.

Main entry points: [`backend/main.py`](https://github.com/modellismz/openskilltrace/blob/main/backend/main.py) (FastAPI backend), [`index.html`](https://github.com/modellismz/openskilltrace/blob/main/index.html) (Web application), [`backend/rag.py`](https://github.com/modellismz/openskilltrace/blob/main/backend/rag.py) (Governed RAG), [`backend/mcp_server.py`](https://github.com/modellismz/openskilltrace/blob/main/backend/mcp_server.py) (MCP tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator_ui["Operator interface"]
  node_web_app["Web application<br/>[index.html]"]
  node_overview["Ops dashboard<br/>[app.js]"]
  node_studio["Workflow Studio<br/>[studio.js]"]
  node_case_views["Cases and tickets"]
  node_warroom["War room<br/>[views-warroom.js]"]
  node_ops_views["Ops controls"]
end

subgraph group_workflow_ops["Workflow operations"]
  node_workflow_api["FastAPI backend<br/>[main.py]"]
  node_intake["Claim intake<br/>[main.py]"]
  node_evidence["Evidence gathering<br/>[main.py]"]
  node_classification["Risk classification<br/>[main.py]"]
  node_preview_runner["Preview runner<br/>[main.py]"]
  node_repair_harness["Repair harness<br/>[main.py]"]
  node_approval["Human approval<br/>[main.py]"]
  node_agent_store[("AgentOps JSON store<br/>[main.py]")]
end

subgraph group_knowledge_governance["Knowledge and governance"]
  node_rag_service["Governed RAG<br/>[rag.py]"]
  node_rag_worker["RAG job worker<br/>[rag_worker.py]"]
  node_rag_sqlite[("RAG SQLite index<br/>[rag.py]")]
  node_audit_policy["Audit and policy<br/>[main.py]"]
end

subgraph group_integrations["External integrations"]
  node_mcp_server["MCP tools<br/>[mcp_server.py]"]
  node_model_providers["Model providers"]
  node_qdrant[("Qdrant")]
  node_telegram["Telegram Bot API"]
end

node_operator(("Operations team"))
node_mcp_client(("MCP client"))

node_operator -->|"uses"| node_web_app
node_web_app -->|"renders"| node_overview
node_web_app -->|"renders"| node_studio
node_web_app -->|"renders"| node_case_views
node_web_app -->|"renders"| node_warroom
node_web_app -->|"renders"| node_ops_views
node_overview -->|"calls API"| node_workflow_api
node_studio -->|"runs previews"| node_workflow_api
node_case_views -->|"manages cases"| node_workflow_api
node_warroom -->|"calls API"| node_workflow_api
node_ops_views -->|"calls API"| node_workflow_api
node_workflow_api -->|"handles claims"| node_intake
node_workflow_api -->|"gathers evidence"| node_evidence
node_workflow_api -->|"classifies risk"| node_classification
node_workflow_api -->|"executes workflow"| node_preview_runner
node_workflow_api -->|"creates repair"| node_repair_harness
node_workflow_api -->|"routes decisions"| node_approval
node_workflow_api -->|"reads and writes"| node_agent_store
node_workflow_api -->|"retrieves knowledge"| node_rag_service
node_workflow_api -->|"routes model calls"| node_model_providers
node_workflow_api -.->|"sends alerts"| node_telegram
node_rag_worker -->|"processes jobs"| node_rag_service
node_rag_service -->|"stores and searches"| node_rag_sqlite
node_rag_service -.->|"vector search"| node_qdrant
node_workflow_api -->|"applies controls"| node_audit_policy
node_mcp_client -->|"invokes tools"| node_mcp_server
node_mcp_server -->|"calls operations"| node_workflow_api
node_mcp_server -->|"calls RAG"| node_rag_service

click node_web_app "https://github.com/modellismz/openskilltrace/blob/main/index.html"
click node_overview "https://github.com/modellismz/openskilltrace/blob/main/assets/app.js"
click node_studio "https://github.com/modellismz/openskilltrace/blob/main/assets/studio.js"
click node_case_views "https://github.com/modellismz/openskilltrace/blob/main/assets/views-notifications.js"
click node_warroom "https://github.com/modellismz/openskilltrace/blob/main/assets/views-warroom.js"
click node_ops_views "https://github.com/modellismz/openskilltrace/blob/main/assets/views-reliability.js"
click node_workflow_api "https://github.com/modellismz/openskilltrace/blob/main/backend/main.py"
click node_intake "https://github.com/modellismz/openskilltrace/blob/main/backend/main.py"
click node_evidence "https://github.com/modellismz/openskilltrace/blob/main/backend/main.py"
click node_classification "https://github.com/modellismz/openskilltrace/blob/main/backend/main.py"
click node_preview_runner "https://github.com/modellismz/openskilltrace/blob/main/backend/main.py"
click node_repair_harness "https://github.com/modellismz/openskilltrace/blob/main/backend/main.py"
click node_approval "https://github.com/modellismz/openskilltrace/blob/main/backend/main.py"
click node_agent_store "https://github.com/modellismz/openskilltrace/blob/main/backend/main.py"
click node_rag_service "https://github.com/modellismz/openskilltrace/blob/main/backend/rag.py"
click node_rag_worker "https://github.com/modellismz/openskilltrace/blob/main/backend/rag_worker.py"
click node_rag_sqlite "https://github.com/modellismz/openskilltrace/blob/main/backend/rag.py"
click node_audit_policy "https://github.com/modellismz/openskilltrace/blob/main/backend/main.py"
click node_mcp_server "https://github.com/modellismz/openskilltrace/blob/main/backend/mcp_server.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_web_app,node_overview,node_studio,node_case_views,node_warroom,node_ops_views,node_mcp_client toneBlue
class node_workflow_api,node_intake,node_evidence,node_classification,node_preview_runner,node_repair_harness,node_approval,node_agent_store toneAmber
class node_rag_service,node_rag_worker,node_rag_sqlite,node_audit_policy toneMint
class node_mcp_server,node_model_providers,node_qdrant,node_telegram toneRose
class node_operator toneIndigo
```

## Components

### Operator interface

- [Web application](https://github.com/modellismz/openskilltrace/blob/main/index.html): `index.html`
- [Ops dashboard](https://github.com/modellismz/openskilltrace/blob/main/assets/app.js): `assets/app.js`
- [Workflow Studio](https://github.com/modellismz/openskilltrace/blob/main/assets/studio.js): `assets/studio.js`
- [Cases and tickets](https://github.com/modellismz/openskilltrace/blob/main/assets/views-notifications.js): `assets/views-notifications.js`
- [War room](https://github.com/modellismz/openskilltrace/blob/main/assets/views-warroom.js): `assets/views-warroom.js`
- [Ops controls](https://github.com/modellismz/openskilltrace/blob/main/assets/views-reliability.js): `assets/views-reliability.js`

### Workflow operations

- [FastAPI backend](https://github.com/modellismz/openskilltrace/blob/main/backend/main.py): `backend/main.py`
- [Claim intake](https://github.com/modellismz/openskilltrace/blob/main/backend/main.py): `backend/main.py`
- [Evidence gathering](https://github.com/modellismz/openskilltrace/blob/main/backend/main.py): `backend/main.py`
- [Risk classification](https://github.com/modellismz/openskilltrace/blob/main/backend/main.py): `backend/main.py`
- [Preview runner](https://github.com/modellismz/openskilltrace/blob/main/backend/main.py): `backend/main.py`
- [Repair harness](https://github.com/modellismz/openskilltrace/blob/main/backend/main.py): `backend/main.py`
- [Human approval](https://github.com/modellismz/openskilltrace/blob/main/backend/main.py): `backend/main.py`
- [AgentOps JSON store](https://github.com/modellismz/openskilltrace/blob/main/backend/main.py): `backend/main.py`

### Knowledge and governance

- [Governed RAG](https://github.com/modellismz/openskilltrace/blob/main/backend/rag.py): `backend/rag.py`
- [RAG job worker](https://github.com/modellismz/openskilltrace/blob/main/backend/rag_worker.py): `backend/rag_worker.py`
- [RAG SQLite index](https://github.com/modellismz/openskilltrace/blob/main/backend/rag.py): `backend/rag.py`
- [Audit and policy](https://github.com/modellismz/openskilltrace/blob/main/backend/main.py): `backend/main.py`

### External integrations

- [MCP tools](https://github.com/modellismz/openskilltrace/blob/main/backend/mcp_server.py): `backend/mcp_server.py`
- **Model providers**
- **Qdrant**
- **Telegram Bot API**

### Other components

- **Operations team**
- **MCP client**

## Connections

- Operations team → Web application: uses
- Web application → Ops dashboard: renders
- Web application → Workflow Studio: renders
- Web application → Cases and tickets: renders
- Web application → War room: renders
- Web application → Ops controls: renders
- Ops dashboard → FastAPI backend: calls API
- Workflow Studio → FastAPI backend: runs previews
- Cases and tickets → FastAPI backend: manages cases
- War room → FastAPI backend: calls API
- Ops controls → FastAPI backend: calls API
- FastAPI backend → Claim intake: handles claims
- FastAPI backend → Evidence gathering: gathers evidence
- FastAPI backend → Risk classification: classifies risk
- FastAPI backend → Preview runner: executes workflow
- FastAPI backend → Repair harness: creates repair
- FastAPI backend → Human approval: routes decisions
- FastAPI backend → AgentOps JSON store: reads and writes
- FastAPI backend → Governed RAG: retrieves knowledge
- FastAPI backend → Model providers: routes model calls
- FastAPI backend → Telegram Bot API: sends alerts
- RAG job worker → Governed RAG: processes jobs
- Governed RAG → RAG SQLite index: stores and searches
- Governed RAG → Qdrant: vector search
- FastAPI backend → Audit and policy: applies controls
- MCP client → MCP tools: invokes tools
- MCP tools → FastAPI backend: calls operations
- MCP tools → Governed RAG: calls RAG