# amitdevx/self-healops architecture

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

- Interactive diagram: https://gitdiagram.com/amitdevx/self-healops
- Repository: https://github.com/amitdevx/self-healops

## Overview

SelfHealOps accepts CI failure events, queues incidents, and runs a cyclical remediation workflow: classify and diagnose failures, plan and safety-check actions, execute and validate fixes, then learn from resolved incidents or escalate. Its API also exposes authentication and incident, analysis, action, and validation operations. The graph distinguishes the workflow stages from the agent and integration layers. Relationships for unsampled API routes and storage behavior are included only where the README or source index supports them; optional or undocumented links are omitted.

Main entry points: [`backend/workflows/graph.py`](https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py) (Workflow Orchestrator), [`backend/agents/core.py`](https://github.com/amitdevx/self-healops/blob/main/backend/agents/core.py) (Agent System), [`backend/database/repository.py`](https://github.com/amitdevx/self-healops/blob/main/backend/database/repository.py) (Data Repository), [`backend/api/v1`](https://github.com/amitdevx/self-healops/tree/main/backend/api/v1) (API Routers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and Intake"]
  node_webhook["GitHub Webhook<br/>[webhooks.py]"]
  node_api["API Routers"]
  node_worker["Incident Worker<br/>[worker.py]"]
end

subgraph group_workflow["Incident Workflow"]
  node_workflow["Workflow Orchestrator<br/>[graph.py]"]
  node_learning_match["Pattern Recall<br/>[graph.py]"]
  node_classification["Failure Classification<br/>[graph.py]"]
  node_root_cause["Root Cause Analysis<br/>[graph.py]"]
  node_planning["Remediation Planning<br/>[graph.py]"]
  node_safety["Safety Validation<br/>[graph.py]"]
  node_execution["Action Execution<br/>[graph.py]"]
  node_fix_validation["Fix Validation<br/>[graph.py]"]
  node_learning["Learning Extraction<br/>[graph.py]"]
  node_escalation["Escalation<br/>[graph.py]"]
end

subgraph group_agents["Agents and Integrations"]
  node_agent_system["Agent System<br/>[core.py]"]
  node_nim["NVIDIA NIM<br/>[nim.py]"]
  node_executor["Policy Executor"]
  node_github_service["GitHub Integration<br/>[github.py]"]
  node_learning_service["Learning Store Service<br/>[learning.py]"]
end

subgraph group_persistence["Persistence and Security"]
  node_database[("Relational Database<br/>[session.py]")]
  node_repository["Data Repository<br/>[repository.py]"]
  node_models["Domain Models"]
  node_security["Authentication and Roles<br/>[dependencies.py]"]
end

node_ci(("CI Provider"))

node_ci -->|"sends event"| node_webhook
node_webhook -->|"queues incident"| node_worker
node_worker -->|"invokes workflow"| node_workflow
node_workflow -->|"checks patterns"| node_learning_match
node_workflow -->|"routes incident"| node_classification
node_workflow -->|"routes incident"| node_root_cause
node_workflow -->|"routes incident"| node_planning
node_workflow -->|"routes plan"| node_safety
node_workflow -->|"routes safe plan"| node_execution
node_workflow -->|"routes execution"| node_fix_validation
node_workflow -->|"routes resolved fix"| node_learning
node_workflow -->|"routes unsafe or failed"| node_escalation
node_workflow -->|"delegates stages"| node_agent_system
node_agent_system -->|"requests structured output"| node_nim
node_agent_system -->|"executes actions"| node_executor
node_agent_system -->|"checks CI runs"| node_github_service
node_executor -->|"updates repository"| node_github_service
node_learning_match -->|"looks up pattern"| node_learning_service
node_learning -->|"extracts pattern"| node_agent_system
node_api -->|"uses data access"| node_repository
node_repository -->|"reads and writes"| node_database
node_security -->|"opens session"| node_database
node_api -->|"authenticates requests"| node_security
node_repository -.->|"operates on models"| node_models

click node_webhook "https://github.com/amitdevx/self-healops/blob/main/backend/api/v1/webhooks.py"
click node_api "https://github.com/amitdevx/self-healops/tree/main/backend/api/v1"
click node_worker "https://github.com/amitdevx/self-healops/blob/main/backend/workers/worker.py"
click node_workflow "https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py"
click node_learning_match "https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py"
click node_classification "https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py"
click node_root_cause "https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py"
click node_planning "https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py"
click node_safety "https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py"
click node_execution "https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py"
click node_fix_validation "https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py"
click node_learning "https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py"
click node_escalation "https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py"
click node_agent_system "https://github.com/amitdevx/self-healops/blob/main/backend/agents/core.py"
click node_nim "https://github.com/amitdevx/self-healops/blob/main/backend/services/nim.py"
click node_executor "https://github.com/amitdevx/self-healops/blob/main/backend/services/execution_service.py"
click node_github_service "https://github.com/amitdevx/self-healops/blob/main/backend/services/github.py"
click node_learning_service "https://github.com/amitdevx/self-healops/blob/main/backend/services/learning.py"
click node_database "https://github.com/amitdevx/self-healops/blob/main/backend/database/session.py"
click node_repository "https://github.com/amitdevx/self-healops/blob/main/backend/database/repository.py"
click node_models "https://github.com/amitdevx/self-healops/tree/main/backend/models"
click node_security "https://github.com/amitdevx/self-healops/blob/main/backend/core/dependencies.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_webhook,node_api,node_worker toneBlue
class node_workflow,node_learning_match,node_classification,node_root_cause,node_planning,node_safety,node_execution,node_fix_validation,node_learning,node_escalation toneAmber
class node_agent_system,node_nim,node_executor,node_github_service,node_learning_service toneMint
class node_database,node_repository,node_models,node_security toneRose
class node_ci toneIndigo
```

## Components

### API and Intake

- [GitHub Webhook](https://github.com/amitdevx/self-healops/blob/main/backend/api/v1/webhooks.py): `backend/api/v1/webhooks.py`
- [API Routers](https://github.com/amitdevx/self-healops/tree/main/backend/api/v1): `backend/api/v1`
- [Incident Worker](https://github.com/amitdevx/self-healops/blob/main/backend/workers/worker.py): `backend/workers/worker.py`

### Incident Workflow

- [Workflow Orchestrator](https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py): `backend/workflows/graph.py`
- [Pattern Recall](https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py): `backend/workflows/graph.py`
- [Failure Classification](https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py): `backend/workflows/graph.py`
- [Root Cause Analysis](https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py): `backend/workflows/graph.py`
- [Remediation Planning](https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py): `backend/workflows/graph.py`
- [Safety Validation](https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py): `backend/workflows/graph.py`
- [Action Execution](https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py): `backend/workflows/graph.py`
- [Fix Validation](https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py): `backend/workflows/graph.py`
- [Learning Extraction](https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py): `backend/workflows/graph.py`
- [Escalation](https://github.com/amitdevx/self-healops/blob/main/backend/workflows/graph.py): `backend/workflows/graph.py`

### Agents and Integrations

- [Agent System](https://github.com/amitdevx/self-healops/blob/main/backend/agents/core.py): `backend/agents/core.py`
- [NVIDIA NIM](https://github.com/amitdevx/self-healops/blob/main/backend/services/nim.py): `backend/services/nim.py`
- [Policy Executor](https://github.com/amitdevx/self-healops/blob/main/backend/services/execution_service.py): `backend/services/execution_service.py`
- [GitHub Integration](https://github.com/amitdevx/self-healops/blob/main/backend/services/github.py): `backend/services/github.py`
- [Learning Store Service](https://github.com/amitdevx/self-healops/blob/main/backend/services/learning.py): `backend/services/learning.py`

### Persistence and Security

- [Relational Database](https://github.com/amitdevx/self-healops/blob/main/backend/database/session.py): `backend/database/session.py`
- [Data Repository](https://github.com/amitdevx/self-healops/blob/main/backend/database/repository.py): `backend/database/repository.py`
- [Domain Models](https://github.com/amitdevx/self-healops/tree/main/backend/models): `backend/models`
- [Authentication and Roles](https://github.com/amitdevx/self-healops/blob/main/backend/core/dependencies.py): `backend/core/dependencies.py`

### Other components

- **CI Provider**

## Connections

- CI Provider → GitHub Webhook: sends event (evidence: `backend/api/v1/webhooks.py`)
- GitHub Webhook → Incident Worker: queues incident (evidence: `backend/api/v1/webhooks.py`)
- Incident Worker → Workflow Orchestrator: invokes workflow (evidence: `backend/workers/worker.py`)
- Workflow Orchestrator → Pattern Recall: checks patterns (evidence: `backend/workflows/graph.py`)
- Workflow Orchestrator → Failure Classification: routes incident (evidence: `backend/workflows/graph.py`)
- Workflow Orchestrator → Root Cause Analysis: routes incident (evidence: `backend/workflows/graph.py`)
- Workflow Orchestrator → Remediation Planning: routes incident (evidence: `backend/workflows/graph.py`)
- Workflow Orchestrator → Safety Validation: routes plan (evidence: `backend/workflows/graph.py`)
- Workflow Orchestrator → Action Execution: routes safe plan (evidence: `backend/workflows/graph.py`)
- Workflow Orchestrator → Fix Validation: routes execution (evidence: `backend/workflows/graph.py`)
- Workflow Orchestrator → Learning Extraction: routes resolved fix (evidence: `backend/workflows/graph.py`)
- Workflow Orchestrator → Escalation: routes unsafe or failed (evidence: `backend/workflows/graph.py`)
- Workflow Orchestrator → Agent System: delegates stages (evidence: `backend/workflows/graph.py`)
- Agent System → NVIDIA NIM: requests structured output (evidence: `backend/agents/core.py`)
- Agent System → Policy Executor: executes actions (evidence: `backend/agents/core.py`)
- Agent System → GitHub Integration: checks CI runs (evidence: `backend/agents/core.py`)
- Policy Executor → GitHub Integration: updates repository (evidence: `backend/services/execution_service.py`)
- Pattern Recall → Learning Store Service: looks up pattern (evidence: `backend/workflows/graph.py`)
- Learning Extraction → Agent System: extracts pattern (evidence: `backend/workflows/graph.py`)
- API Routers → Data Repository: uses data access (evidence: `backend/api/v1/incidents.py`)
- Data Repository → Relational Database: reads and writes (evidence: `backend/database/repository.py`)
- Authentication and Roles → Relational Database: opens session (evidence: `backend/core/dependencies.py`)
- API Routers → Authentication and Roles: authenticates requests (evidence: `backend/api/v1/auth.py`)
- Data Repository → Domain Models: operates on models
