# perftool-incubator/crucible architecture

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

- Interactive diagram: https://gitdiagram.com/perftool-incubator/crucible
- Repository: https://github.com/perftool-incubator/crucible

## Overview

Crucible is a modular performance-testing harness: users define runs, Crucible launches benchmark and tool workloads across supported endpoint types, then converts and stores results for querying and comparison. Its MCP service offers a secured, typed interface for run planning, operations, and job supervision. The README documents the harness workflow and major capabilities; the MCP and logger edges below are grounded in the supplied source excerpts and SOURCE INDEX. Several harness subsystems are represented at their documented directory-level boundary because their implementation was not sampled.

Main entry points: [`mcp/crucible_mcp/server.py`](https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/server.py) (MCP transport), [`bin`](https://github.com/perftool-incubator/crucible/tree/master/bin) (Benchmark engine), [`mcp/crucible_mcp/operations.py`](https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/operations.py) (Typed operations), [`bin/crucible`](https://github.com/perftool-incubator/crucible/blob/master/bin/crucible) (Crucible CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_harness["Run orchestration"]
  node_cli["Crucible CLI"]
  node_runfile["Run definition"]
  node_endpoints["Endpoints"]
end

subgraph group_execution["Workload execution"]
  node_tooling["Tool collection"]
  node_userenv["User environments"]
  node_engine["Benchmark engine"]
  node_benchmarks["Benchmarks<br/>[repos.json]"]
end

subgraph group_results["Results and logging"]
  node_processor["Result processor"]
  node_cdm["Common data model"]
  node_opensearch[("OpenSearch")]
  node_query["Query interface"]
  node_logger["Logger CLI<br/>[_logger.py]"]
  node_logcommands["Log commands<br/>[_log.py]"]
  node_logstore[("Log database<br/>[db.py]")]
  node_logviewer["Log viewer<br/>[viewer.py]"]
end

subgraph group_mcp["MCP service"]
  node_mcpserver["MCP transport<br/>[server.py]"]
  node_policy["Security policy<br/>[policy.py]"]
  node_operations["Typed operations<br/>[operations.py]"]
  node_documentation["Docs resources<br/>[documentation.py]"]
  node_runner["Job supervisor<br/>[runner.py]"]
  node_jobs[("Durable jobs<br/>[jobs.py]")]
  node_models["Job models<br/>[models.py]"]
  node_audit["Audit<br/>[audit.py]"]
end

node_user(("User"))
node_sut(("Systems under test"))
node_mcpclient(("MCP client"))

node_user -->|"invokes"| node_cli
node_cli -->|"accepts"| node_runfile
node_cli -->|"selects"| node_endpoints
node_endpoints -->|"launches"| node_engine
node_endpoints -->|"uses image"| node_userenv
node_engine -->|"executes"| node_benchmarks
node_engine -->|"collects data"| node_tooling
node_engine -->|"tests"| node_sut
node_processor -->|"converts output"| node_cdm
node_cdm -->|"stores results"| node_opensearch
node_user -->|"queries results"| node_query
node_logger -->|"writes logs"| node_logstore
node_logcommands -->|"reads logs"| node_logstore
node_logcommands -->|"delegates viewing"| node_logviewer
node_mcpclient -.->|"sends requests"| node_mcpserver
node_mcpserver -->|"checks credentials"| node_policy
node_mcpserver -->|"dispatches operations"| node_operations
node_mcpserver -->|"dispatches jobs"| node_runner
node_mcpserver -->|"uses job store"| node_jobs
node_mcpserver -->|"uses audit"| node_audit
node_mcpserver -->|"serves resources"| node_documentation
node_runner -->|"persists state"| node_jobs
node_runner -->|"validates plans"| node_operations
node_jobs -->|"builds records"| node_models
node_operations -->|"checks inputs"| node_policy
node_operations -->|"uses catalog"| node_documentation

click node_cli "https://github.com/perftool-incubator/crucible/blob/master/bin/crucible"
click node_endpoints "https://github.com/perftool-incubator/crucible/tree/master/bin"
click node_tooling "https://github.com/perftool-incubator/crucible/tree/master/bin"
click node_userenv "https://github.com/perftool-incubator/crucible/blob/master/bin/userenvs"
click node_engine "https://github.com/perftool-incubator/crucible/tree/master/bin"
click node_benchmarks "https://github.com/perftool-incubator/crucible/blob/master/config/repos.json"
click node_processor "https://github.com/perftool-incubator/crucible/blob/master/bin/result-processor.py"
click node_cdm "https://github.com/perftool-incubator/crucible/blob/master/bin/result-processor.py"
click node_opensearch "https://github.com/perftool-incubator/crucible/blob/master/bin/manage_opensearch.py"
click node_query "https://github.com/perftool-incubator/crucible/tree/master/bin"
click node_logger "https://github.com/perftool-incubator/crucible/blob/master/bin/_logger.py"
click node_logcommands "https://github.com/perftool-incubator/crucible/blob/master/bin/_log.py"
click node_logstore "https://github.com/perftool-incubator/crucible/blob/master/bin/_logger_lib/db.py"
click node_logviewer "https://github.com/perftool-incubator/crucible/blob/master/bin/_logger_lib/viewer.py"
click node_mcpserver "https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/server.py"
click node_policy "https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/policy.py"
click node_operations "https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/operations.py"
click node_documentation "https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/documentation.py"
click node_runner "https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/runner.py"
click node_jobs "https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/jobs.py"
click node_models "https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/models.py"
click node_audit "https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/audit.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_cli,node_runfile,node_endpoints,node_user,node_mcpclient toneBlue
class node_tooling,node_userenv,node_engine,node_benchmarks toneAmber
class node_processor,node_cdm,node_opensearch,node_query,node_logger,node_logcommands,node_logstore,node_logviewer toneMint
class node_mcpserver,node_policy,node_operations,node_documentation,node_runner,node_jobs,node_models,node_audit toneRose
class node_sut toneIndigo
```

## Components

### Run orchestration

- [Crucible CLI](https://github.com/perftool-incubator/crucible/blob/master/bin/crucible): `bin/crucible`
- **Run definition**
- [Endpoints](https://github.com/perftool-incubator/crucible/tree/master/bin): `bin`

### Workload execution

- [Tool collection](https://github.com/perftool-incubator/crucible/tree/master/bin): `bin`
- [User environments](https://github.com/perftool-incubator/crucible/blob/master/bin/userenvs): `bin/userenvs`
- [Benchmark engine](https://github.com/perftool-incubator/crucible/tree/master/bin): `bin`
- [Benchmarks](https://github.com/perftool-incubator/crucible/blob/master/config/repos.json): `config/repos.json`

### Results and logging

- [Result processor](https://github.com/perftool-incubator/crucible/blob/master/bin/result-processor.py): `bin/result-processor.py`
- [Common data model](https://github.com/perftool-incubator/crucible/blob/master/bin/result-processor.py): `bin/result-processor.py`
- [OpenSearch](https://github.com/perftool-incubator/crucible/blob/master/bin/manage_opensearch.py): `bin/manage_opensearch.py`
- [Query interface](https://github.com/perftool-incubator/crucible/tree/master/bin): `bin`
- [Logger CLI](https://github.com/perftool-incubator/crucible/blob/master/bin/_logger.py): `bin/_logger.py`
- [Log commands](https://github.com/perftool-incubator/crucible/blob/master/bin/_log.py): `bin/_log.py`
- [Log database](https://github.com/perftool-incubator/crucible/blob/master/bin/_logger_lib/db.py): `bin/_logger_lib/db.py`
- [Log viewer](https://github.com/perftool-incubator/crucible/blob/master/bin/_logger_lib/viewer.py): `bin/_logger_lib/viewer.py`

### MCP service

- [MCP transport](https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/server.py): `mcp/crucible_mcp/server.py`
- [Security policy](https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/policy.py): `mcp/crucible_mcp/policy.py`
- [Typed operations](https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/operations.py): `mcp/crucible_mcp/operations.py`
- [Docs resources](https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/documentation.py): `mcp/crucible_mcp/documentation.py`
- [Job supervisor](https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/runner.py): `mcp/crucible_mcp/runner.py`
- [Durable jobs](https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/jobs.py): `mcp/crucible_mcp/jobs.py`
- [Job models](https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/models.py): `mcp/crucible_mcp/models.py`
- [Audit](https://github.com/perftool-incubator/crucible/blob/master/mcp/crucible_mcp/audit.py): `mcp/crucible_mcp/audit.py`

### Other components

- **User**
- **Systems under test**
- **MCP client**

## Connections

- User → Crucible CLI: invokes (evidence: `README.md`)
- Crucible CLI → Run definition: accepts (evidence: `README.md`)
- Crucible CLI → Endpoints: selects (evidence: `README.md`)
- Endpoints → Benchmark engine: launches (evidence: `README.md`)
- Endpoints → User environments: uses image (evidence: `README.md`)
- Benchmark engine → Benchmarks: executes (evidence: `README.md`)
- Benchmark engine → Tool collection: collects data (evidence: `README.md`)
- Benchmark engine → Systems under test: tests (evidence: `README.md`)
- Result processor → Common data model: converts output (evidence: `README.md`)
- Common data model → OpenSearch: stores results (evidence: `README.md`)
- User → Query interface: queries results (evidence: `README.md`)
- Logger CLI → Log database: writes logs (evidence: `bin/_logger.py`)
- Log commands → Log database: reads logs (evidence: `bin/_log.py`)
- Log commands → Log viewer: delegates viewing (evidence: `bin/_log.py`)
- MCP client → MCP transport: sends requests
- MCP transport → Security policy: checks credentials (evidence: `mcp/crucible_mcp/server.py`)
- MCP transport → Typed operations: dispatches operations (evidence: `mcp/crucible_mcp/server.py`)
- MCP transport → Job supervisor: dispatches jobs (evidence: `mcp/crucible_mcp/server.py`)
- MCP transport → Durable jobs: uses job store (evidence: `mcp/crucible_mcp/server.py`)
- MCP transport → Audit: uses audit (evidence: `mcp/crucible_mcp/server.py`)
- MCP transport → Docs resources: serves resources (evidence: `mcp/crucible_mcp/server.py`)
- Job supervisor → Durable jobs: persists state (evidence: `mcp/crucible_mcp/runner.py`)
- Job supervisor → Typed operations: validates plans (evidence: `mcp/crucible_mcp/runner.py`)
- Durable jobs → Job models: builds records (evidence: `mcp/crucible_mcp/jobs.py`)
- Typed operations → Security policy: checks inputs (evidence: `mcp/crucible_mcp/operations.py`)
- Typed operations → Docs resources: uses catalog (evidence: `mcp/crucible_mcp/operations.py`)
