# calab/blackbox architecture

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

- Interactive diagram: https://gitdiagram.com/calab/blackbox
- Repository: https://github.com/calab/blackbox

## Overview

Black Box is a desktop deduction game: players fire rays into a grid, infer hidden sphere positions from the ray outcomes, and submit a guess. The main runtime is a single Python file, so the components below are logical responsibilities within that implementation rather than separate modules. The excerpts show scoring, save calls, sound triggers, and rendering behavior, but omit the ray-tracing implementation and persistence details; those internal links are therefore limited to documented behavior. [README, csd-blackbox.py]

Main entry points: [`csd-blackbox.py`](https://github.com/calab/blackbox/blob/main/csd-blackbox.py) (BlackBox window), [`resources`](https://github.com/calab/blackbox/tree/main/resources) (Audio assets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gameplay["Gameplay"]
  node_raygame["Grid and ray rules<br/>[csd-blackbox.py]"]
  node_deduction["Guess and scoring<br/>[csd-blackbox.py]"]
end

subgraph group_interface["Interface"]
  node_blackbox["BlackBox window<br/>[csd-blackbox.py]"]
  node_controls["Input controls<br/>[csd-blackbox.py]"]
end

subgraph group_support["Game support"]
  node_records[("Settings and best times<br/>[csd-blackbox.py]")]
  node_sound["Sound effects<br/>[csd-blackbox.py]"]
  node_assets["Audio assets"]
end

node_player(("Player"))

node_player -->|"plays"| node_blackbox
node_blackbox -->|"runs game"| node_raygame
node_player -->|"marks and fires"| node_controls
node_controls -->|"updates guesses"| node_deduction
node_deduction -->|"saves scores"| node_records
node_deduction -->|"plays effects"| node_sound
node_blackbox -.->|"uses effects"| node_sound
node_sound -.->|"loads clips"| node_assets
node_blackbox -->|"renders status"| node_deduction

click node_blackbox "https://github.com/calab/blackbox/blob/main/csd-blackbox.py"
click node_controls "https://github.com/calab/blackbox/blob/main/csd-blackbox.py"
click node_raygame "https://github.com/calab/blackbox/blob/main/csd-blackbox.py"
click node_deduction "https://github.com/calab/blackbox/blob/main/csd-blackbox.py"
click node_records "https://github.com/calab/blackbox/blob/main/csd-blackbox.py"
click node_sound "https://github.com/calab/blackbox/blob/main/csd-blackbox.py"
click node_assets "https://github.com/calab/blackbox/tree/main/resources"

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_raygame,node_deduction toneBlue
class node_blackbox,node_controls toneAmber
class node_records,node_sound,node_assets toneMint
class node_player toneIndigo
```

## Components

### Gameplay

- [Grid and ray rules](https://github.com/calab/blackbox/blob/main/csd-blackbox.py): `csd-blackbox.py`
- [Guess and scoring](https://github.com/calab/blackbox/blob/main/csd-blackbox.py): `csd-blackbox.py`

### Interface

- [BlackBox window](https://github.com/calab/blackbox/blob/main/csd-blackbox.py): `csd-blackbox.py`
- [Input controls](https://github.com/calab/blackbox/blob/main/csd-blackbox.py): `csd-blackbox.py`

### Game support

- [Settings and best times](https://github.com/calab/blackbox/blob/main/csd-blackbox.py): `csd-blackbox.py`
- [Sound effects](https://github.com/calab/blackbox/blob/main/csd-blackbox.py): `csd-blackbox.py`
- [Audio assets](https://github.com/calab/blackbox/tree/main/resources): `resources`

### Other components

- **Player**

## Connections

- Player → BlackBox window: plays (evidence: `README.md`)
- BlackBox window → Grid and ray rules: runs game (evidence: `README.md`)
- Player → Input controls: marks and fires (evidence: `csd-blackbox.py`)
- Input controls → Guess and scoring: updates guesses (evidence: `csd-blackbox.py`)
- Guess and scoring → Settings and best times: saves scores (evidence: `csd-blackbox.py`)
- Guess and scoring → Sound effects: plays effects (evidence: `csd-blackbox.py`)
- BlackBox window → Sound effects: uses effects (evidence: `csd-blackbox.py`)
- Sound effects → Audio assets: loads clips
- BlackBox window → Guess and scoring: renders status (evidence: `csd-blackbox.py`)
