# pman369/ai-battle-royale-developer-arena architecture

> Architecture diagram of the GitHub repository pman369/ai-battle-royale-developer-arena, 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/pman369/ai-battle-royale-developer-arena
- Repository: https://github.com/pman369/ai-battle-royale-developer-arena

## Overview

This Paperclip plugin runs competitive, budget-constrained rounds in which agents submit code patches for isolated evaluation. The match engine tracks spending, grades submissions, and advances or ends rounds; supporting capabilities include governance audits, durable event replay, comparative metrics, dataset export, and a dashboard. The README documents the main workflow and dashboard features. Some worker integrations are named in the source index but their call sites are not shown, so those links are marked unverified rather than asserted.

Main entry points: [`src/worker.ts`](https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/worker.ts) (Match engine), [`src/types.ts`](https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/types.ts) (Arena data model), [`src/eval_metrics.ts`](https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/eval_metrics.ts) (Evaluation metrics), [`src/routine.ts`](https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/routine.ts) (Routine coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Match orchestration"]
  node_routine["Routine coordinator<br/>[routine.ts]"]
  node_engine["Match engine<br/>[worker.ts]"]
end

subgraph group_evaluation["Patch evaluation"]
  node_sandbox["Sandbox manager<br/>[sandbox.ts]"]
  node_governance["Governance auditor<br/>[governance.ts]"]
end

subgraph group_insights["Audit and insights"]
  node_metrics["Evaluation metrics<br/>[eval_metrics.ts]"]
  node_activity["Activity logger<br/>[activity_log.ts]"]
  node_log_files[("JSONL event files")]
  node_exporter["Dataset exporter"]
  node_dataset_file["Evaluation dataset"]
end

subgraph group_plugin["Paperclip plugin"]
  node_cockpit["Arena cockpit<br/>[index.tsx]"]
  node_manifest["Plugin manifest<br/>[manifest.ts]"]
  node_types["Arena data model<br/>[types.ts]"]
end

node_paperclip(("Paperclip host"))
node_agent(("Contestant agents"))
node_test_runner["Target test command"]

node_paperclip -->|"loads plugin"| node_manifest
node_paperclip -->|"schedules ticks"| node_routine
node_routine -->|"advances rounds"| node_engine
node_agent -.->|"reports spend"| node_engine
node_engine -->|"evaluates patches"| node_sandbox
node_sandbox -->|"runs tests"| node_test_runner
node_engine -.->|"audits patches"| node_governance
node_engine -.->|"persists events"| node_activity
node_activity -->|"appends and reads"| node_log_files
node_metrics -->|"supplies scorecard"| node_cockpit
node_engine -.->|"computes metrics"| node_metrics
node_engine -.->|"generates dataset"| node_exporter
node_exporter -->|"exports JSONL"| node_dataset_file
node_paperclip -->|"hosts dashboard"| node_cockpit
node_engine -->|"uses match model"| node_types
node_routine -->|"uses schedule config"| node_types
node_sandbox -->|"shares patch submission"| node_governance
node_metrics -->|"reads events and agents"| node_types
node_activity -->|"stores typed events"| node_types
node_exporter -->|"accepts summary"| node_metrics
node_cockpit -->|"displays match state"| node_types

click node_routine "https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/routine.ts"
click node_engine "https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/worker.ts"
click node_sandbox "https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/sandbox.ts"
click node_governance "https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/governance.ts"
click node_metrics "https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/eval_metrics.ts"
click node_activity "https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/activity_log.ts"
click node_exporter "https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/dataset_exporter.ts"
click node_cockpit "https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/ui/index.tsx"
click node_manifest "https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/manifest.ts"
click node_types "https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/types.ts"

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_routine,node_engine toneBlue
class node_sandbox,node_governance toneAmber
class node_metrics,node_activity,node_log_files,node_exporter,node_dataset_file toneMint
class node_cockpit,node_manifest,node_types toneRose
class node_paperclip,node_agent,node_test_runner toneIndigo
```

## Components

### Match orchestration

- [Routine coordinator](https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/routine.ts): `src/routine.ts`
- [Match engine](https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/worker.ts): `src/worker.ts`

### Patch evaluation

- [Sandbox manager](https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/sandbox.ts): `src/sandbox.ts`
- [Governance auditor](https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/governance.ts): `src/governance.ts`

### Audit and insights

- [Evaluation metrics](https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/eval_metrics.ts): `src/eval_metrics.ts`
- [Activity logger](https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/activity_log.ts): `src/activity_log.ts`
- **JSONL event files**
- [Dataset exporter](https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/dataset_exporter.ts): `src/dataset_exporter.ts`
- **Evaluation dataset**

### Paperclip plugin

- [Arena cockpit](https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/ui/index.tsx): `src/ui/index.tsx`
- [Plugin manifest](https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/manifest.ts): `src/manifest.ts`
- [Arena data model](https://github.com/pman369/ai-battle-royale-developer-arena/blob/main/src/types.ts): `src/types.ts`

### Other components

- **Paperclip host**
- **Contestant agents**
- **Target test command**

## Connections

- Paperclip host → Plugin manifest: loads plugin (evidence: `src/manifest.ts`)
- Paperclip host → Routine coordinator: schedules ticks (evidence: `src/routine.ts`)
- Routine coordinator → Match engine: advances rounds (evidence: `src/routine.ts`)
- Contestant agents → Match engine: reports spend (evidence: `README.md`)
- Match engine → Sandbox manager: evaluates patches (evidence: `src/worker.ts`)
- Sandbox manager → Target test command: runs tests (evidence: `src/sandbox.ts`)
- Match engine → Governance auditor: audits patches (evidence: `src/worker.ts`)
- Match engine → Activity logger: persists events (evidence: `src/worker.ts`)
- Activity logger → JSONL event files: appends and reads (evidence: `src/activity_log.ts`)
- Evaluation metrics → Arena cockpit: supplies scorecard (evidence: `README.md`)
- Match engine → Evaluation metrics: computes metrics (evidence: `src/worker.ts`)
- Match engine → Dataset exporter: generates dataset (evidence: `src/worker.ts`)
- Dataset exporter → Evaluation dataset: exports JSONL (evidence: `README.md`)
- Paperclip host → Arena cockpit: hosts dashboard
- Match engine → Arena data model: uses match model (evidence: `src/worker.ts`)
- Routine coordinator → Arena data model: uses schedule config (evidence: `src/routine.ts`)
- Sandbox manager → Governance auditor: shares patch submission (evidence: `src/governance.ts`)
- Evaluation metrics → Arena data model: reads events and agents (evidence: `src/eval_metrics.ts`)
- Activity logger → Arena data model: stores typed events (evidence: `src/activity_log.ts`)
- Dataset exporter → Evaluation metrics: accepts summary (evidence: `src/dataset_exporter.ts`)
- Arena cockpit → Arena data model: displays match state (evidence: `src/ui/index.tsx`)
