# aayushgokhale2005/bugparcel-core architecture

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

- Interactive diagram: https://gitdiagram.com/aayushgokhale2005/bugparcel-core
- Repository: https://github.com/aayushgokhale2005/bugparcel-core

## Overview

BugParcel captures reproducible failure parcels from a dirty Git workspace, then replays and verifies them in isolated worktrees. The CLI is the primary workflow; Python adapters can initiate capture, while the MCP server and local dashboard expose parcel operations to agents and users. Parcel manifests, Git snapshots, environment details, request state, and fixtures preserve the reproduction contract. README documents reduction, optional Docker replay, and enterprise association; their internal wiring is not fully shown in the sampled source, so those links are omitted or marked unverified.

Main entry points: [`apps/cli/src/main.rs`](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/apps/cli/src/main.rs) (BugParcel CLI), [`apps/mcp-server/src/main.rs`](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/apps/mcp-server/src/main.rs) (MCP Server), [`crates/parcel-core/src/lib.rs`](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/parcel-core/src/lib.rs) (Parcel Manifest), [`crates/replay/src/lib.rs`](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/replay/src/lib.rs) (Reproduction Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture"]
  node_git["Git Snapshot<br/>[lib.rs]"]
  node_environment["Environment Capture<br/>[lib.rs]"]
end

subgraph group_core["Parcel Core"]
  node_manifest["Parcel Manifest<br/>[lib.rs]"]
  node_artifacts[("Artifact Store<br/>[lib.rs]")]
  node_replay["Reproduction Runner<br/>[lib.rs]"]
  node_verify["Fix Verification<br/>[lib.rs]"]
  node_reducer["State Reducer<br/>[lib.rs]"]
  node_parcel_store[("Local Parcel Store")]
end

subgraph group_interfaces["User Interfaces"]
  node_cli["BugParcel CLI<br/>[main.rs]"]
  node_mcp["MCP Server<br/>[main.rs]"]
  node_dashboard["Dashboard UI<br/>[main.js]"]
  node_bridge["Local HTTP Bridge<br/>[server.mjs]"]
end

subgraph group_extensions["Adapters &amp; Integrations"]
  node_capture_sdk["Generic Capture SDK<br/>[capture.py]"]
  node_fastapi_sdk["FastAPI Adapter<br/>[middleware.py]"]
end

node_developer(("Developer"))
node_server_app(("Failing Service"))
node_docker["Docker Runtime"]
node_enterprise["Enterprise Service"]

node_developer -->|"captures or operates"| node_cli
node_server_app -.->|"captures failures"| node_capture_sdk
node_server_app -->|"captures exceptions"| node_fastapi_sdk
node_capture_sdk -->|"invokes capture"| node_cli
node_fastapi_sdk -->|"invokes capture"| node_cli
node_cli -->|"captures Git state"| node_git
node_cli -->|"records environment"| node_environment
node_cli -->|"creates parcel"| node_manifest
node_manifest -->|"persists parcel"| node_parcel_store
node_cli -.->|"stores artifacts"| node_artifacts
node_cli -->|"reproduces command"| node_replay
node_replay -->|"runs optionally"| node_docker
node_cli -->|"verifies fix"| node_verify
node_cli -->|"reduces state"| node_reducer
node_developer -->|"requests tools"| node_mcp
node_mcp -->|"captures Git state"| node_git
node_mcp -->|"captures environment"| node_environment
node_mcp -.->|"handles parcels"| node_manifest
node_developer -->|"views parcels"| node_dashboard
node_dashboard -->|"requests actions"| node_bridge
node_bridge -->|"invokes tools"| node_mcp
node_cli -.->|"calls remote API"| node_enterprise

click node_capture_sdk "https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/sdks/python/bugparcel-capture/src/bugparcel_capture/capture.py"
click node_fastapi_sdk "https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/sdks/python/bugparcel-fastapi/src/bugparcel_fastapi/middleware.py"
click node_cli "https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/apps/cli/src/main.rs"
click node_mcp "https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/apps/mcp-server/src/main.rs"
click node_dashboard "https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/apps/dashboard/src/main.js"
click node_bridge "https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/apps/dashboard/server.mjs"
click node_git "https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/git-state/src/lib.rs"
click node_environment "https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/environment/src/lib.rs"
click node_manifest "https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/parcel-core/src/lib.rs"
click node_artifacts "https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/artifact-store/src/lib.rs"
click node_replay "https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/replay/src/lib.rs"
click node_verify "https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/verify/src/lib.rs"
click node_reducer "https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/reducer/src/lib.rs"

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_git,node_environment toneBlue
class node_manifest,node_artifacts,node_replay,node_verify,node_reducer,node_parcel_store toneAmber
class node_cli,node_mcp,node_dashboard,node_bridge toneMint
class node_capture_sdk,node_fastapi_sdk toneRose
class node_developer,node_server_app,node_docker,node_enterprise toneIndigo
```

## Components

### Capture

- [Git Snapshot](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/git-state/src/lib.rs): `crates/git-state/src/lib.rs`
- [Environment Capture](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/environment/src/lib.rs): `crates/environment/src/lib.rs`

### Parcel Core

- [Parcel Manifest](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/parcel-core/src/lib.rs): `crates/parcel-core/src/lib.rs`
- [Artifact Store](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/artifact-store/src/lib.rs): `crates/artifact-store/src/lib.rs`
- [Reproduction Runner](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/replay/src/lib.rs): `crates/replay/src/lib.rs`
- [Fix Verification](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/verify/src/lib.rs): `crates/verify/src/lib.rs`
- [State Reducer](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/crates/reducer/src/lib.rs): `crates/reducer/src/lib.rs`
- **Local Parcel Store**

### User Interfaces

- [BugParcel CLI](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/apps/cli/src/main.rs): `apps/cli/src/main.rs`
- [MCP Server](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/apps/mcp-server/src/main.rs): `apps/mcp-server/src/main.rs`
- [Dashboard UI](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/apps/dashboard/src/main.js): `apps/dashboard/src/main.js`
- [Local HTTP Bridge](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/apps/dashboard/server.mjs): `apps/dashboard/server.mjs`

### Adapters & Integrations

- [Generic Capture SDK](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/sdks/python/bugparcel-capture/src/bugparcel_capture/capture.py): `sdks/python/bugparcel-capture/src/bugparcel_capture/capture.py`
- [FastAPI Adapter](https://github.com/aayushgokhale2005/bugparcel-core/blob/setup/fastapi-sandbox/sdks/python/bugparcel-fastapi/src/bugparcel_fastapi/middleware.py): `sdks/python/bugparcel-fastapi/src/bugparcel_fastapi/middleware.py`

### Other components

- **Developer**
- **Failing Service**
- **Docker Runtime**
- **Enterprise Service**

## Connections

- Developer → BugParcel CLI: captures or operates (evidence: `README.md`)
- Failing Service → Generic Capture SDK: captures failures (evidence: `README.md`)
- Failing Service → FastAPI Adapter: captures exceptions (evidence: `sdks/python/bugparcel-fastapi/src/bugparcel_fastapi/middleware.py`)
- Generic Capture SDK → BugParcel CLI: invokes capture (evidence: `sdks/python/bugparcel-capture/src/bugparcel_capture/capture.py`)
- FastAPI Adapter → BugParcel CLI: invokes capture (evidence: `sdks/python/bugparcel-fastapi/src/bugparcel_fastapi/middleware.py`)
- BugParcel CLI → Git Snapshot: captures Git state (evidence: `README.md`)
- BugParcel CLI → Environment Capture: records environment (evidence: `README.md`)
- BugParcel CLI → Parcel Manifest: creates parcel (evidence: `README.md`)
- Parcel Manifest → Local Parcel Store: persists parcel (evidence: `README.md`)
- BugParcel CLI → Artifact Store: stores artifacts (evidence: `README.md`)
- BugParcel CLI → Reproduction Runner: reproduces command (evidence: `README.md`)
- Reproduction Runner → Docker Runtime: runs optionally (evidence: `crates/replay/src/lib.rs`)
- BugParcel CLI → Fix Verification: verifies fix (evidence: `README.md`)
- BugParcel CLI → State Reducer: reduces state (evidence: `README.md`)
- Developer → MCP Server: requests tools (evidence: `README.md`)
- MCP Server → Git Snapshot: captures Git state (evidence: `apps/mcp-server/src/main.rs`)
- MCP Server → Environment Capture: captures environment (evidence: `apps/mcp-server/src/main.rs`)
- MCP Server → Parcel Manifest: handles parcels
- Developer → Dashboard UI: views parcels (evidence: `apps/dashboard/src/main.js`)
- Dashboard UI → Local HTTP Bridge: requests actions (evidence: `apps/dashboard/src/main.js`)
- Local HTTP Bridge → MCP Server: invokes tools (evidence: `apps/dashboard/server.mjs`)
- BugParcel CLI → Enterprise Service: calls remote API (evidence: `apps/cli/src/main.rs`)
