# ieee-blackbox-ai/blackbox-ai-participant-template architecture

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

- Interactive diagram: https://gitdiagram.com/ieee-blackbox-ai/blackbox-ai-participant-template
- Repository: https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template

## Overview

This is a team template for investigating a black-box system across four rounds, documenting evidence, and submitting findings; the final round focuses on reconstructing a surrogate. The shared Python client lets teams inspect their challenge and quota, query the system, and export accumulated data. Edges reflect README workflow statements and calls visible in `src/blackbox.py`; round-specific internals are represented only by their documented layout.

Main entry points: [`src/blackbox.py`](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/src/blackbox.py) (Blackbox client), [`round-1/README.md`](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-1/README.md) (Observe), [`round-2/README.md`](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-2/README.md) (Investigate), [`round-3/README.md`](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-3/README.md) (Break)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rounds["Investigation rounds"]
  node_observe["Observe<br/>[README.md]"]
  node_investigate["Investigate<br/>[README.md]"]
  node_break["Break<br/>[README.md]"]
  node_reconstruct["Reconstruct<br/>[README.md]"]
  node_final_stage["Final Unknown<br/>[README.md]"]
end

subgraph group_artifacts["Team artifacts"]
  node_findings["Findings<br/>[findings.json]"]
  node_reports["Round reports<br/>[report.md]"]
  node_experiments["Experiments and plots"]
  node_issues["Investigation issues<br/>[ISSUE_TEMPLATE]"]
  node_pull_request["Round submission"]
end

subgraph group_client["API client"]
  node_client["Blackbox client<br/>[blackbox.py]"]
  node_challenge["Challenge spec<br/>[blackbox.py]"]
  node_query["Query system<br/>[blackbox.py]"]
  node_quota_export["Quota and export<br/>[blackbox.py]"]
  node_leaderboard["Leaderboard<br/>[blackbox.py]"]
end

node_team(("Team"))
node_api["Competition API"]

node_team -->|"starts with"| node_observe
node_observe -->|"continues to"| node_investigate
node_investigate -->|"continues to"| node_break
node_break -->|"continues to"| node_reconstruct
node_team -->|"submits final"| node_final_stage
node_team -->|"records claims"| node_findings
node_team -->|"explains evidence"| node_reports
node_team -->|"runs and plots"| node_experiments
node_team -->|"opens investigation"| node_issues
node_team -->|"submits round"| node_pull_request
node_team -->|"uses"| node_client
node_client -->|"requests"| node_challenge
node_client -->|"sends inputs"| node_query
node_client -->|"requests"| node_quota_export
node_client -->|"requests"| node_leaderboard
node_challenge -->|"calls"| node_api
node_query -->|"calls"| node_api
node_quota_export -->|"calls"| node_api
node_leaderboard -->|"calls"| node_api
node_reconstruct -->|"uses prior queries"| node_quota_export

click node_observe "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-1/README.md"
click node_investigate "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-2/README.md"
click node_break "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-3/README.md"
click node_reconstruct "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-4/README.md"
click node_final_stage "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/final/README.md"
click node_findings "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-1/findings.json"
click node_reports "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-1/report.md"
click node_experiments "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/tree/main/round-1/experiments"
click node_issues "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/tree/main/.github/ISSUE_TEMPLATE"
click node_pull_request "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/.github/PULL_REQUEST_TEMPLATE.md"
click node_client "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/src/blackbox.py"
click node_challenge "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/src/blackbox.py"
click node_query "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/src/blackbox.py"
click node_quota_export "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/src/blackbox.py"
click node_leaderboard "https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/src/blackbox.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_observe,node_investigate,node_break,node_reconstruct,node_final_stage toneBlue
class node_findings,node_reports,node_experiments,node_issues,node_pull_request toneAmber
class node_client,node_challenge,node_query,node_quota_export,node_leaderboard,node_api toneMint
class node_team toneIndigo
```

## Components

### Investigation rounds

- [Observe](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-1/README.md): `round-1/README.md`
- [Investigate](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-2/README.md): `round-2/README.md`
- [Break](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-3/README.md): `round-3/README.md`
- [Reconstruct](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-4/README.md): `round-4/README.md`
- [Final Unknown](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/final/README.md): `final/README.md`

### Team artifacts

- [Findings](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-1/findings.json): `round-1/findings.json`
- [Round reports](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/round-1/report.md): `round-1/report.md`
- [Experiments and plots](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/tree/main/round-1/experiments): `round-1/experiments`
- [Investigation issues](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/tree/main/.github/ISSUE_TEMPLATE): `.github/ISSUE_TEMPLATE`
- [Round submission](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/.github/PULL_REQUEST_TEMPLATE.md): `.github/PULL_REQUEST_TEMPLATE.md`

### API client

- [Blackbox client](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/src/blackbox.py): `src/blackbox.py`
- [Challenge spec](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/src/blackbox.py): `src/blackbox.py`
- [Query system](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/src/blackbox.py): `src/blackbox.py`
- [Quota and export](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/src/blackbox.py): `src/blackbox.py`
- [Leaderboard](https://github.com/ieee-blackbox-ai/blackbox-ai-participant-template/blob/main/src/blackbox.py): `src/blackbox.py`

### Other components

- **Team**
- **Competition API**

## Connections

- Team → Observe: starts with (evidence: `README.md`)
- Observe → Investigate: continues to (evidence: `README.md`)
- Investigate → Break: continues to (evidence: `README.md`)
- Break → Reconstruct: continues to (evidence: `README.md`)
- Team → Final Unknown: submits final (evidence: `README.md`)
- Team → Findings: records claims (evidence: `README.md`)
- Team → Round reports: explains evidence (evidence: `README.md`)
- Team → Experiments and plots: runs and plots (evidence: `README.md`)
- Team → Investigation issues: opens investigation (evidence: `README.md`)
- Team → Round submission: submits round (evidence: `README.md`)
- Team → Blackbox client: uses (evidence: `README.md`)
- Blackbox client → Challenge spec: requests (evidence: `src/blackbox.py`)
- Blackbox client → Query system: sends inputs (evidence: `src/blackbox.py`)
- Blackbox client → Quota and export: requests (evidence: `src/blackbox.py`)
- Blackbox client → Leaderboard: requests (evidence: `src/blackbox.py`)
- Challenge spec → Competition API: calls (evidence: `src/blackbox.py`)
- Query system → Competition API: calls (evidence: `src/blackbox.py`)
- Quota and export → Competition API: calls (evidence: `src/blackbox.py`)
- Leaderboard → Competition API: calls (evidence: `src/blackbox.py`)
- Reconstruct → Quota and export: uses prior queries (evidence: `README.md`)
