# harmansaini29/project-umbrella architecture

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

- Interactive diagram: https://gitdiagram.com/harmansaini29/project-umbrella
- Repository: https://github.com/harmansaini29/project-umbrella

## Overview

UMBRELLA is a risk-aware control plane for diagnosing backend incidents, planning and governing remediations, executing them with verification, and learning from outcomes. Operators or connected services submit incidents through the dashboard; the council runs diagnosis, topology analysis, planning, safety approval, and execution. Hybrid RAG supplies grounded evidence, while Agent 6 supports adaptation. The README also describes capsule-based disaster recovery. Edges reflect the README and excerpted/indexed source references; unsampled subsystem details and integrations are left unconnected where their wiring is not shown.

Main entry points: [`agents/orchestrator.py`](https://github.com/harmansaini29/project-umbrella/blob/main/agents/orchestrator.py) (Council Orchestrator), [`dashboard/server.py`](https://github.com/harmansaini29/project-umbrella/blob/main/dashboard/server.py) (Control Dashboard), [`rag/hybrid_engine.py`](https://github.com/harmansaini29/project-umbrella/blob/main/rag/hybrid_engine.py) (Hybrid Retrieval), [`agents/agent1_rca/analyzer.py`](https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent1_rca/analyzer.py) (Root Cause Analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Incident Control"]
  node_dashboard["Control Dashboard<br/>[server.py]"]
  node_contracts["Incident Contracts<br/>[schemas.py]"]
  node_council["Council Orchestrator<br/>[orchestrator.py]"]
end

subgraph group_knowledge["Evidence Retrieval"]
  node_rag["Hybrid Retrieval<br/>[hybrid_engine.py]"]
  node_bm25["Keyword Index<br/>[bm25_index.py]"]
  node_vectors["Vector Index<br/>[vector_index.py]"]
end

subgraph group_recovery["Remediation Council"]
  node_rca["Root Cause Analysis<br/>[analyzer.py]"]
  node_topology["Topology Mapper<br/>[visualizer.py]"]
  node_planner["Remediation Planner<br/>[planner.py]"]
  node_guardian["Safety Guardian<br/>[guardian.py]"]
  node_executor["Sandbox Executor<br/>[executor.py]"]
end

subgraph group_evolution["Learning and Recovery"]
  node_evolution["Evolution Learner<br/>[policy_learner.py]"]
  node_outcomes[("Outcome Memory<br/>[outcome_store.py]")]
  node_capsule["System DNA Capsule<br/>[dna_packager.py]"]
  node_genesis["Genesis Restore<br/>[genesis_engine.py]"]
end

subgraph group_runtime["Managed Systems"]
  node_backend["Managed Backend<br/>[server.py]"]
  node_backenddb[("Backend Database<br/>[database.py]")]
  node_sdk["Umbrella SDK<br/>[client.py]"]
end

node_operator(("Operator / Client"))

node_operator -->|"reports incident"| node_dashboard
node_dashboard -->|"triggers council"| node_council
node_dashboard -->|"validates payload"| node_contracts
node_council -->|"runs diagnosis"| node_rca
node_council -->|"maps impact"| node_topology
node_council -->|"plans remediation"| node_planner
node_council -->|"gates agents"| node_guardian
node_council -->|"executes approval"| node_executor
node_rca -.->|"retrieves evidence"| node_rag
node_planner -.->|"retrieves evidence"| node_rag
node_rag -->|"searches lexical"| node_bm25
node_rag -->|"searches dense"| node_vectors
node_executor -.->|"tests remediation"| node_backend
node_council -.->|"updates ranking"| node_evolution
node_evolution -.->|"learns outcomes"| node_outcomes
node_operator -.->|"requests recovery"| node_capsule
node_capsule -->|"restores from"| node_genesis
node_backend -->|"uses database"| node_backenddb
node_sdk -.->|"submits incident"| node_dashboard

click node_dashboard "https://github.com/harmansaini29/project-umbrella/blob/main/dashboard/server.py"
click node_contracts "https://github.com/harmansaini29/project-umbrella/blob/main/agents/schemas.py"
click node_council "https://github.com/harmansaini29/project-umbrella/blob/main/agents/orchestrator.py"
click node_rag "https://github.com/harmansaini29/project-umbrella/blob/main/rag/hybrid_engine.py"
click node_bm25 "https://github.com/harmansaini29/project-umbrella/blob/main/rag/bm25_index.py"
click node_vectors "https://github.com/harmansaini29/project-umbrella/blob/main/rag/vector_index.py"
click node_rca "https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent1_rca/analyzer.py"
click node_topology "https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent2_topology/visualizer.py"
click node_planner "https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent3_planner/planner.py"
click node_guardian "https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent5_guardian/guardian.py"
click node_executor "https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent4_executor/executor.py"
click node_evolution "https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent6_evo/policy_learner.py"
click node_outcomes "https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent6_evo/outcome_store.py"
click node_capsule "https://github.com/harmansaini29/project-umbrella/blob/main/capsule/dna_packager.py"
click node_genesis "https://github.com/harmansaini29/project-umbrella/blob/main/capsule/genesis_engine.py"
click node_backend "https://github.com/harmansaini29/project-umbrella/blob/main/target_system/demo_app/server.py"
click node_backenddb "https://github.com/harmansaini29/project-umbrella/blob/main/target_system/demo_app/database.py"
click node_sdk "https://github.com/harmansaini29/project-umbrella/blob/main/umbrella_sdk/client.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_dashboard,node_contracts,node_council,node_operator toneBlue
class node_rag,node_bm25,node_vectors toneAmber
class node_rca,node_topology,node_planner,node_guardian,node_executor toneMint
class node_evolution,node_outcomes,node_capsule,node_genesis toneRose
class node_backend,node_backenddb,node_sdk toneIndigo
```

## Components

### Incident Control

- [Control Dashboard](https://github.com/harmansaini29/project-umbrella/blob/main/dashboard/server.py): `dashboard/server.py`
- [Incident Contracts](https://github.com/harmansaini29/project-umbrella/blob/main/agents/schemas.py): `agents/schemas.py`
- [Council Orchestrator](https://github.com/harmansaini29/project-umbrella/blob/main/agents/orchestrator.py): `agents/orchestrator.py`

### Evidence Retrieval

- [Hybrid Retrieval](https://github.com/harmansaini29/project-umbrella/blob/main/rag/hybrid_engine.py): `rag/hybrid_engine.py`
- [Keyword Index](https://github.com/harmansaini29/project-umbrella/blob/main/rag/bm25_index.py): `rag/bm25_index.py`
- [Vector Index](https://github.com/harmansaini29/project-umbrella/blob/main/rag/vector_index.py): `rag/vector_index.py`

### Remediation Council

- [Root Cause Analysis](https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent1_rca/analyzer.py): `agents/agent1_rca/analyzer.py`
- [Topology Mapper](https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent2_topology/visualizer.py): `agents/agent2_topology/visualizer.py`
- [Remediation Planner](https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent3_planner/planner.py): `agents/agent3_planner/planner.py`
- [Safety Guardian](https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent5_guardian/guardian.py): `agents/agent5_guardian/guardian.py`
- [Sandbox Executor](https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent4_executor/executor.py): `agents/agent4_executor/executor.py`

### Learning and Recovery

- [Evolution Learner](https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent6_evo/policy_learner.py): `agents/agent6_evo/policy_learner.py`
- [Outcome Memory](https://github.com/harmansaini29/project-umbrella/blob/main/agents/agent6_evo/outcome_store.py): `agents/agent6_evo/outcome_store.py`
- [System DNA Capsule](https://github.com/harmansaini29/project-umbrella/blob/main/capsule/dna_packager.py): `capsule/dna_packager.py`
- [Genesis Restore](https://github.com/harmansaini29/project-umbrella/blob/main/capsule/genesis_engine.py): `capsule/genesis_engine.py`

### Managed Systems

- [Managed Backend](https://github.com/harmansaini29/project-umbrella/blob/main/target_system/demo_app/server.py): `target_system/demo_app/server.py`
- [Backend Database](https://github.com/harmansaini29/project-umbrella/blob/main/target_system/demo_app/database.py): `target_system/demo_app/database.py`
- [Umbrella SDK](https://github.com/harmansaini29/project-umbrella/blob/main/umbrella_sdk/client.py): `umbrella_sdk/client.py`

### Other components

- **Operator / Client**

## Connections

- Operator / Client → Control Dashboard: reports incident (evidence: `dashboard/server.py`)
- Control Dashboard → Council Orchestrator: triggers council (evidence: `dashboard/server.py`)
- Control Dashboard → Incident Contracts: validates payload (evidence: `dashboard/server.py`)
- Council Orchestrator → Root Cause Analysis: runs diagnosis (evidence: `agents/orchestrator.py`)
- Council Orchestrator → Topology Mapper: maps impact (evidence: `agents/orchestrator.py`)
- Council Orchestrator → Remediation Planner: plans remediation (evidence: `agents/orchestrator.py`)
- Council Orchestrator → Safety Guardian: gates agents (evidence: `agents/orchestrator.py`)
- Council Orchestrator → Sandbox Executor: executes approval (evidence: `agents/orchestrator.py`)
- Root Cause Analysis → Hybrid Retrieval: retrieves evidence (evidence: `agents/agent1_rca/analyzer.py`)
- Remediation Planner → Hybrid Retrieval: retrieves evidence (evidence: `agents/agent3_planner/planner.py`)
- Hybrid Retrieval → Keyword Index: searches lexical (evidence: `rag/hybrid_engine.py`)
- Hybrid Retrieval → Vector Index: searches dense (evidence: `rag/hybrid_engine.py`)
- Sandbox Executor → Managed Backend: tests remediation
- Council Orchestrator → Evolution Learner: updates ranking (evidence: `agents/orchestrator.py`)
- Evolution Learner → Outcome Memory: learns outcomes (evidence: `agents/agent6_evo/policy_learner.py`)
- Operator / Client → System DNA Capsule: requests recovery
- System DNA Capsule → Genesis Restore: restores from (evidence: `capsule/genesis_engine.py`)
- Managed Backend → Backend Database: uses database (evidence: `target_system/demo_app/server.py`)
- Umbrella SDK → Control Dashboard: submits incident