# code-philia/hackathon-local-simulation architecture

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

- Interactive diagram: https://gitdiagram.com/code-philia/hackathon-local-simulation
- Repository: https://github.com/code-philia/hackathon-local-simulation

## Overview

This repository packages a local ARC-Bench submission simulator, not the competition website. A user supplies an agent ZIP and requirements, optionally public tests, then `local_submit.py` assembles a workspace and launches the runner in Docker. The runner executes the agent, deploys its generated application, and optionally evaluates it with Playwright; results and logs remain in the workspace. The README documents these stages and optional Meter usage, while sampled source confirms workspace handling, result reading, and runner customization. Production runner internals are not included in the tree, so their internal wiring is not expanded.

Main entry points: [`local_submit.py`](https://github.com/code-philia/hackathon-local-simulation/blob/main/local_submit.py) (Submission CLI), [`public-exercise/bookstack/tests`](https://github.com/code-philia/hackathon-local-simulation/tree/main/public-exercise/bookstack/tests) (Public tests), [`local_runner.py`](https://github.com/code-philia/hackathon-local-simulation/blob/main/local_runner.py) (Local runner adapter), [`public-exercise/bookstack/requirements`](https://github.com/code-philia/hackathon-local-simulation/tree/main/public-exercise/bookstack/requirements) (Requirements)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Submission inputs"]
  node_agent_zip["Agent ZIP"]
  node_requirements["Requirements"]
  node_public_tests["Public tests"]
  node_env_config["Model environment<br/>[env.example]"]
end

subgraph group_orchestration["Local orchestration"]
  node_submit_cli["Submission CLI<br/>[local_submit.py]"]
  node_workspace["Run workspace"]
end

subgraph group_execution["Container execution"]
  node_docker["Docker container"]
  node_local_runner["Local runner adapter<br/>[local_runner.py]"]
  node_production_runner["Production runner"]
  node_agent_runtime["Agent execution"]
  node_generated_app["Generated application"]
  node_deploy["Application deployment"]
end

subgraph group_results["Evaluation and results"]
  node_playwright["Playwright evaluation"]
  node_meter["ARC Bench Meter"]
  node_run_artifacts["Run artifacts"]
  node_result_reader["Result reader<br/>[local_submit.py]"]
end

node_participant(("Participant"))

node_participant -->|"submits inputs"| node_submit_cli
node_agent_zip -->|"provides agent"| node_submit_cli
node_requirements -->|"provides requirements"| node_submit_cli
node_public_tests -.->|"optionally provides tests"| node_submit_cli
node_env_config -.->|"configures models"| node_submit_cli
node_submit_cli -->|"assembles"| node_workspace
node_submit_cli -->|"starts container"| node_docker
node_workspace -->|"mounts inputs"| node_docker
node_docker -->|"invokes"| node_local_runner
node_local_runner -->|"loads and adapts"| node_production_runner
node_production_runner -->|"runs agent"| node_agent_runtime
node_agent_runtime -->|"generates"| node_generated_app
node_production_runner -->|"starts application"| node_deploy
node_deploy -->|"serves"| node_generated_app
node_production_runner -.->|"optionally evaluates"| node_playwright
node_public_tests -.->|"supplies test cases"| node_playwright
node_agent_runtime -.->|"records usage"| node_meter
node_playwright -->|"writes report"| node_run_artifacts
node_production_runner -->|"writes logs and status"| node_run_artifacts
node_workspace -->|"provides run files"| node_result_reader
node_result_reader -->|"reports outcome"| node_participant

click node_requirements "https://github.com/code-philia/hackathon-local-simulation/tree/main/public-exercise/bookstack/requirements"
click node_public_tests "https://github.com/code-philia/hackathon-local-simulation/tree/main/public-exercise/bookstack/tests"
click node_env_config "https://github.com/code-philia/hackathon-local-simulation/blob/main/env.example"
click node_submit_cli "https://github.com/code-philia/hackathon-local-simulation/blob/main/local_submit.py"
click node_local_runner "https://github.com/code-philia/hackathon-local-simulation/blob/main/local_runner.py"
click node_result_reader "https://github.com/code-philia/hackathon-local-simulation/blob/main/local_submit.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_agent_zip,node_requirements,node_public_tests,node_env_config toneBlue
class node_submit_cli,node_workspace toneAmber
class node_docker,node_local_runner,node_production_runner,node_agent_runtime,node_generated_app,node_deploy toneMint
class node_playwright,node_meter,node_run_artifacts,node_result_reader toneRose
class node_participant toneIndigo
```

## Components

### Submission inputs

- **Agent ZIP**
- [Requirements](https://github.com/code-philia/hackathon-local-simulation/tree/main/public-exercise/bookstack/requirements): `public-exercise/bookstack/requirements`
- [Public tests](https://github.com/code-philia/hackathon-local-simulation/tree/main/public-exercise/bookstack/tests): `public-exercise/bookstack/tests`
- [Model environment](https://github.com/code-philia/hackathon-local-simulation/blob/main/env.example): `env.example`

### Local orchestration

- [Submission CLI](https://github.com/code-philia/hackathon-local-simulation/blob/main/local_submit.py): `local_submit.py`
- **Run workspace**

### Container execution

- **Docker container**
- [Local runner adapter](https://github.com/code-philia/hackathon-local-simulation/blob/main/local_runner.py): `local_runner.py`
- **Production runner**
- **Agent execution**
- **Generated application**
- **Application deployment**

### Evaluation and results

- **Playwright evaluation**
- **ARC Bench Meter**
- **Run artifacts**
- [Result reader](https://github.com/code-philia/hackathon-local-simulation/blob/main/local_submit.py): `local_submit.py`

### Other components

- **Participant**

## Connections

- Participant → Submission CLI: submits inputs
- Agent ZIP → Submission CLI: provides agent
- Requirements → Submission CLI: provides requirements
- Public tests → Submission CLI: optionally provides tests
- Model environment → Submission CLI: configures models
- Submission CLI → Run workspace: assembles
- Submission CLI → Docker container: starts container
- Run workspace → Docker container: mounts inputs
- Docker container → Local runner adapter: invokes
- Local runner adapter → Production runner: loads and adapts
- Production runner → Agent execution: runs agent
- Agent execution → Generated application: generates
- Production runner → Application deployment: starts application
- Application deployment → Generated application: serves
- Production runner → Playwright evaluation: optionally evaluates
- Public tests → Playwright evaluation: supplies test cases
- Agent execution → ARC Bench Meter: records usage
- Playwright evaluation → Run artifacts: writes report
- Production runner → Run artifacts: writes logs and status
- Run workspace → Result reader: provides run files
- Result reader → Participant: reports outcome