# thedead91/groundrumble architecture

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

- Interactive diagram: https://gitdiagram.com/thedead91/groundrumble
- Repository: https://github.com/thedead91/groundrumble

## Overview

GroundRumble is a client-side LLM security workbench. Its main workflow turns research sources into editable, ATLAS-mapped tests, then runs the same suite against a model lineup and presents inspectable verdicts and comparisons. The graph also captures the documented matrix, prompt editing, dashboard, sandbox, and credential-vault capabilities. README claims guide several subsystem links; sampled source confirms the app shell, generation orchestration, provider request handling, and judge-merge flow, but not every view’s internal wiring.

Main entry points: [`src/App.jsx`](https://github.com/thedead91/groundrumble/blob/main/src/App.jsx) (App shell), [`src/hooks/useAIGeneration.js`](https://github.com/thedead91/groundrumble/blob/main/src/hooks/useAIGeneration.js) (Generation workflow), [`src/hooks/useAuditRun.js`](https://github.com/thedead91/groundrumble/blob/main/src/hooks/useAuditRun.js) (Audit orchestration), [`src/components/views/DashboardView.jsx`](https://github.com/thedead91/groundrumble/blob/main/src/components/views/DashboardView.jsx) (Security Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Workbench UI"]
  node_app["App shell<br/>[App.jsx]"]
  node_runner["Auditor Runner<br/>[RunnerView.jsx]"]
  node_library["Test Library<br/>[TestsView.jsx]"]
  node_matrix["ATLAS Matrix<br/>[MatrixView.jsx]"]
  node_dashboard["Security Dashboard<br/>[DashboardView.jsx]"]
end

subgraph group_research["Research To Tests"]
  node_generation["Generation workflow<br/>[useAIGeneration.js]"]
  node_ai["AI operations<br/>[index.js]"]
  node_atlas["ATLAS catalog<br/>[atlas-bundled.js]"]
end

subgraph group_evaluation["Audit And Results"]
  node_audit["Audit orchestration<br/>[useAuditRun.js]"]
  node_judging["Verdict judging<br/>[ai-judge.js]"]
  node_history["Audit history<br/>[HistoryContext.jsx]"]
  node_reports["Reports and metrics<br/>[report-builder.js]"]
end

subgraph group_configuration["Models And Prompts"]
  node_providers["Provider settings"]
  node_providerclient["Provider client<br/>[provider-client.js]"]
  node_judgeclient["Judge client<br/>[judge-client.js]"]
  node_prompts["Editable prompts<br/>[PromptsView.jsx]"]
  node_sandbox["Sandbox models<br/>[index.js]"]
  node_settings["App settings"]
end

subgraph group_persistence["Browser Data"]
  node_localstorage[("Browser storage<br/>[storage.js]")]
  node_vault[("Credential vault<br/>[vault.js]")]
end

node_user(("Researcher"))
node_research["Research sources"]
node_localmodels{{"Model endpoints"}}
node_idb[("IndexedDB")]

node_user -->|"uses"| node_app
node_app -->|"shows"| node_runner
node_app -->|"shows"| node_library
node_app -->|"shows"| node_matrix
node_app -->|"shows"| node_dashboard
node_user -->|"provides"| node_research
node_library -->|"starts generation"| node_generation
node_generation -->|"fetches excerpts"| node_research
node_generation -->|"requests analysis"| node_ai
node_generation -->|"maps techniques"| node_atlas
node_generation -->|"offers tests"| node_library
node_matrix -->|"browses"| node_atlas
node_runner -->|"starts audit"| node_audit
node_audit -->|"sends test prompts"| node_providerclient
node_audit -->|"evaluates responses"| node_judging
node_judging -->|"requests judge"| node_judgeclient
node_providerclient -->|"calls endpoint"| node_localmodels
node_judgeclient -->|"calls endpoint"| node_localmodels
node_audit -->|"records results"| node_history
node_dashboard -->|"reads runs"| node_history
node_dashboard -->|"builds reports"| node_reports
node_prompts -->|"edits overrides"| node_settings
node_providers -->|"persists config"| node_localstorage
node_settings -->|"persists settings"| node_localstorage
node_vault -->|"stores credentials"| node_idb
node_providers -->|"uses credentials"| node_vault
node_audit -.->|"uses in sandbox"| node_sandbox

click node_app "https://github.com/thedead91/groundrumble/blob/main/src/App.jsx"
click node_runner "https://github.com/thedead91/groundrumble/blob/main/src/components/views/RunnerView.jsx"
click node_library "https://github.com/thedead91/groundrumble/blob/main/src/components/views/TestsView.jsx"
click node_matrix "https://github.com/thedead91/groundrumble/blob/main/src/components/views/MatrixView.jsx"
click node_dashboard "https://github.com/thedead91/groundrumble/blob/main/src/components/views/DashboardView.jsx"
click node_generation "https://github.com/thedead91/groundrumble/blob/main/src/hooks/useAIGeneration.js"
click node_ai "https://github.com/thedead91/groundrumble/blob/main/src/utils/api/index.js"
click node_atlas "https://github.com/thedead91/groundrumble/blob/main/src/data/atlas-bundled.js"
click node_audit "https://github.com/thedead91/groundrumble/blob/main/src/hooks/useAuditRun.js"
click node_judging "https://github.com/thedead91/groundrumble/blob/main/src/utils/ai-judge.js"
click node_history "https://github.com/thedead91/groundrumble/blob/main/src/context/HistoryContext.jsx"
click node_reports "https://github.com/thedead91/groundrumble/blob/main/src/utils/report-builder.js"
click node_providers "https://github.com/thedead91/groundrumble/blob/main/src/context/ProvidersContext.jsx"
click node_providerclient "https://github.com/thedead91/groundrumble/blob/main/src/utils/api/provider-client.js"
click node_judgeclient "https://github.com/thedead91/groundrumble/blob/main/src/utils/api/judge-client.js"
click node_prompts "https://github.com/thedead91/groundrumble/blob/main/src/components/views/PromptsView.jsx"
click node_sandbox "https://github.com/thedead91/groundrumble/blob/main/src/utils/api/index.js"
click node_settings "https://github.com/thedead91/groundrumble/blob/main/src/context/SettingsContext.jsx"
click node_localstorage "https://github.com/thedead91/groundrumble/blob/main/src/utils/storage.js"
click node_vault "https://github.com/thedead91/groundrumble/blob/main/src/utils/vault.js"

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_app,node_runner,node_library,node_matrix,node_dashboard toneBlue
class node_generation,node_ai,node_atlas,node_idb toneAmber
class node_audit,node_judging,node_history,node_reports toneMint
class node_providers,node_providerclient,node_judgeclient,node_prompts,node_sandbox,node_settings toneRose
class node_localstorage,node_vault,node_user,node_research,node_localmodels toneIndigo
```

## Components

### Workbench UI

- [App shell](https://github.com/thedead91/groundrumble/blob/main/src/App.jsx): `src/App.jsx`
- [Auditor Runner](https://github.com/thedead91/groundrumble/blob/main/src/components/views/RunnerView.jsx): `src/components/views/RunnerView.jsx`
- [Test Library](https://github.com/thedead91/groundrumble/blob/main/src/components/views/TestsView.jsx): `src/components/views/TestsView.jsx`
- [ATLAS Matrix](https://github.com/thedead91/groundrumble/blob/main/src/components/views/MatrixView.jsx): `src/components/views/MatrixView.jsx`
- [Security Dashboard](https://github.com/thedead91/groundrumble/blob/main/src/components/views/DashboardView.jsx): `src/components/views/DashboardView.jsx`

### Research To Tests

- [Generation workflow](https://github.com/thedead91/groundrumble/blob/main/src/hooks/useAIGeneration.js): `src/hooks/useAIGeneration.js`
- [AI operations](https://github.com/thedead91/groundrumble/blob/main/src/utils/api/index.js): `src/utils/api/index.js`
- [ATLAS catalog](https://github.com/thedead91/groundrumble/blob/main/src/data/atlas-bundled.js): `src/data/atlas-bundled.js`

### Audit And Results

- [Audit orchestration](https://github.com/thedead91/groundrumble/blob/main/src/hooks/useAuditRun.js): `src/hooks/useAuditRun.js`
- [Verdict judging](https://github.com/thedead91/groundrumble/blob/main/src/utils/ai-judge.js): `src/utils/ai-judge.js`
- [Audit history](https://github.com/thedead91/groundrumble/blob/main/src/context/HistoryContext.jsx): `src/context/HistoryContext.jsx`
- [Reports and metrics](https://github.com/thedead91/groundrumble/blob/main/src/utils/report-builder.js): `src/utils/report-builder.js`

### Models And Prompts

- [Provider settings](https://github.com/thedead91/groundrumble/blob/main/src/context/ProvidersContext.jsx): `src/context/ProvidersContext.jsx`
- [Provider client](https://github.com/thedead91/groundrumble/blob/main/src/utils/api/provider-client.js): `src/utils/api/provider-client.js`
- [Judge client](https://github.com/thedead91/groundrumble/blob/main/src/utils/api/judge-client.js): `src/utils/api/judge-client.js`
- [Editable prompts](https://github.com/thedead91/groundrumble/blob/main/src/components/views/PromptsView.jsx): `src/components/views/PromptsView.jsx`
- [Sandbox models](https://github.com/thedead91/groundrumble/blob/main/src/utils/api/index.js): `src/utils/api/index.js`
- [App settings](https://github.com/thedead91/groundrumble/blob/main/src/context/SettingsContext.jsx): `src/context/SettingsContext.jsx`

### Browser Data

- [Browser storage](https://github.com/thedead91/groundrumble/blob/main/src/utils/storage.js): `src/utils/storage.js`
- [Credential vault](https://github.com/thedead91/groundrumble/blob/main/src/utils/vault.js): `src/utils/vault.js`

### Other components

- **Researcher**
- **Research sources**
- **Model endpoints**
- **IndexedDB**

## Connections

- Researcher → App shell: uses
- App shell → Auditor Runner: shows
- App shell → Test Library: shows
- App shell → ATLAS Matrix: shows
- App shell → Security Dashboard: shows
- Researcher → Research sources: provides
- Test Library → Generation workflow: starts generation
- Generation workflow → Research sources: fetches excerpts
- Generation workflow → AI operations: requests analysis
- Generation workflow → ATLAS catalog: maps techniques
- Generation workflow → Test Library: offers tests
- ATLAS Matrix → ATLAS catalog: browses
- Auditor Runner → Audit orchestration: starts audit
- Audit orchestration → Provider client: sends test prompts
- Audit orchestration → Verdict judging: evaluates responses
- Verdict judging → Judge client: requests judge
- Provider client → Model endpoints: calls endpoint
- Judge client → Model endpoints: calls endpoint
- Audit orchestration → Audit history: records results
- Security Dashboard → Audit history: reads runs
- Security Dashboard → Reports and metrics: builds reports
- Editable prompts → App settings: edits overrides
- Provider settings → Browser storage: persists config
- App settings → Browser storage: persists settings
- Credential vault → IndexedDB: stores credentials
- Provider settings → Credential vault: uses credentials
- Audit orchestration → Sandbox models: uses in sandbox