# aadyasingh2/kavach architecture

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

- Interactive diagram: https://gitdiagram.com/aadyasingh2/kavach
- Repository: https://github.com/aadyasingh2/kavach

## Overview

Kavach accepts a GitHub repository URL, fetches repository files, runs five focused security analyses, synthesizes their findings, and streams progress and the final report to the dashboard. The README documents all five agent roles; source excerpts directly confirm the orchestration and selected agent implementations, while the planner and secrets implementations were not sampled.

Main entry points: [`Kavach/backend/orchestrator.py`](https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/orchestrator.py) (Swarm coordinator), [`Kavach/frontend/src/App.jsx`](https://github.com/aadyasingh2/kavach/blob/main/Kavach/frontend/src/App.jsx) (Dashboard state), [`Kavach/backend/main.py`](https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/main.py) (Analysis API), [`Kavach/frontend/src/components/RepoInput.jsx`](https://github.com/aadyasingh2/kavach/blob/main/Kavach/frontend/src/components/RepoInput.jsx) (Repository input)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_repo_input["Repository input<br/>[RepoInput.jsx]"]
  node_dashboard_app["Dashboard state<br/>[App.jsx]"]
  node_agent_status["Agent status grid<br/>[AgentSwarm.jsx]"]
  node_report_view["Report and telemetry<br/>[Report.jsx]"]
end

subgraph group_service["API and orchestration"]
  node_api["Analysis API<br/>[main.py]"]
  node_orchestrator["Swarm coordinator<br/>[orchestrator.py]"]
end

subgraph group_collection["Repository collection"]
  node_github_fetcher["Repository fetcher<br/>[github_fetcher.py]"]
end

subgraph group_audit["Security audit"]
  node_planner["Attack-surface planner<br/>[planner.py]"]
  node_secrets["Secrets scanner<br/>[secrets.py]"]
  node_dependency["Dependency auditor<br/>[dependency.py]"]
  node_logic["OWASP code auditor<br/>[logic.py]"]
  node_synthesizer["Report synthesizer<br/>[synthesizer.py]"]
end

node_developer(("Developer"))
node_github["GitHub REST API"]
node_models["GitHub Models"]

node_developer -->|"enters repo URL"| node_repo_input
node_repo_input -->|"submits URL"| node_dashboard_app
node_dashboard_app -->|"posts scan request"| node_api
node_api -->|"starts swarm"| node_orchestrator
node_orchestrator -->|"requests files"| node_github_fetcher
node_github_fetcher -->|"fetches tree and contents"| node_github
node_orchestrator -->|"analyzes files"| node_planner
node_orchestrator -->|"analyzes files"| node_secrets
node_orchestrator -->|"analyzes files"| node_dependency
node_orchestrator -->|"analyzes files"| node_logic
node_orchestrator -->|"sends agent findings"| node_synthesizer
node_planner -.->|"requests analysis"| node_models
node_secrets -.->|"requests analysis"| node_models
node_dependency -->|"requests analysis"| node_models
node_logic -->|"requests analysis"| node_models
node_synthesizer -->|"requests synthesis"| node_models
node_orchestrator -->|"sends progress callbacks"| node_api
node_api -->|"streams SSE updates and result"| node_dashboard_app
node_dashboard_app -->|"passes agent statuses"| node_agent_status
node_dashboard_app -->|"passes final result"| node_report_view

click node_repo_input "https://github.com/aadyasingh2/kavach/blob/main/Kavach/frontend/src/components/RepoInput.jsx"
click node_dashboard_app "https://github.com/aadyasingh2/kavach/blob/main/Kavach/frontend/src/App.jsx"
click node_agent_status "https://github.com/aadyasingh2/kavach/blob/main/Kavach/frontend/src/components/AgentSwarm.jsx"
click node_report_view "https://github.com/aadyasingh2/kavach/blob/main/Kavach/frontend/src/components/Report.jsx"
click node_api "https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/main.py"
click node_orchestrator "https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/orchestrator.py"
click node_github_fetcher "https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/github_fetcher.py"
click node_planner "https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/agents/planner.py"
click node_secrets "https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/agents/secrets.py"
click node_dependency "https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/agents/dependency.py"
click node_logic "https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/agents/logic.py"
click node_synthesizer "https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/agents/synthesizer.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_repo_input,node_dashboard_app,node_agent_status,node_report_view toneBlue
class node_api,node_orchestrator toneAmber
class node_github_fetcher,node_github toneMint
class node_planner,node_secrets,node_dependency,node_logic,node_synthesizer toneRose
class node_developer,node_models toneIndigo
```

## Components

### Dashboard

- [Repository input](https://github.com/aadyasingh2/kavach/blob/main/Kavach/frontend/src/components/RepoInput.jsx): `Kavach/frontend/src/components/RepoInput.jsx`
- [Dashboard state](https://github.com/aadyasingh2/kavach/blob/main/Kavach/frontend/src/App.jsx): `Kavach/frontend/src/App.jsx`
- [Agent status grid](https://github.com/aadyasingh2/kavach/blob/main/Kavach/frontend/src/components/AgentSwarm.jsx): `Kavach/frontend/src/components/AgentSwarm.jsx`
- [Report and telemetry](https://github.com/aadyasingh2/kavach/blob/main/Kavach/frontend/src/components/Report.jsx): `Kavach/frontend/src/components/Report.jsx`

### API and orchestration

- [Analysis API](https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/main.py): `Kavach/backend/main.py`
- [Swarm coordinator](https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/orchestrator.py): `Kavach/backend/orchestrator.py`

### Repository collection

- [Repository fetcher](https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/github_fetcher.py): `Kavach/backend/github_fetcher.py`

### Security audit

- [Attack-surface planner](https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/agents/planner.py): `Kavach/backend/agents/planner.py`
- [Secrets scanner](https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/agents/secrets.py): `Kavach/backend/agents/secrets.py`
- [Dependency auditor](https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/agents/dependency.py): `Kavach/backend/agents/dependency.py`
- [OWASP code auditor](https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/agents/logic.py): `Kavach/backend/agents/logic.py`
- [Report synthesizer](https://github.com/aadyasingh2/kavach/blob/main/Kavach/backend/agents/synthesizer.py): `Kavach/backend/agents/synthesizer.py`

### Other components

- **Developer**
- **GitHub REST API**
- **GitHub Models**

## Connections

- Developer → Repository input: enters repo URL
- Repository input → Dashboard state: submits URL
- Dashboard state → Analysis API: posts scan request
- Analysis API → Swarm coordinator: starts swarm
- Swarm coordinator → Repository fetcher: requests files
- Repository fetcher → GitHub REST API: fetches tree and contents
- Swarm coordinator → Attack-surface planner: analyzes files
- Swarm coordinator → Secrets scanner: analyzes files
- Swarm coordinator → Dependency auditor: analyzes files
- Swarm coordinator → OWASP code auditor: analyzes files
- Swarm coordinator → Report synthesizer: sends agent findings
- Attack-surface planner → GitHub Models: requests analysis
- Secrets scanner → GitHub Models: requests analysis
- Dependency auditor → GitHub Models: requests analysis
- OWASP code auditor → GitHub Models: requests analysis
- Report synthesizer → GitHub Models: requests synthesis
- Swarm coordinator → Analysis API: sends progress callbacks
- Analysis API → Dashboard state: streams SSE updates and result
- Dashboard state → Agent status grid: passes agent statuses
- Dashboard state → Report and telemetry: passes final result