# jglasse/zd architecture

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

- Interactive diagram: https://gitdiagram.com/jglasse/zd
- Repository: https://github.com/jglasse/zd

## Overview

Zylon Defenders is an iOS space-combat game inspired by Star Raiders: players configure a run, navigate a galaxy, and defend Zylon stations in real-time ship combat. The main game controller coordinates the SceneKit game loop and galaxy updates; separate modules represent the map, ships, weapons, and controls. The README also describes Kohai’s spoken commentary and a MultiPeer companion controller. Some subsystems are documented but their wiring is not shown in the excerpts, so those links are omitted or marked unverified.

Main entry points: [`zylons/ZylonGameViewController.swift`](https://github.com/jglasse/zd/blob/main/zylons/ZylonGameViewController.swift) (Game Controller), [`zylons/GalaxyMapModel.swift`](https://github.com/jglasse/zd/blob/main/zylons/GalaxyMapModel.swift) (Galaxy State), [`zylons/SectorObject.swift`](https://github.com/jglasse/zd/blob/main/zylons/SectorObject.swift) (Sector Objects), [`zylons/MainMenuViewController.swift`](https://github.com/jglasse/zd/blob/main/zylons/MainMenuViewController.swift) (Main Menu)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_navigation["Menus and Navigation"]
  node_menu["Main Menu"]
  node_prologue["Prologue"]
end

subgraph group_galaxy["Galaxy and Sectors"]
  node_galaxy_model["Galaxy State"]
  node_sector_state["Sector State<br/>[SectorGrid.swift]"]
  node_classic_map["Classic Map<br/>[ClassicMap.swift]"]
  node_galaxy_display["Galaxy Display"]
  node_galaxy_blip["Map Blips<br/>[GalaxyBlip.swift]"]
end

subgraph group_combat["Ship Combat"]
  node_game["Game Controller"]
  node_zylon_ship["Player Ship<br/>[ZylonShip.swift]"]
  node_humon_ship["Humon Ships<br/>[HumonShip.swift]"]
  node_station["Zylon Stations<br/>[ZylonStation.swift]"]
  node_torpedo["Torpedoes<br/>[Torpedo.swift]"]
  node_sector_object["Sector Objects<br/>[SectorObject.swift]"]
end

subgraph group_interface["Controls and Feedback"]
  node_scanner["Scanner<br/>[Scanner.swift]"]
  node_joystick["Joystick<br/>[JoyStickView.swift]"]
  node_hud["HUD<br/>[HUD.swift]"]
  node_kohai["Kohai Copilot<br/>[Kohai.swift]"]
  node_sound["Sound Playback<br/>[SoundEngine.swift]"]
end

subgraph group_connectivity["Companion Control"]
  node_helm["Helm Controller<br/>[MCController.swift]"]
end

node_player(("Player"))
node_remote_player(("Second Device"))

node_player -.->|"opens"| node_menu
node_menu -->|"presents"| node_game
node_player -.->|"steers"| node_joystick
node_game -->|"updates troops"| node_galaxy_model
node_galaxy_model -.->|"stores sectors"| node_sector_state
node_classic_map -->|"renders map"| node_galaxy_model
node_galaxy_display -.->|"reads state"| node_galaxy_model
node_galaxy_display -.->|"uses blips"| node_galaxy_blip
node_game -.->|"coordinates combat"| node_humon_ship
node_game -.->|"coordinates combat"| node_zylon_ship
node_game -.->|"manages stations"| node_station
node_humon_ship -->|"fires"| node_torpedo
node_humon_ship -->|"inherits"| node_sector_object
node_zylon_ship -->|"inherits"| node_sector_object
node_torpedo -->|"inherits"| node_sector_object
node_scanner -.->|"scans"| node_sector_object
node_game -.->|"accepts input"| node_joystick
node_game -.->|"updates display"| node_hud
node_game -.->|"uses copilot"| node_kohai
node_kohai -.->|"plays commentary"| node_sound
node_remote_player -.->|"sends controls"| node_helm
node_helm -.->|"remotely controls"| node_game
node_menu -.->|"offers prologue"| node_prologue

click node_menu "https://github.com/jglasse/zd/blob/main/zylons/MainMenuViewController.swift"
click node_prologue "https://github.com/jglasse/zd/blob/main/zylons/PrologueViewController.swift"
click node_game "https://github.com/jglasse/zd/blob/main/zylons/ZylonGameViewController.swift"
click node_galaxy_model "https://github.com/jglasse/zd/blob/main/zylons/GalaxyMapModel.swift"
click node_sector_state "https://github.com/jglasse/zd/blob/main/zylons/SectorGrid.swift"
click node_classic_map "https://github.com/jglasse/zd/blob/main/zylons/ClassicMap.swift"
click node_galaxy_display "https://github.com/jglasse/zd/blob/main/zylons/GalaxyMapDisplay.swift"
click node_galaxy_blip "https://github.com/jglasse/zd/blob/main/zylons/GalaxyBlip.swift"
click node_zylon_ship "https://github.com/jglasse/zd/blob/main/zylons/ZylonShip.swift"
click node_humon_ship "https://github.com/jglasse/zd/blob/main/zylons/HumonShip.swift"
click node_station "https://github.com/jglasse/zd/blob/main/zylons/ZylonStation.swift"
click node_torpedo "https://github.com/jglasse/zd/blob/main/zylons/Torpedo.swift"
click node_sector_object "https://github.com/jglasse/zd/blob/main/zylons/SectorObject.swift"
click node_scanner "https://github.com/jglasse/zd/blob/main/zylons/Scanner.swift"
click node_joystick "https://github.com/jglasse/zd/blob/main/zylons/JoyStickView.swift"
click node_hud "https://github.com/jglasse/zd/blob/main/zylons/HUD.swift"
click node_kohai "https://github.com/jglasse/zd/blob/main/zylons/Kohai.swift"
click node_sound "https://github.com/jglasse/zd/blob/main/zylons/SoundEngine.swift"
click node_helm "https://github.com/jglasse/zd/blob/main/helm/MCController.swift"

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_menu,node_prologue toneBlue
class node_galaxy_model,node_sector_state,node_classic_map,node_galaxy_display,node_galaxy_blip toneAmber
class node_game,node_zylon_ship,node_humon_ship,node_station,node_torpedo,node_sector_object toneMint
class node_scanner,node_joystick,node_hud,node_kohai,node_sound toneRose
class node_helm,node_player,node_remote_player toneIndigo
```

## Components

### Menus and Navigation

- [Main Menu](https://github.com/jglasse/zd/blob/main/zylons/MainMenuViewController.swift): `zylons/MainMenuViewController.swift`
- [Prologue](https://github.com/jglasse/zd/blob/main/zylons/PrologueViewController.swift): `zylons/PrologueViewController.swift`

### Galaxy and Sectors

- [Galaxy State](https://github.com/jglasse/zd/blob/main/zylons/GalaxyMapModel.swift): `zylons/GalaxyMapModel.swift`
- [Sector State](https://github.com/jglasse/zd/blob/main/zylons/SectorGrid.swift): `zylons/SectorGrid.swift`
- [Classic Map](https://github.com/jglasse/zd/blob/main/zylons/ClassicMap.swift): `zylons/ClassicMap.swift`
- [Galaxy Display](https://github.com/jglasse/zd/blob/main/zylons/GalaxyMapDisplay.swift): `zylons/GalaxyMapDisplay.swift`
- [Map Blips](https://github.com/jglasse/zd/blob/main/zylons/GalaxyBlip.swift): `zylons/GalaxyBlip.swift`

### Ship Combat

- [Game Controller](https://github.com/jglasse/zd/blob/main/zylons/ZylonGameViewController.swift): `zylons/ZylonGameViewController.swift`
- [Player Ship](https://github.com/jglasse/zd/blob/main/zylons/ZylonShip.swift): `zylons/ZylonShip.swift`
- [Humon Ships](https://github.com/jglasse/zd/blob/main/zylons/HumonShip.swift): `zylons/HumonShip.swift`
- [Zylon Stations](https://github.com/jglasse/zd/blob/main/zylons/ZylonStation.swift): `zylons/ZylonStation.swift`
- [Torpedoes](https://github.com/jglasse/zd/blob/main/zylons/Torpedo.swift): `zylons/Torpedo.swift`
- [Sector Objects](https://github.com/jglasse/zd/blob/main/zylons/SectorObject.swift): `zylons/SectorObject.swift`

### Controls and Feedback

- [Scanner](https://github.com/jglasse/zd/blob/main/zylons/Scanner.swift): `zylons/Scanner.swift`
- [Joystick](https://github.com/jglasse/zd/blob/main/zylons/JoyStickView.swift): `zylons/JoyStickView.swift`
- [HUD](https://github.com/jglasse/zd/blob/main/zylons/HUD.swift): `zylons/HUD.swift`
- [Kohai Copilot](https://github.com/jglasse/zd/blob/main/zylons/Kohai.swift): `zylons/Kohai.swift`
- [Sound Playback](https://github.com/jglasse/zd/blob/main/zylons/SoundEngine.swift): `zylons/SoundEngine.swift`

### Companion Control

- [Helm Controller](https://github.com/jglasse/zd/blob/main/helm/MCController.swift): `helm/MCController.swift`

### Other components

- **Player**
- **Second Device**

## Connections

- Player → Main Menu: opens (evidence: `README.md`)
- Main Menu → Game Controller: presents (evidence: `zylons/MainMenuViewController.swift`)
- Player → Joystick: steers (evidence: `README.md`)
- Game Controller → Galaxy State: updates troops (evidence: `zylons/ZylonGameViewController.swift`)
- Galaxy State → Sector State: stores sectors (evidence: `zylons/GalaxyMapModel.swift`)
- Classic Map → Galaxy State: renders map (evidence: `zylons/ClassicMap.swift`)
- Galaxy Display → Galaxy State: reads state (evidence: `zylons/GalaxyMapDisplay.swift`)
- Galaxy Display → Map Blips: uses blips (evidence: `zylons/GalaxyMapDisplay.swift`)
- Game Controller → Humon Ships: coordinates combat (evidence: `zylons/ZylonGameViewController.swift`)
- Game Controller → Player Ship: coordinates combat (evidence: `zylons/ZylonGameViewController.swift`)
- Game Controller → Zylon Stations: manages stations (evidence: `zylons/ZylonGameViewController.swift`)
- Humon Ships → Torpedoes: fires (evidence: `zylons/HumonShip.swift`)
- Humon Ships → Sector Objects: inherits (evidence: `zylons/HumonShip.swift`)
- Player Ship → Sector Objects: inherits (evidence: `zylons/ZylonShip.swift`)
- Torpedoes → Sector Objects: inherits (evidence: `zylons/Torpedo.swift`)
- Scanner → Sector Objects: scans (evidence: `zylons/Scanner.swift`)
- Game Controller → Joystick: accepts input (evidence: `zylons/ZylonGameViewController.swift`)
- Game Controller → HUD: updates display (evidence: `zylons/HUD.swift`)
- Game Controller → Kohai Copilot: uses copilot (evidence: `README.md`)
- Kohai Copilot → Sound Playback: plays commentary
- Second Device → Helm Controller: sends controls (evidence: `README.md`)
- Helm Controller → Game Controller: remotely controls (evidence: `README.md`)
- Main Menu → Prologue: offers prologue (evidence: `README.md`)
