# shankerrudresh-bit/bugforge architecture

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

- Interactive diagram: https://gitdiagram.com/shankerrudresh-bit/bugforge
- Repository: https://github.com/shankerrudresh-bit/bugforge

## Overview

BugForge turns an engineer’s architecture description into reviewable compound fault scenarios, executes approved scenarios against Docker containers, and presents live run data and resilience reports. The backend path is grounded in excerpts and SOURCE INDEX references; frontend-to-backend interactions are shown only where the README documents the user workflow.

Main entry points: [`backend/app/models`](https://github.com/shankerrudresh-bit/bugforge/tree/main/backend/app/models) (Domain records), [`backend/app/routers/scenarios.py`](https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/routers/scenarios.py) (Scenario routes), [`backend/app/routers/runs.py`](https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/routers/runs.py) (Run routes), [`frontend/src/lib/api.ts`](https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/lib/api.ts) (Typed API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Engineer interface"]
  node_architecture_ui["Architecture editor<br/>[page.tsx]"]
  node_architecture_list["Architecture catalog<br/>[page.tsx]"]
  node_scenario_review["Scenario review<br/>[page.tsx]"]
  node_scenario_detail["Scenario detail<br/>[page.tsx]"]
  node_run_view["Run timeline<br/>[page.tsx]"]
  node_report_view["Report view<br/>[page.tsx]"]
  node_api_client["Typed API client<br/>[api.ts]"]
end

subgraph group_api["API and domain"]
  node_api_entry["FastAPI entry<br/>[main.py]"]
  node_architecture_routes["Architecture routes<br/>[architectures.py]"]
  node_scenario_routes["Scenario routes<br/>[scenarios.py]"]
  node_run_routes["Run routes<br/>[runs.py]"]
  node_schemas["Domain schemas<br/>[schemas.py]"]
  node_llm["Scenario generation<br/>[llm_service.py]"]
end

subgraph group_execution["Experiment execution"]
  node_run_executor["Run orchestrator<br/>[run_executor.py]"]
  node_fault_engine["Fault injection<br/>[fault_engine.py]"]
  node_observability["Log and metrics collection<br/>[observability.py]"]
end

subgraph group_state["Persistence and reporting"]
  node_models[("Domain records")]
  node_db_session["Database sessions<br/>[db.py]"]
  node_report_service["Report builder<br/>[report_service.py]"]
end

node_engineer(("Engineer"))
node_docker["Docker environment"]
node_llm_provider["LLM provider"]

node_engineer -->|"describes system"| node_architecture_ui
node_architecture_ui -->|"submits architecture"| node_api_client
node_api_client -->|"calls API"| node_api_entry
node_api_entry -->|"registers routes"| node_architecture_routes
node_api_entry -->|"registers routes"| node_scenario_routes
node_api_entry -->|"registers routes"| node_run_routes
node_architecture_routes -->|"uses sessions"| node_db_session
node_architecture_routes -->|"reads and writes"| node_models
node_scenario_routes -->|"uses sessions"| node_db_session
node_scenario_routes -->|"reads and writes"| node_models
node_scenario_routes -->|"requests scenarios"| node_llm
node_scenario_routes -->|"validates payloads"| node_schemas
node_llm -->|"generates scenarios"| node_llm_provider
node_engineer -->|"reviews and approves"| node_scenario_review
node_scenario_review -->|"requests scenarios"| node_api_client
node_engineer -->|"launches and monitors"| node_run_view
node_run_view -->|"requests run data"| node_api_client
node_run_routes -->|"uses sessions"| node_db_session
node_run_routes -->|"stores run steps"| node_models
node_run_routes -->|"starts execution"| node_run_executor
node_run_executor -->|"applies and reverts"| node_fault_engine
node_fault_engine -->|"injects container faults"| node_docker
node_run_executor -->|"collects telemetry"| node_observability
node_observability -->|"persists telemetry"| node_models
node_engineer -->|"views report"| node_report_view
node_report_view -->|"requests report"| node_api_client
node_run_routes -->|"builds completed report"| node_report_service
node_report_service -->|"reads run and telemetry"| node_models
node_report_service -.->|"requests optional narrative"| node_llm
node_db_session -->|"backs ORM records"| node_models

click node_architecture_ui "https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/app/architectures/new/page.tsx"
click node_architecture_list "https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/app/architectures/page.tsx"
click node_scenario_review "https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/app/architectures/%5Bid%5D/scenarios/page.tsx"
click node_scenario_detail "https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/app/scenarios/%5Bid%5D/page.tsx"
click node_run_view "https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/app/runs/%5Bid%5D/page.tsx"
click node_report_view "https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/app/runs/%5Bid%5D/report/page.tsx"
click node_api_client "https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/lib/api.ts"
click node_api_entry "https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/main.py"
click node_architecture_routes "https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/routers/architectures.py"
click node_scenario_routes "https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/routers/scenarios.py"
click node_run_routes "https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/routers/runs.py"
click node_schemas "https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/schemas.py"
click node_llm "https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/services/llm_service.py"
click node_run_executor "https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/services/run_executor.py"
click node_fault_engine "https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/services/fault_engine.py"
click node_observability "https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/services/observability.py"
click node_models "https://github.com/shankerrudresh-bit/bugforge/tree/main/backend/app/models"
click node_db_session "https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/db.py"
click node_report_service "https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/services/report_service.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_architecture_ui,node_architecture_list,node_scenario_review,node_scenario_detail,node_run_view,node_report_view,node_api_client toneBlue
class node_api_entry,node_architecture_routes,node_scenario_routes,node_run_routes,node_schemas,node_llm toneAmber
class node_run_executor,node_fault_engine,node_observability toneMint
class node_models,node_db_session,node_report_service toneRose
class node_engineer,node_docker,node_llm_provider toneIndigo
```

## Components

### Engineer interface

- [Architecture editor](https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/app/architectures/new/page.tsx): `frontend/src/app/architectures/new/page.tsx`
- [Architecture catalog](https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/app/architectures/page.tsx): `frontend/src/app/architectures/page.tsx`
- [Scenario review](https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/app/architectures/%5Bid%5D/scenarios/page.tsx): `frontend/src/app/architectures/[id]/scenarios/page.tsx`
- [Scenario detail](https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/app/scenarios/%5Bid%5D/page.tsx): `frontend/src/app/scenarios/[id]/page.tsx`
- [Run timeline](https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/app/runs/%5Bid%5D/page.tsx): `frontend/src/app/runs/[id]/page.tsx`
- [Report view](https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/app/runs/%5Bid%5D/report/page.tsx): `frontend/src/app/runs/[id]/report/page.tsx`
- [Typed API client](https://github.com/shankerrudresh-bit/bugforge/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and domain

- [FastAPI entry](https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/main.py): `backend/app/main.py`
- [Architecture routes](https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/routers/architectures.py): `backend/app/routers/architectures.py`
- [Scenario routes](https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/routers/scenarios.py): `backend/app/routers/scenarios.py`
- [Run routes](https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/routers/runs.py): `backend/app/routers/runs.py`
- [Domain schemas](https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/schemas.py): `backend/app/schemas.py`
- [Scenario generation](https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/services/llm_service.py): `backend/app/services/llm_service.py`

### Experiment execution

- [Run orchestrator](https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/services/run_executor.py): `backend/app/services/run_executor.py`
- [Fault injection](https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/services/fault_engine.py): `backend/app/services/fault_engine.py`
- [Log and metrics collection](https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/services/observability.py): `backend/app/services/observability.py`

### Persistence and reporting

- [Domain records](https://github.com/shankerrudresh-bit/bugforge/tree/main/backend/app/models): `backend/app/models`
- [Database sessions](https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/db.py): `backend/app/db.py`
- [Report builder](https://github.com/shankerrudresh-bit/bugforge/blob/main/backend/app/services/report_service.py): `backend/app/services/report_service.py`

### Other components

- **Engineer**
- **Docker environment**
- **LLM provider**

## Connections

- Engineer → Architecture editor: describes system (evidence: `README.md`)
- Architecture editor → Typed API client: submits architecture (evidence: `README.md`)
- Typed API client → FastAPI entry: calls API (evidence: `README.md`)
- FastAPI entry → Architecture routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI entry → Scenario routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI entry → Run routes: registers routes (evidence: `backend/app/main.py`)
- Architecture routes → Database sessions: uses sessions (evidence: `backend/app/routers/architectures.py`)
- Architecture routes → Domain records: reads and writes (evidence: `backend/app/routers/architectures.py`)
- Scenario routes → Database sessions: uses sessions (evidence: `backend/app/routers/scenarios.py`)
- Scenario routes → Domain records: reads and writes (evidence: `backend/app/routers/scenarios.py`)
- Scenario routes → Scenario generation: requests scenarios (evidence: `backend/app/routers/scenarios.py`)
- Scenario routes → Domain schemas: validates payloads (evidence: `backend/app/routers/scenarios.py`)
- Scenario generation → LLM provider: generates scenarios (evidence: `backend/app/services/llm_service.py`)
- Engineer → Scenario review: reviews and approves (evidence: `README.md`)
- Scenario review → Typed API client: requests scenarios (evidence: `README.md`)
- Engineer → Run timeline: launches and monitors (evidence: `README.md`)
- Run timeline → Typed API client: requests run data (evidence: `README.md`)
- Run routes → Database sessions: uses sessions (evidence: `backend/app/routers/runs.py`)
- Run routes → Domain records: stores run steps (evidence: `backend/app/routers/runs.py`)
- Run routes → Run orchestrator: starts execution (evidence: `backend/app/routers/runs.py`)
- Run orchestrator → Fault injection: applies and reverts (evidence: `backend/app/services/run_executor.py`)
- Fault injection → Docker environment: injects container faults (evidence: `backend/app/services/fault_engine.py`)
- Run orchestrator → Log and metrics collection: collects telemetry (evidence: `backend/app/services/run_executor.py`)
- Log and metrics collection → Domain records: persists telemetry (evidence: `backend/app/services/observability.py`)
- Engineer → Report view: views report (evidence: `README.md`)
- Report view → Typed API client: requests report (evidence: `README.md`)
- Run routes → Report builder: builds completed report (evidence: `backend/app/routers/runs.py`)
- Report builder → Domain records: reads run and telemetry (evidence: `backend/app/services/report_service.py`)
- Report builder → Scenario generation: requests optional narrative (evidence: `backend/app/services/report_service.py`)
- Database sessions → Domain records: backs ORM records (evidence: `backend/app/models/run.py`)
