# horizon-sky/agentops architecture

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

- Interactive diagram: https://gitdiagram.com/horizon-sky/agentops
- Repository: https://github.com/horizon-sky/agentops

## Overview

AgentOps is a user-facing engineering-ticket automation agent. A user submits a request in the workspace; the API starts a stateful run, which classifies and plans work, retrieves cited knowledge, invokes tools, pauses for approval before writes, and returns an answer. The workspace also supports document ingestion, ticket management, trace replay, and evaluation reporting. The graph retains README-documented capabilities whose implementation was not sampled; those relationships are omitted where no excerpt or documented connection establishes them.

Main entry points: [`apps/api/src/main.py`](https://github.com/horizon-sky/agentops/blob/main/apps/api/src/main.py) (FastAPI app), [`src/db/models.py`](https://github.com/horizon-sky/agentops/blob/main/src/db/models.py) (Postgres pgvector), [`apps/web/app/api/[...path]/route.ts`](https://github.com/horizon-sky/agentops/blob/main/apps/web/app/api/%5B...path%5D/route.ts) (Web API proxy), [`src/agent/nodes`](https://github.com/horizon-sky/agentops/tree/main/src/agent/nodes) (Agent stages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_web["Workspace UI<br/>[page.tsx]"]
  node_run_ui["Run stream UI<br/>[useRun.ts]"]
  node_approval["Approval card<br/>[ApprovalCard.tsx]"]
  node_document_ui["Document ingest UI<br/>[DocumentIngest.tsx]"]
  node_tickets_ui["Ticket overview<br/>[page.tsx]"]
  node_traces_ui["Trace replay UI<br/>[page.tsx]"]
  node_eval_ui["Evaluation dashboard<br/>[page.tsx]"]
end

subgraph group_api["API and identity"]
  node_proxy["Web API proxy<br/>[route.ts]"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_auth_routes["Account routes<br/>[auth.py]"]
  node_run_routes["Run routes<br/>[runs.py]"]
  node_ingest_route["Ingest route<br/>[ingest.py]"]
  node_ticket_routes["Ticket routes<br/>[tickets.py]"]
  node_trace_routes["Trace routes<br/>[traces.py]"]
  node_eval_routes["Evaluation route<br/>[eval.py]"]
  node_auth["Identity services<br/>[auth.py]"]
end

subgraph group_agent["Agent execution"]
  node_graph{{"Agent state graph<br/>[graph.py]"}}
  node_agent_nodes["Agent stages"]
  node_agent_context["Run context<br/>[context.py]"]
  node_agent_events["Event emission<br/>[emit.py]"]
  node_agent_model["Model access<br/>[model.py]"]
  node_tool_registry["Tool registry<br/>[registry.py]"]
  node_builtin_tools["Built-in tools<br/>[builtin.py]"]
  node_mcp_services["MCP servers"]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_rag_ingest["Document processing<br/>[ingest.py]"]
  node_hybrid_search["Hybrid search<br/>[hybrid_search.py]"]
  node_retrieve_node["Retrieval stage<br/>[retrieve.py]"]
end

subgraph group_state["Persistence and insight"]
  node_database[("Postgres pgvector<br/>[models.py]")]
  node_db_session["Database sessions<br/>[session.py]"]
  node_cache[("Cache<br/>[cache.py]")]
  node_tracing["Trace recorder<br/>[tracing.py]"]
  node_eval_runner["Evaluation runner<br/>[runner.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

node_user(("Engineer"))

node_user -->|"submits request"| node_web
node_web -->|"calls API"| node_proxy
node_proxy -->|"proxies REST"| node_api_app
node_api_app -->|"registers routes"| node_run_routes
node_api_app -->|"registers routes"| node_ingest_route
node_api_app -->|"registers routes"| node_auth_routes
node_api_app -->|"registers routes"| node_ticket_routes
node_api_app -->|"registers routes"| node_trace_routes
node_api_app -->|"registers routes"| node_eval_routes
node_run_ui -->|"streams runs"| node_proxy
node_run_routes -->|"starts or resumes"| node_graph
node_graph -.->|"dispatches stages"| node_agent_nodes
node_agent_nodes -->|"includes retrieval"| node_retrieve_node
node_retrieve_node -->|"searches evidence"| node_hybrid_search
node_hybrid_search -->|"queries chunks"| node_database
node_hybrid_search -->|"builds embedder"| node_agent_model
node_retrieve_node -->|"emits retrieval event"| node_agent_events
node_agent_nodes -.->|"invokes tools"| node_tool_registry
node_tool_registry -->|"dispatches tools"| node_builtin_tools
node_builtin_tools -->|"persists approved ticket"| node_database
node_tool_registry -.->|"offers MCP tools"| node_mcp_services
node_approval -->|"confirms writes"| node_run_routes
node_ingest_route -->|"ingests document"| node_rag_ingest
node_rag_ingest -->|"stores chunks"| node_database
node_rag_ingest -->|"opens session"| node_db_session
node_rag_ingest -->|"embeds text"| node_agent_model
node_document_ui -->|"uploads document"| node_proxy
node_ticket_routes -.->|"manages tickets"| node_database
node_tickets_ui -->|"manages tickets"| node_proxy
node_trace_routes -.->|"serves spans"| node_database
node_tracing -->|"records spans"| node_database
node_traces_ui -->|"loads trace"| node_proxy
node_eval_ui -->|"loads report"| node_proxy
node_eval_routes -.->|"serves report"| node_eval_runner
node_eval_runner -->|"runs agent"| node_graph
node_auth_routes -->|"authenticates users"| node_auth
node_auth -->|"checks sessions"| node_database
node_api_app -->|"reports cache health"| node_cache
node_agent_nodes -.->|"uses run context"| node_agent_context
node_agent_nodes -.->|"uses model"| node_agent_model
node_api_app -->|"initializes database"| node_db_session
node_db_session -->|"connects to"| node_database

click node_web "https://github.com/horizon-sky/agentops/blob/main/apps/web/app/(workspace)/page.tsx"
click node_run_ui "https://github.com/horizon-sky/agentops/blob/main/apps/web/lib/useRun.ts"
click node_approval "https://github.com/horizon-sky/agentops/blob/main/apps/web/components/ApprovalCard.tsx"
click node_document_ui "https://github.com/horizon-sky/agentops/blob/main/apps/web/components/DocumentIngest.tsx"
click node_tickets_ui "https://github.com/horizon-sky/agentops/blob/main/apps/web/app/(workspace)/tickets/page.tsx"
click node_traces_ui "https://github.com/horizon-sky/agentops/blob/main/apps/web/app/(workspace)/traces/page.tsx"
click node_eval_ui "https://github.com/horizon-sky/agentops/blob/main/apps/web/app/(workspace)/evals/page.tsx"
click node_proxy "https://github.com/horizon-sky/agentops/blob/main/apps/web/app/api/%5B...path%5D/route.ts"
click node_api_app "https://github.com/horizon-sky/agentops/blob/main/apps/api/src/main.py"
click node_auth_routes "https://github.com/horizon-sky/agentops/blob/main/apps/api/src/routers/auth.py"
click node_run_routes "https://github.com/horizon-sky/agentops/blob/main/apps/api/src/routers/runs.py"
click node_ingest_route "https://github.com/horizon-sky/agentops/blob/main/apps/api/src/routers/ingest.py"
click node_ticket_routes "https://github.com/horizon-sky/agentops/blob/main/apps/api/src/routers/tickets.py"
click node_trace_routes "https://github.com/horizon-sky/agentops/blob/main/apps/api/src/routers/traces.py"
click node_eval_routes "https://github.com/horizon-sky/agentops/blob/main/apps/api/src/routers/eval.py"
click node_auth "https://github.com/horizon-sky/agentops/blob/main/src/auth.py"
click node_graph "https://github.com/horizon-sky/agentops/blob/main/src/agent/graph.py"
click node_agent_nodes "https://github.com/horizon-sky/agentops/tree/main/src/agent/nodes"
click node_agent_context "https://github.com/horizon-sky/agentops/blob/main/src/agent/context.py"
click node_agent_events "https://github.com/horizon-sky/agentops/blob/main/src/agent/emit.py"
click node_agent_model "https://github.com/horizon-sky/agentops/blob/main/src/agent/model.py"
click node_tool_registry "https://github.com/horizon-sky/agentops/blob/main/src/tools/registry.py"
click node_builtin_tools "https://github.com/horizon-sky/agentops/blob/main/src/tools/builtin.py"
click node_mcp_services "https://github.com/horizon-sky/agentops/tree/main/services"
click node_rag_ingest "https://github.com/horizon-sky/agentops/blob/main/src/rag/ingest.py"
click node_hybrid_search "https://github.com/horizon-sky/agentops/blob/main/src/rag/hybrid_search.py"
click node_retrieve_node "https://github.com/horizon-sky/agentops/blob/main/src/agent/nodes/retrieve.py"
click node_database "https://github.com/horizon-sky/agentops/blob/main/src/db/models.py"
click node_db_session "https://github.com/horizon-sky/agentops/blob/main/src/db/session.py"
click node_cache "https://github.com/horizon-sky/agentops/blob/main/src/db/cache.py"
click node_tracing "https://github.com/horizon-sky/agentops/blob/main/src/agent/tracing.py"
click node_eval_runner "https://github.com/horizon-sky/agentops/blob/main/evals/runner.py"
click node_settings "https://github.com/horizon-sky/agentops/blob/main/src/config.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,node_run_ui,node_approval,node_document_ui,node_tickets_ui,node_traces_ui,node_eval_ui toneBlue
class node_proxy,node_api_app,node_auth_routes,node_run_routes,node_ingest_route,node_ticket_routes,node_trace_routes,node_eval_routes,node_auth toneAmber
class node_graph,node_agent_nodes,node_agent_context,node_agent_events,node_agent_model,node_tool_registry,node_builtin_tools,node_mcp_services toneMint
class node_rag_ingest,node_hybrid_search,node_retrieve_node toneRose
class node_database,node_db_session,node_cache,node_tracing,node_eval_runner,node_settings,node_user toneIndigo
```

## Components

### Workspace

- [Workspace UI](https://github.com/horizon-sky/agentops/blob/main/apps/web/app/(workspace)/page.tsx): `apps/web/app/(workspace)/page.tsx`
- [Run stream UI](https://github.com/horizon-sky/agentops/blob/main/apps/web/lib/useRun.ts): `apps/web/lib/useRun.ts`
- [Approval card](https://github.com/horizon-sky/agentops/blob/main/apps/web/components/ApprovalCard.tsx): `apps/web/components/ApprovalCard.tsx`
- [Document ingest UI](https://github.com/horizon-sky/agentops/blob/main/apps/web/components/DocumentIngest.tsx): `apps/web/components/DocumentIngest.tsx`
- [Ticket overview](https://github.com/horizon-sky/agentops/blob/main/apps/web/app/(workspace)/tickets/page.tsx): `apps/web/app/(workspace)/tickets/page.tsx`
- [Trace replay UI](https://github.com/horizon-sky/agentops/blob/main/apps/web/app/(workspace)/traces/page.tsx): `apps/web/app/(workspace)/traces/page.tsx`
- [Evaluation dashboard](https://github.com/horizon-sky/agentops/blob/main/apps/web/app/(workspace)/evals/page.tsx): `apps/web/app/(workspace)/evals/page.tsx`

### API and identity

- [Web API proxy](https://github.com/horizon-sky/agentops/blob/main/apps/web/app/api/%5B...path%5D/route.ts): `apps/web/app/api/[...path]/route.ts`
- [FastAPI app](https://github.com/horizon-sky/agentops/blob/main/apps/api/src/main.py): `apps/api/src/main.py`
- [Account routes](https://github.com/horizon-sky/agentops/blob/main/apps/api/src/routers/auth.py): `apps/api/src/routers/auth.py`
- [Run routes](https://github.com/horizon-sky/agentops/blob/main/apps/api/src/routers/runs.py): `apps/api/src/routers/runs.py`
- [Ingest route](https://github.com/horizon-sky/agentops/blob/main/apps/api/src/routers/ingest.py): `apps/api/src/routers/ingest.py`
- [Ticket routes](https://github.com/horizon-sky/agentops/blob/main/apps/api/src/routers/tickets.py): `apps/api/src/routers/tickets.py`
- [Trace routes](https://github.com/horizon-sky/agentops/blob/main/apps/api/src/routers/traces.py): `apps/api/src/routers/traces.py`
- [Evaluation route](https://github.com/horizon-sky/agentops/blob/main/apps/api/src/routers/eval.py): `apps/api/src/routers/eval.py`
- [Identity services](https://github.com/horizon-sky/agentops/blob/main/src/auth.py): `src/auth.py`

### Agent execution

- [Agent state graph](https://github.com/horizon-sky/agentops/blob/main/src/agent/graph.py): `src/agent/graph.py`
- [Agent stages](https://github.com/horizon-sky/agentops/tree/main/src/agent/nodes): `src/agent/nodes`
- [Run context](https://github.com/horizon-sky/agentops/blob/main/src/agent/context.py): `src/agent/context.py`
- [Event emission](https://github.com/horizon-sky/agentops/blob/main/src/agent/emit.py): `src/agent/emit.py`
- [Model access](https://github.com/horizon-sky/agentops/blob/main/src/agent/model.py): `src/agent/model.py`
- [Tool registry](https://github.com/horizon-sky/agentops/blob/main/src/tools/registry.py): `src/tools/registry.py`
- [Built-in tools](https://github.com/horizon-sky/agentops/blob/main/src/tools/builtin.py): `src/tools/builtin.py`
- [MCP servers](https://github.com/horizon-sky/agentops/tree/main/services): `services`

### Knowledge retrieval

- [Document processing](https://github.com/horizon-sky/agentops/blob/main/src/rag/ingest.py): `src/rag/ingest.py`
- [Hybrid search](https://github.com/horizon-sky/agentops/blob/main/src/rag/hybrid_search.py): `src/rag/hybrid_search.py`
- [Retrieval stage](https://github.com/horizon-sky/agentops/blob/main/src/agent/nodes/retrieve.py): `src/agent/nodes/retrieve.py`

### Persistence and insight

- [Postgres pgvector](https://github.com/horizon-sky/agentops/blob/main/src/db/models.py): `src/db/models.py`
- [Database sessions](https://github.com/horizon-sky/agentops/blob/main/src/db/session.py): `src/db/session.py`
- [Cache](https://github.com/horizon-sky/agentops/blob/main/src/db/cache.py): `src/db/cache.py`
- [Trace recorder](https://github.com/horizon-sky/agentops/blob/main/src/agent/tracing.py): `src/agent/tracing.py`
- [Evaluation runner](https://github.com/horizon-sky/agentops/blob/main/evals/runner.py): `evals/runner.py`
- [Runtime settings](https://github.com/horizon-sky/agentops/blob/main/src/config.py): `src/config.py`

### Other components

- **Engineer**

## Connections

- Engineer → Workspace UI: submits request
- Workspace UI → Web API proxy: calls API
- Web API proxy → FastAPI app: proxies REST (evidence: `apps/web/app/api/[...path]/route.ts`)
- FastAPI app → Run routes: registers routes (evidence: `apps/api/src/main.py`)
- FastAPI app → Ingest route: registers routes (evidence: `apps/api/src/main.py`)
- FastAPI app → Account routes: registers routes (evidence: `apps/api/src/main.py`)
- FastAPI app → Ticket routes: registers routes (evidence: `apps/api/src/main.py`)
- FastAPI app → Trace routes: registers routes (evidence: `apps/api/src/main.py`)
- FastAPI app → Evaluation route: registers routes (evidence: `apps/api/src/main.py`)
- Run stream UI → Web API proxy: streams runs
- Run routes → Agent state graph: starts or resumes
- Agent state graph → Agent stages: dispatches stages
- Agent stages → Retrieval stage: includes retrieval
- Retrieval stage → Hybrid search: searches evidence (evidence: `src/agent/nodes/retrieve.py`)
- Hybrid search → Postgres pgvector: queries chunks (evidence: `src/rag/hybrid_search.py`)
- Hybrid search → Model access: builds embedder (evidence: `src/rag/hybrid_search.py`)
- Retrieval stage → Event emission: emits retrieval event (evidence: `src/agent/nodes/retrieve.py`)
- Agent stages → Tool registry: invokes tools
- Tool registry → Built-in tools: dispatches tools (evidence: `src/tools/registry.py`)
- Built-in tools → Postgres pgvector: persists approved ticket (evidence: `src/tools/builtin.py`)
- Tool registry → MCP servers: offers MCP tools
- Approval card → Run routes: confirms writes
- Ingest route → Document processing: ingests document (evidence: `apps/api/src/routers/ingest.py`)
- Document processing → Postgres pgvector: stores chunks (evidence: `src/rag/ingest.py`)
- Document processing → Database sessions: opens session (evidence: `src/rag/ingest.py`)
- Document processing → Model access: embeds text (evidence: `src/rag/ingest.py`)
- Document ingest UI → Web API proxy: uploads document
- Ticket routes → Postgres pgvector: manages tickets
- Ticket overview → Web API proxy: manages tickets
- Trace routes → Postgres pgvector: serves spans
- Trace recorder → Postgres pgvector: records spans (evidence: `src/agent/tracing.py`)
- Trace replay UI → Web API proxy: loads trace
- Evaluation dashboard → Web API proxy: loads report
- Evaluation route → Evaluation runner: serves report
- Evaluation runner → Agent state graph: runs agent (evidence: `evals/runner.py`)
- Account routes → Identity services: authenticates users (evidence: `apps/api/src/routers/auth.py`)
- Identity services → Postgres pgvector: checks sessions (evidence: `src/auth.py`)
- FastAPI app → Cache: reports cache health (evidence: `apps/api/src/main.py`)
- Agent stages → Run context: uses run context (evidence: `src/agent/nodes/retrieve.py`)
- Agent stages → Model access: uses model (evidence: `src/agent/nodes/review.py`)
- FastAPI app → Database sessions: initializes database (evidence: `apps/api/src/main.py`)
- Database sessions → Postgres pgvector: connects to (evidence: `src/db/session.py`)
