# percobain/leakguard architecture

> Architecture diagram of the GitHub repository percobain/leakguard, 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/percobain/leakguard
- Repository: https://github.com/percobain/leakguard

## Overview

LeakGuard is an incident-response demo: a simulated secret leak triggers detection, key rotation and redeployment, revocation, history cleanup, verification, and a zero-knowledge proof. The orchestrator owns the workflow and exposes live state and actions to the dashboard. The README documents the external services and lifecycle; source excerpts and the SOURCE INDEX support the main module relationships, though several implementation details were not sampled.

Main entry points: [`services/orchestrator/src/pipeline.ts`](https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/pipeline.ts) (Incident pipeline), [`services/orchestrator/src/server.ts`](https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/server.ts) (HTTP and WebSocket API), [`dashboard/src/App.tsx`](https://github.com/percobain/leakguard/blob/main/dashboard/src/App.tsx) (Dashboard application), [`services/orchestrator/src/zk.ts`](https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/zk.ts) (Proof generation and verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Incident workflow"]
  node_pipeline["Incident pipeline<br/>[pipeline.ts]"]
  node_state["Incident state<br/>[state.ts]"]
  node_api["HTTP and WebSocket API<br/>[server.ts]"]
  node_config["Runtime configuration<br/>[config.ts]"]
end

subgraph group_integrations["Service integrations"]
  node_git["Git operations<br/>[git.ts]"]
  node_github["GitHub integration<br/>[github.ts]"]
  node_google["Google key API<br/>[google.ts]"]
  node_vault["Vault secrets<br/>[vault.ts]"]
  node_docker["Docker control<br/>[docker.ts]"]
  node_github_service["GitHub Actions and repo"]
  node_google_service["Google API Keys"]
  node_vault_service[("HashiCorp Vault")]
end

subgraph group_proof["Proof system"]
  node_zk["Proof generation and verification<br/>[zk.ts]"]
  node_circuit{{"Clean-repo circuit<br/>[leakguard.circom]"}}
end

subgraph group_dashboard["Live dashboard"]
  node_dashboard_app["Dashboard application<br/>[App.tsx]"]
  node_state_hook["Live state connection<br/>[useLeakGuard.ts]"]
  node_chapters["Incident chapters<br/>[Story.tsx]"]
  node_stage["Stage display<br/>[Stage.tsx]"]
  node_vitals["Incident metrics<br/>[Vitals.tsx]"]
  node_logs["Event log drawer<br/>[LogDrawer.tsx]"]
  node_zk_view["Browser proof check<br/>[ZkVerify.tsx]"]
end

subgraph group_demo["Demo environment"]
  node_demo_app["Production demo app<br/>[server.js]"]
  node_attacker["Attacker bot<br/>[attacker.js]"]
  node_mock_google["Mock Google API<br/>[server.js]"]
end

node_developer(("Developer"))

node_developer -->|"pushes leak"| node_github_service
node_pipeline -->|"updates state"| node_state
node_api -->|"routes actions"| node_pipeline
node_api -->|"serves state"| node_state
node_api -->|"verifies proof"| node_zk
node_pipeline -->|"delegates git work"| node_git
node_pipeline -->|"delegates CI work"| node_github
node_pipeline -->|"delegates key operations"| node_google
node_pipeline -->|"delegates secret operations"| node_vault
node_pipeline -->|"controls redeploy"| node_docker
node_pipeline -->|"requests proof"| node_zk
node_pipeline -->|"uses settings"| node_config
node_git -->|"rewrites and pushes"| node_github_service
node_github -->|"reads Actions runs"| node_github_service
node_google -->|"creates and deletes keys"| node_google_service
node_google_service -.->|"simulated by"| node_mock_google
node_vault -->|"stores key versions"| node_vault_service
node_docker -->|"restarts container"| node_demo_app
node_demo_app -->|"reads key via AppRole"| node_vault_service
node_attacker -->|"scrapes commits"| node_github_service
node_attacker -->|"tests stolen key"| node_google_service
node_zk -->|"proves constraints"| node_circuit
node_dashboard_app -->|"subscribes to state"| node_state_hook
node_state_hook -->|"fetches and subscribes"| node_api
node_api -->|"streams snapshots"| node_state_hook
node_dashboard_app -->|"renders"| node_chapters
node_dashboard_app -->|"renders"| node_stage
node_dashboard_app -->|"renders"| node_vitals
node_dashboard_app -->|"renders"| node_logs
node_stage -->|"renders"| node_zk_view
node_zk_view -->|"requests browser verification"| node_api

click node_pipeline "https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/pipeline.ts"
click node_state "https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/state.ts"
click node_api "https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/server.ts"
click node_config "https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/config.ts"
click node_git "https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/git.ts"
click node_github "https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/github.ts"
click node_google "https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/google.ts"
click node_vault "https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/vault.ts"
click node_docker "https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/docker.ts"
click node_demo_app "https://github.com/percobain/leakguard/blob/main/services/demo-app/server.js"
click node_attacker "https://github.com/percobain/leakguard/blob/main/services/attacker/attacker.js"
click node_mock_google "https://github.com/percobain/leakguard/blob/main/services/mock-google/server.js"
click node_zk "https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/zk.ts"
click node_circuit "https://github.com/percobain/leakguard/blob/main/zk/circuits/leakguard.circom"
click node_dashboard_app "https://github.com/percobain/leakguard/blob/main/dashboard/src/App.tsx"
click node_state_hook "https://github.com/percobain/leakguard/blob/main/dashboard/src/useLeakGuard.ts"
click node_chapters "https://github.com/percobain/leakguard/blob/main/dashboard/src/components/Story.tsx"
click node_stage "https://github.com/percobain/leakguard/blob/main/dashboard/src/components/Stage.tsx"
click node_vitals "https://github.com/percobain/leakguard/blob/main/dashboard/src/components/Vitals.tsx"
click node_logs "https://github.com/percobain/leakguard/blob/main/dashboard/src/components/LogDrawer.tsx"
click node_zk_view "https://github.com/percobain/leakguard/blob/main/dashboard/src/components/ZkVerify.tsx"

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_pipeline,node_state,node_api,node_config toneBlue
class node_git,node_github,node_google,node_vault,node_docker,node_github_service,node_google_service,node_vault_service toneAmber
class node_zk,node_circuit toneMint
class node_dashboard_app,node_state_hook,node_chapters,node_stage,node_vitals,node_logs,node_zk_view toneRose
class node_demo_app,node_attacker,node_mock_google,node_developer toneIndigo
```

## Components

### Incident workflow

- [Incident pipeline](https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/pipeline.ts): `services/orchestrator/src/pipeline.ts`
- [Incident state](https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/state.ts): `services/orchestrator/src/state.ts`
- [HTTP and WebSocket API](https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/server.ts): `services/orchestrator/src/server.ts`
- [Runtime configuration](https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/config.ts): `services/orchestrator/src/config.ts`

### Service integrations

- [Git operations](https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/git.ts): `services/orchestrator/src/git.ts`
- [GitHub integration](https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/github.ts): `services/orchestrator/src/github.ts`
- [Google key API](https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/google.ts): `services/orchestrator/src/google.ts`
- [Vault secrets](https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/vault.ts): `services/orchestrator/src/vault.ts`
- [Docker control](https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/docker.ts): `services/orchestrator/src/docker.ts`
- **GitHub Actions and repo**
- **Google API Keys**
- **HashiCorp Vault**

### Proof system

- [Proof generation and verification](https://github.com/percobain/leakguard/blob/main/services/orchestrator/src/zk.ts): `services/orchestrator/src/zk.ts`
- [Clean-repo circuit](https://github.com/percobain/leakguard/blob/main/zk/circuits/leakguard.circom): `zk/circuits/leakguard.circom`

### Live dashboard

- [Dashboard application](https://github.com/percobain/leakguard/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`
- [Live state connection](https://github.com/percobain/leakguard/blob/main/dashboard/src/useLeakGuard.ts): `dashboard/src/useLeakGuard.ts`
- [Incident chapters](https://github.com/percobain/leakguard/blob/main/dashboard/src/components/Story.tsx): `dashboard/src/components/Story.tsx`
- [Stage display](https://github.com/percobain/leakguard/blob/main/dashboard/src/components/Stage.tsx): `dashboard/src/components/Stage.tsx`
- [Incident metrics](https://github.com/percobain/leakguard/blob/main/dashboard/src/components/Vitals.tsx): `dashboard/src/components/Vitals.tsx`
- [Event log drawer](https://github.com/percobain/leakguard/blob/main/dashboard/src/components/LogDrawer.tsx): `dashboard/src/components/LogDrawer.tsx`
- [Browser proof check](https://github.com/percobain/leakguard/blob/main/dashboard/src/components/ZkVerify.tsx): `dashboard/src/components/ZkVerify.tsx`

### Demo environment

- [Production demo app](https://github.com/percobain/leakguard/blob/main/services/demo-app/server.js): `services/demo-app/server.js`
- [Attacker bot](https://github.com/percobain/leakguard/blob/main/services/attacker/attacker.js): `services/attacker/attacker.js`
- [Mock Google API](https://github.com/percobain/leakguard/blob/main/services/mock-google/server.js): `services/mock-google/server.js`

### Other components

- **Developer**

## Connections

- Developer → GitHub Actions and repo: pushes leak (evidence: `README.md`)
- Incident pipeline → Incident state: updates state (evidence: `services/orchestrator/src/pipeline.ts`)
- HTTP and WebSocket API → Incident pipeline: routes actions (evidence: `services/orchestrator/src/server.ts`)
- HTTP and WebSocket API → Incident state: serves state (evidence: `services/orchestrator/src/server.ts`)
- HTTP and WebSocket API → Proof generation and verification: verifies proof (evidence: `services/orchestrator/src/server.ts`)
- Incident pipeline → Git operations: delegates git work (evidence: `services/orchestrator/src/pipeline.ts`)
- Incident pipeline → GitHub integration: delegates CI work (evidence: `services/orchestrator/src/pipeline.ts`)
- Incident pipeline → Google key API: delegates key operations (evidence: `services/orchestrator/src/pipeline.ts`)
- Incident pipeline → Vault secrets: delegates secret operations (evidence: `services/orchestrator/src/pipeline.ts`)
- Incident pipeline → Docker control: controls redeploy (evidence: `services/orchestrator/src/pipeline.ts`)
- Incident pipeline → Proof generation and verification: requests proof (evidence: `services/orchestrator/src/pipeline.ts`)
- Incident pipeline → Runtime configuration: uses settings (evidence: `services/orchestrator/src/pipeline.ts`)
- Git operations → GitHub Actions and repo: rewrites and pushes (evidence: `README.md`)
- GitHub integration → GitHub Actions and repo: reads Actions runs (evidence: `README.md`)
- Google key API → Google API Keys: creates and deletes keys (evidence: `README.md`)
- Google API Keys → Mock Google API: simulated by (evidence: `README.md`)
- Vault secrets → HashiCorp Vault: stores key versions (evidence: `README.md`)
- Docker control → Production demo app: restarts container (evidence: `README.md`)
- Production demo app → HashiCorp Vault: reads key via AppRole (evidence: `README.md`)
- Attacker bot → GitHub Actions and repo: scrapes commits (evidence: `README.md`)
- Attacker bot → Google API Keys: tests stolen key (evidence: `README.md`)
- Proof generation and verification → Clean-repo circuit: proves constraints (evidence: `services/orchestrator/src/zk.ts`)
- Dashboard application → Live state connection: subscribes to state (evidence: `dashboard/src/App.tsx`)
- Live state connection → HTTP and WebSocket API: fetches and subscribes (evidence: `dashboard/src/useLeakGuard.ts`)
- HTTP and WebSocket API → Live state connection: streams snapshots (evidence: `services/orchestrator/src/server.ts`)
- Dashboard application → Incident chapters: renders (evidence: `dashboard/src/App.tsx`)
- Dashboard application → Stage display: renders (evidence: `dashboard/src/App.tsx`)
- Dashboard application → Incident metrics: renders (evidence: `dashboard/src/App.tsx`)
- Dashboard application → Event log drawer: renders (evidence: `dashboard/src/App.tsx`)
- Stage display → Browser proof check: renders (evidence: `dashboard/src/components/Stage.tsx`)
- Browser proof check → HTTP and WebSocket API: requests browser verification (evidence: `README.md`)
