# anthonyjclarke/shadow-skimmer architecture

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

- Interactive diagram: https://gitdiagram.com/anthonyjclarke/shadow-skimmer
- Repository: https://github.com/anthonyjclarke/shadow-skimmer

## Overview

This repository is a commented, reassemblable disassembly of the ZX Spectrum game Shadow Skimmer, accompanied by catalogs and a behavior specification. The main reader workflow is to use the annotated listing and supporting pages to understand the game’s behavior, graphics, screens, and sound. The README documents simulator-based rendering and exact snapshot reconstruction; sampled source confirms the screen-map renderer and snapshot/tune utilities. Most listing and catalog implementation files were not sampled, so those documented capabilities are shown without guessing their internal call structure.

Main entry points: [`src/screens.py`](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/screens.py) (Hull-map renderer), [`tools/tune_player.py`](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/tools/tune_player.py) (Tune decryptor), [`src/shadskim.ctl`](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/shadskim.ctl) (Annotated listing), [`src/graphics.ref`](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/graphics.ref) (Graphics catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reference["Disassembly reference"]
  node_listing["Annotated listing<br/>[shadskim.ctl]"]
  node_listing_refs["Listing annotations<br/>[shadskim.ref]"]
  node_tune_listing["Tune listing<br/>[tune.ctl]"]
  node_glossary["Glossary<br/>[glossary.ref]"]
end

subgraph group_catalogs["Game catalogs"]
  node_graphics["Graphics catalog<br/>[graphics.ref]"]
  node_screens_catalog["Screens catalog<br/>[screens.ref]"]
  node_screen_writer["Hull-map renderer<br/>[screens.py]"]
  node_sound["Sound catalog<br/>[sound.ref]"]
  node_workspace["Workspace page<br/>[workspace.ref]"]
end

subgraph group_behavior["Behavior reference"]
  node_behavior_spec["Behavior specification<br/>[index.md]"]
end

subgraph group_utilities["Snapshot utilities"]
  node_snapshot_codec["Snapshot codec<br/>[z80snap.py]"]
  node_tune_decoder["Tune decryptor<br/>[tune_player.py]"]
end

node_reader(("Engineer / reader"))
node_snapshot["Game snapshot"]
node_simulator["SkoolKit simulator"]

node_reader -->|"consults"| node_listing
node_reader -->|"consults"| node_graphics
node_reader -->|"consults"| node_screens_catalog
node_reader -->|"consults"| node_sound
node_reader -->|"consults"| node_workspace
node_reader -->|"consults"| node_glossary
node_reader -->|"consults"| node_behavior_spec
node_listing -.->|"annotated by"| node_listing_refs
node_screen_writer -->|"renders through"| node_simulator
node_screen_writer -->|"tiles renders for"| node_screens_catalog
node_snapshot_codec -->|"rebuilds"| node_snapshot
node_tune_decoder -->|"unpacks with"| node_snapshot_codec
node_tune_decoder -->|"produces bytes for"| node_tune_listing
node_snapshot -.->|"runs in"| node_simulator
node_graphics -->|"renders through"| node_simulator
node_sound -->|"renders through"| node_simulator

click node_listing "https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/shadskim.ctl"
click node_listing_refs "https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/shadskim.ref"
click node_tune_listing "https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/tune.ctl"
click node_graphics "https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/graphics.ref"
click node_screens_catalog "https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/screens.ref"
click node_screen_writer "https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/screens.py"
click node_sound "https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/sound.ref"
click node_workspace "https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/workspace.ref"
click node_glossary "https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/glossary.ref"
click node_behavior_spec "https://github.com/anthonyjclarke/shadow-skimmer/blob/main/spec/index.md"
click node_snapshot_codec "https://github.com/anthonyjclarke/shadow-skimmer/blob/main/tools/z80snap.py"
click node_tune_decoder "https://github.com/anthonyjclarke/shadow-skimmer/blob/main/tools/tune_player.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_listing,node_listing_refs,node_tune_listing,node_glossary toneBlue
class node_graphics,node_screens_catalog,node_screen_writer,node_sound,node_workspace toneAmber
class node_behavior_spec toneMint
class node_snapshot_codec,node_tune_decoder toneRose
class node_reader,node_snapshot,node_simulator toneIndigo
```

## Components

### Disassembly reference

- [Annotated listing](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/shadskim.ctl): `src/shadskim.ctl`
- [Listing annotations](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/shadskim.ref): `src/shadskim.ref`
- [Tune listing](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/tune.ctl): `src/tune.ctl`
- [Glossary](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/glossary.ref): `src/glossary.ref`

### Game catalogs

- [Graphics catalog](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/graphics.ref): `src/graphics.ref`
- [Screens catalog](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/screens.ref): `src/screens.ref`
- [Hull-map renderer](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/screens.py): `src/screens.py`
- [Sound catalog](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/sound.ref): `src/sound.ref`
- [Workspace page](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/src/workspace.ref): `src/workspace.ref`

### Behavior reference

- [Behavior specification](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/spec/index.md): `spec/index.md`

### Snapshot utilities

- [Snapshot codec](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/tools/z80snap.py): `tools/z80snap.py`
- [Tune decryptor](https://github.com/anthonyjclarke/shadow-skimmer/blob/main/tools/tune_player.py): `tools/tune_player.py`

### Other components

- **Engineer / reader**
- **Game snapshot**
- **SkoolKit simulator**

## Connections

- Engineer / reader → Annotated listing: consults (evidence: `README.md`)
- Engineer / reader → Graphics catalog: consults (evidence: `README.md`)
- Engineer / reader → Screens catalog: consults (evidence: `README.md`)
- Engineer / reader → Sound catalog: consults (evidence: `README.md`)
- Engineer / reader → Workspace page: consults (evidence: `README.md`)
- Engineer / reader → Glossary: consults (evidence: `README.md`)
- Engineer / reader → Behavior specification: consults (evidence: `README.md`)
- Annotated listing → Listing annotations: annotated by
- Hull-map renderer → SkoolKit simulator: renders through (evidence: `src/screens.py`)
- Hull-map renderer → Screens catalog: tiles renders for (evidence: `src/screens.py`)
- Snapshot codec → Game snapshot: rebuilds (evidence: `tools/z80snap.py`)
- Tune decryptor → Snapshot codec: unpacks with (evidence: `tools/tune_player.py`)
- Tune decryptor → Tune listing: produces bytes for (evidence: `tools/tune_player.py`)
- Game snapshot → SkoolKit simulator: runs in
- Graphics catalog → SkoolKit simulator: renders through (evidence: `README.md`)
- Sound catalog → SkoolKit simulator: renders through (evidence: `README.md`)
