# theredbluepill/arc-interactive architecture

> Architecture diagram of the GitHub repository theredbluepill/arc-interactive, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theredbluepill/arc-interactive
- Repository: https://github.com/theredbluepill/arc-interactive

## Overview

ARC-Interactive is a collection of 249 community-built ARC-AGI-3 interactive game environments. The main workflow is to choose a game and run it locally, online, or in competition mode; humans and agents use the shared action interface, and the game returns interactive results. The repository also provides tutorial games and a mechanical per-level solvability checker. The README documents the runner modes and checker, but the runner implementation is not among the supplied excerpts, so those links rely on README evidence; game modules are represented as a collection rather than an exhaustive catalog.

Main entry points: [`environment_files`](https://github.com/theredbluepill/arc-interactive/tree/main/environment_files) (Local Games), [`run_game.py`](https://github.com/theredbluepill/arc-interactive/blob/main/run_game.py) (Game Runner), [`devtools/verify_level_solvability.py`](https://github.com/theredbluepill/arc-interactive/blob/main/devtools/verify_level_solvability.py) (Level Solvability), [`environment_files/ez01/63be02fb/ez01.py`](https://github.com/theredbluepill/arc-interactive/blob/main/environment_files/ez01/63be02fb/ez01.py) (Tutorial Games)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Play and Runtime"]
  node_runner["Game Runner<br/>[run_game.py]"]
  node_local[("Local Games")]
  node_arc["ARC Toolkit"]
end

subgraph group_games["Game Environments"]
  node_tutorial["Tutorial Games<br/>[ez01.py]"]
  node_puzzle["Puzzle Games"]
  node_strategy["Strategy Games"]
  node_action["Action Games"]
  node_memory["Memory Games<br/>[mm01.py]"]
  node_flood["Flood Fill<br/>[ff02.py]"]
  node_shape["Shape Rotation<br/>[pt01.py]"]
  node_sequence["Sequence Game<br/>[sq03.py]"]
  node_largegames["Large Game Modules"]
end

subgraph group_analysis["Solvability"]
  node_solvability["Level Solvability"]
  node_bfs["BFS Engine<br/>[engine_bfs.py]"]
end

node_human(("Human Player"))
node_agent(("Agent"))

node_human -->|"plays via"| node_runner
node_agent -->|"acts via"| node_runner
node_runner -->|"runs locally"| node_local
node_runner -.->|"runs online"| node_arc
node_local -.->|"includes"| node_tutorial
node_local -.->|"includes"| node_puzzle
node_local -.->|"includes"| node_strategy
node_local -.->|"includes"| node_action
node_local -.->|"includes"| node_memory
node_local -.->|"includes"| node_flood
node_local -.->|"includes"| node_shape
node_local -.->|"includes"| node_sequence
node_local -.->|"includes"| node_largegames
node_solvability -.->|"uses"| node_bfs
node_local -->|"checks levels"| node_solvability

click node_runner "https://github.com/theredbluepill/arc-interactive/blob/main/run_game.py"
click node_local "https://github.com/theredbluepill/arc-interactive/tree/main/environment_files"
click node_tutorial "https://github.com/theredbluepill/arc-interactive/blob/main/environment_files/ez01/63be02fb/ez01.py"
click node_puzzle "https://github.com/theredbluepill/arc-interactive/tree/main/environment_files"
click node_strategy "https://github.com/theredbluepill/arc-interactive/tree/main/environment_files"
click node_action "https://github.com/theredbluepill/arc-interactive/tree/main/environment_files"
click node_memory "https://github.com/theredbluepill/arc-interactive/blob/main/environment_files/mm01/63be02fb/mm01.py"
click node_flood "https://github.com/theredbluepill/arc-interactive/blob/main/environment_files/ff02/63be02fb/ff02.py"
click node_shape "https://github.com/theredbluepill/arc-interactive/blob/main/environment_files/pt01/63be02fb/pt01.py"
click node_sequence "https://github.com/theredbluepill/arc-interactive/blob/main/environment_files/sq03/63be02fb/sq03.py"
click node_largegames "https://github.com/theredbluepill/arc-interactive/tree/main/environment_files"
click node_solvability "https://github.com/theredbluepill/arc-interactive/blob/main/devtools/verify_level_solvability.py"
click node_bfs "https://github.com/theredbluepill/arc-interactive/blob/main/devtools/solvers/engine_bfs.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_runner,node_local,node_arc toneBlue
class node_tutorial,node_puzzle,node_strategy,node_action,node_memory,node_flood,node_shape,node_sequence,node_largegames toneAmber
class node_solvability,node_bfs toneMint
class node_human,node_agent toneIndigo
```

## Components

### Play and Runtime

- [Game Runner](https://github.com/theredbluepill/arc-interactive/blob/main/run_game.py): `run_game.py`
- [Local Games](https://github.com/theredbluepill/arc-interactive/tree/main/environment_files): `environment_files`
- **ARC Toolkit**

### Game Environments

- [Tutorial Games](https://github.com/theredbluepill/arc-interactive/blob/main/environment_files/ez01/63be02fb/ez01.py): `environment_files/ez01/63be02fb/ez01.py`
- [Puzzle Games](https://github.com/theredbluepill/arc-interactive/tree/main/environment_files): `environment_files`
- [Strategy Games](https://github.com/theredbluepill/arc-interactive/tree/main/environment_files): `environment_files`
- [Action Games](https://github.com/theredbluepill/arc-interactive/tree/main/environment_files): `environment_files`
- [Memory Games](https://github.com/theredbluepill/arc-interactive/blob/main/environment_files/mm01/63be02fb/mm01.py): `environment_files/mm01/63be02fb/mm01.py`
- [Flood Fill](https://github.com/theredbluepill/arc-interactive/blob/main/environment_files/ff02/63be02fb/ff02.py): `environment_files/ff02/63be02fb/ff02.py`
- [Shape Rotation](https://github.com/theredbluepill/arc-interactive/blob/main/environment_files/pt01/63be02fb/pt01.py): `environment_files/pt01/63be02fb/pt01.py`
- [Sequence Game](https://github.com/theredbluepill/arc-interactive/blob/main/environment_files/sq03/63be02fb/sq03.py): `environment_files/sq03/63be02fb/sq03.py`
- [Large Game Modules](https://github.com/theredbluepill/arc-interactive/tree/main/environment_files): `environment_files`

### Solvability

- [Level Solvability](https://github.com/theredbluepill/arc-interactive/blob/main/devtools/verify_level_solvability.py): `devtools/verify_level_solvability.py`
- [BFS Engine](https://github.com/theredbluepill/arc-interactive/blob/main/devtools/solvers/engine_bfs.py): `devtools/solvers/engine_bfs.py`

### Other components

- **Human Player**
- **Agent**

## Connections

- Human Player → Game Runner: plays via (evidence: `README.md`)
- Agent → Game Runner: acts via (evidence: `README.md`)
- Game Runner → Local Games: runs locally (evidence: `README.md`)
- Game Runner → ARC Toolkit: runs online (evidence: `README.md`)
- Local Games → Tutorial Games: includes
- Local Games → Puzzle Games: includes
- Local Games → Strategy Games: includes
- Local Games → Action Games: includes
- Local Games → Memory Games: includes
- Local Games → Flood Fill: includes
- Local Games → Shape Rotation: includes
- Local Games → Sequence Game: includes
- Local Games → Large Game Modules: includes
- Level Solvability → BFS Engine: uses
- Local Games → Level Solvability: checks levels (evidence: `README.md`)
