# sergetsyba/rayracer architecture

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

- Interactive diagram: https://gitdiagram.com/sergetsyba/rayracer
- Repository: https://github.com/sergetsyba/rayracer

## Overview

Ray Racer is a macOS Atari 2600 emulator with a debugger; the README notes that emulation is partial. The main workflow is to open a cartridge, hand it to the console for emulation, and display generated fields in the screen window. Users can also inspect disassembly and system state, set breakpoints, and step execution. The graph preserves the documented emulator domains, but their internal call wiring is not established by the sampled C sources, so those links are omitted.

Main entry points: [`RayRacer/MainMenuController.swift`](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/MainMenuController.swift) (Main menu), [`RayRacer/Screen/ScreenWindowController.swift`](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Screen/ScreenWindowController.swift) (Screen window), [`RayRacer/RayRacerKit/Atari2600.swift`](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/RayRacerKit/Atari2600.swift) (Console wrapper), [`RayRacer/Debugger/DebuggerWindowController.swift`](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Debugger/DebuggerWindowController.swift) (Debugger window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["macOS App"]
  node_menu["Main menu"]
  node_screen["Screen window"]
  node_renderer["Metal renderer<br/>[Renderer.swift]"]
  node_framebuffer["Field buffer"]
end

subgraph group_media["Cartridge Handling"]
  node_cartridge["Cartridge<br/>[Cartridge.swift]"]
  node_cartridgekind["Cartridge kind"]
  node_collection["Cartridge collection<br/>[Atari2600.swift]"]
  node_preferences[("Recent cartridges<br/>[Cartridge.swift]")]
end

subgraph group_emulator["Emulation Core"]
  node_console["Console wrapper<br/>[Atari2600.swift]"]
  node_core["Console core<br/>[atari2600.c]"]
  node_cpu["6507 CPU<br/>[mcs6507.c]"]
  node_riot["6532 RIOT<br/>[mcs6532.c]"]
  node_tia["TIA video<br/>[tia.c]"]
  node_graphics["Graphics<br/>[graphics.c]"]
  node_cartcore["Cartridge mapping<br/>[cartridge.c]"]
  node_controller["Joystick input<br/>[controller.c]"]
  node_thread["Emulation thread<br/>[thread.c]"]
end

subgraph group_debugger["Debugger"]
  node_debugwindow["Debugger window"]
  node_assembly["Assembly view"]
  node_disassembly["Disassembler"]
  node_state["System state view"]
  node_stepper["Step controls"]
end

node_user(("User"))
node_rom["Cartridge file"]

node_user -->|"selects"| node_menu
node_user -->|"chooses"| node_rom
node_menu -->|"opens"| node_cartridge
node_cartridge -->|"reads"| node_rom
node_cartridge -->|"classifies"| node_cartridgekind
node_menu -->|"plays cartridge"| node_collection
node_collection -->|"selects game"| node_console
node_menu -->|"clears recents"| node_preferences
node_preferences -->|"supplies recents"| node_menu
node_menu -->|"sets switches"| node_console
node_menu -->|"resets"| node_console
node_screen -->|"creates thread"| node_thread
node_screen -->|"passes console"| node_console
node_thread -->|"writes fields"| node_framebuffer
node_screen -->|"pauses and resumes"| node_thread
node_screen -->|"configures view"| node_renderer
node_renderer -->|"renders fields"| node_framebuffer
node_debugwindow -->|"hosts"| node_assembly
node_debugwindow -->|"hosts"| node_state
node_debugwindow -->|"dispatches stepping"| node_stepper
node_assembly -->|"decodes instructions"| node_disassembly

click node_menu "https://github.com/sergetsyba/rayracer/blob/main/RayRacer/MainMenuController.swift"
click node_screen "https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Screen/ScreenWindowController.swift"
click node_renderer "https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Screen/Renderer.swift"
click node_framebuffer "https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Screen/ScreenWindowController.swift"
click node_cartridge "https://github.com/sergetsyba/rayracer/blob/main/RayRacer/RayRacerKit/Cartridge.swift"
click node_cartridgekind "https://github.com/sergetsyba/rayracer/blob/main/RayRacer/RayRacerKit/CartridgeKind.swift"
click node_collection "https://github.com/sergetsyba/rayracer/blob/main/RayRacer/RayRacerKit/Atari2600.swift"
click node_preferences "https://github.com/sergetsyba/rayracer/blob/main/RayRacer/RayRacerKit/Cartridge.swift"
click node_console "https://github.com/sergetsyba/rayracer/blob/main/RayRacer/RayRacerKit/Atari2600.swift"
click node_core "https://github.com/sergetsyba/rayracer/blob/main/librayracer/atari2600.c"
click node_cpu "https://github.com/sergetsyba/rayracer/blob/main/librayracer/mcs6507.c"
click node_riot "https://github.com/sergetsyba/rayracer/blob/main/librayracer/mcs6532.c"
click node_tia "https://github.com/sergetsyba/rayracer/blob/main/librayracer/tia.c"
click node_graphics "https://github.com/sergetsyba/rayracer/blob/main/librayracer/graphics.c"
click node_cartcore "https://github.com/sergetsyba/rayracer/blob/main/librayracer/cartridge.c"
click node_controller "https://github.com/sergetsyba/rayracer/blob/main/librayracer/controller.c"
click node_thread "https://github.com/sergetsyba/rayracer/blob/main/librayracer/thread.c"
click node_debugwindow "https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Debugger/DebuggerWindowController.swift"
click node_assembly "https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Debugger/AssemblyViewController.swift"
click node_disassembly "https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Debugger/AssemblyViewController%2BDisassembly.swift"
click node_state "https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Debugger/SystemStateViewController.swift"
click node_stepper "https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Debugger/MultiStepperViewController.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_screen,node_renderer,node_framebuffer,node_user toneBlue
class node_cartridge,node_cartridgekind,node_collection,node_preferences toneAmber
class node_console,node_core,node_cpu,node_riot,node_tia,node_graphics,node_cartcore,node_controller,node_thread toneMint
class node_debugwindow,node_assembly,node_disassembly,node_state,node_stepper toneRose
class node_rom toneIndigo
```

## Components

### macOS App

- [Main menu](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/MainMenuController.swift): `RayRacer/MainMenuController.swift`
- [Screen window](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Screen/ScreenWindowController.swift): `RayRacer/Screen/ScreenWindowController.swift`
- [Metal renderer](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Screen/Renderer.swift): `RayRacer/Screen/Renderer.swift`
- [Field buffer](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Screen/ScreenWindowController.swift): `RayRacer/Screen/ScreenWindowController.swift`

### Cartridge Handling

- [Cartridge](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/RayRacerKit/Cartridge.swift): `RayRacer/RayRacerKit/Cartridge.swift`
- [Cartridge kind](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/RayRacerKit/CartridgeKind.swift): `RayRacer/RayRacerKit/CartridgeKind.swift`
- [Cartridge collection](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/RayRacerKit/Atari2600.swift): `RayRacer/RayRacerKit/Atari2600.swift`
- [Recent cartridges](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/RayRacerKit/Cartridge.swift): `RayRacer/RayRacerKit/Cartridge.swift`

### Emulation Core

- [Console wrapper](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/RayRacerKit/Atari2600.swift): `RayRacer/RayRacerKit/Atari2600.swift`
- [Console core](https://github.com/sergetsyba/rayracer/blob/main/librayracer/atari2600.c): `librayracer/atari2600.c`
- [6507 CPU](https://github.com/sergetsyba/rayracer/blob/main/librayracer/mcs6507.c): `librayracer/mcs6507.c`
- [6532 RIOT](https://github.com/sergetsyba/rayracer/blob/main/librayracer/mcs6532.c): `librayracer/mcs6532.c`
- [TIA video](https://github.com/sergetsyba/rayracer/blob/main/librayracer/tia.c): `librayracer/tia.c`
- [Graphics](https://github.com/sergetsyba/rayracer/blob/main/librayracer/graphics.c): `librayracer/graphics.c`
- [Cartridge mapping](https://github.com/sergetsyba/rayracer/blob/main/librayracer/cartridge.c): `librayracer/cartridge.c`
- [Joystick input](https://github.com/sergetsyba/rayracer/blob/main/librayracer/controller.c): `librayracer/controller.c`
- [Emulation thread](https://github.com/sergetsyba/rayracer/blob/main/librayracer/thread.c): `librayracer/thread.c`

### Debugger

- [Debugger window](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Debugger/DebuggerWindowController.swift): `RayRacer/Debugger/DebuggerWindowController.swift`
- [Assembly view](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Debugger/AssemblyViewController.swift): `RayRacer/Debugger/AssemblyViewController.swift`
- [Disassembler](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Debugger/AssemblyViewController%2BDisassembly.swift): `RayRacer/Debugger/AssemblyViewController+Disassembly.swift`
- [System state view](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Debugger/SystemStateViewController.swift): `RayRacer/Debugger/SystemStateViewController.swift`
- [Step controls](https://github.com/sergetsyba/rayracer/blob/main/RayRacer/Debugger/MultiStepperViewController.swift): `RayRacer/Debugger/MultiStepperViewController.swift`

### Other components

- **User**
- **Cartridge file**

## Connections

- User → Main menu: selects
- User → Cartridge file: chooses
- Main menu → Cartridge: opens
- Cartridge → Cartridge file: reads
- Cartridge → Cartridge kind: classifies
- Main menu → Cartridge collection: plays cartridge
- Cartridge collection → Console wrapper: selects game
- Main menu → Recent cartridges: clears recents
- Recent cartridges → Main menu: supplies recents
- Main menu → Console wrapper: sets switches
- Main menu → Console wrapper: resets
- Screen window → Emulation thread: creates thread
- Screen window → Console wrapper: passes console
- Emulation thread → Field buffer: writes fields
- Screen window → Emulation thread: pauses and resumes
- Screen window → Metal renderer: configures view
- Metal renderer → Field buffer: renders fields
- Debugger window → Assembly view: hosts
- Debugger window → System state view: hosts
- Debugger window → Step controls: dispatches stepping
- Assembly view → Disassembler: decodes instructions