# ishrak-saleh/drift-ds architecture

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

- Interactive diagram: https://gitdiagram.com/ishrak-saleh/drift-ds
- Repository: https://github.com/ishrak-saleh/drift-ds

## Overview

DriftDS is a native PC port of Mario Kart DS that runs user-supplied game data. The principal workflow is to translate ARM/Thumb game code into C, load the ROM and translated code, then boot the emulated DS processors and render the game for the player. Runtime subsystems cover DS hardware, graphics, input, audio, saves, and diagnostics. The README documents the product and ROM requirement; several runtime connections are supported by source comments or interfaces, but unsampled implementation details are not inferred.

Main entry points: [`runtime/ds.c`](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/ds.c) (DS Hardware), [`tools/translate.py`](https://github.com/ishrak-saleh/drift-ds/blob/main/tools/translate.py) (Translation Driver), [`tools/armc/recompiler.py`](https://github.com/ishrak-saleh/drift-ds/blob/main/tools/armc/recompiler.py) (Recompiler), [`runtime/main.c`](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/main.c) (Runtime Boot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_translation["Code Translation"]
  node_translator["Translation Driver<br/>[translate.py]"]
  node_rom_reader["ROM Reader<br/>[rom_reader.py]"]
  node_code_image["Code Image<br/>[code_image.py]"]
  node_function_finder["Function Finder<br/>[finder.py]"]
  node_instruction_decoder["Instruction Decoder<br/>[decode.py]"]
  node_recompiler["Recompiler<br/>[recompiler.py]"]
  node_arm_emitter["ARM Emitter<br/>[emit_arm.py]"]
  node_thumb_emitter["Thumb Emitter<br/>[emit_thumb.py]"]
end

subgraph group_runtime["Emulation Runtime"]
  node_main["Runtime Boot<br/>[main.c]"]
  node_cpu["CPU Emulation<br/>[cpu.c]"]
  node_ds["DS Hardware<br/>[ds.c]"]
  node_memory["Memory Bus<br/>[memory.c]"]
  node_threads["Thread Scheduling<br/>[threads.c]"]
end

subgraph group_presentation["Player Experience"]
  node_video["2D Video<br/>[video.c]"]
  node_gpu3d["3D Graphics<br/>[gpu3d.c]"]
  node_window["Window and Display<br/>[window.c]"]
  node_keys["Input Mapping<br/>[keys.c]"]
  node_sound["Sound Output<br/>[sound.c]"]
  node_microphone["Microphone Input<br/>[microphone.c]"]
end

subgraph group_support["Runtime Services"]
  node_settings["Settings Parser<br/>[inifile.c]"]
  node_save[("Save State Files<br/>[ds.c]")]
  node_logging["Logging and Metrics<br/>[log.c]"]
  node_system_info["System Information<br/>[sysinfo.c]"]
end

node_player(("Player"))
node_rom["Game ROM"]

node_player -->|"provides"| node_rom
node_rom -.->|"translates"| node_translator
node_translator -->|"reads ROM"| node_rom_reader
node_translator -->|"builds image"| node_code_image
node_translator -->|"recompiles"| node_recompiler
node_function_finder -->|"decodes instructions"| node_instruction_decoder
node_recompiler -->|"finds functions"| node_function_finder
node_recompiler -->|"emits ARM"| node_arm_emitter
node_recompiler -->|"emits Thumb"| node_thumb_emitter
node_player -->|"starts game"| node_main
node_main -->|"boots processors"| node_ds
node_main -->|"reads settings"| node_settings
node_ds -->|"runs processors"| node_cpu
node_ds -->|"draws screens"| node_video
node_ds -->|"renders 3D"| node_gpu3d
node_ds -->|"writes saves"| node_save
node_ds -->|"requests input"| node_microphone
node_memory -->|"uses hardware state"| node_ds
node_threads -->|"uses processor state"| node_ds
node_window -->|"presents frames"| node_video
node_window -->|"reads controls"| node_keys
node_window -->|"reports display mode"| node_logging
node_sound -->|"uses hardware state"| node_ds
node_main -->|"reports runtime"| node_logging
node_logging -->|"reports machine"| node_system_info

click node_translator "https://github.com/ishrak-saleh/drift-ds/blob/main/tools/translate.py"
click node_rom_reader "https://github.com/ishrak-saleh/drift-ds/blob/main/tools/rom_reader.py"
click node_code_image "https://github.com/ishrak-saleh/drift-ds/blob/main/tools/armc/code_image.py"
click node_function_finder "https://github.com/ishrak-saleh/drift-ds/blob/main/tools/armc/finder.py"
click node_instruction_decoder "https://github.com/ishrak-saleh/drift-ds/blob/main/tools/armc/decode.py"
click node_recompiler "https://github.com/ishrak-saleh/drift-ds/blob/main/tools/armc/recompiler.py"
click node_arm_emitter "https://github.com/ishrak-saleh/drift-ds/blob/main/tools/armc/emit_arm.py"
click node_thumb_emitter "https://github.com/ishrak-saleh/drift-ds/blob/main/tools/armc/emit_thumb.py"
click node_main "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/main.c"
click node_cpu "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/cpu.c"
click node_ds "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/ds.c"
click node_memory "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/memory.c"
click node_threads "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/threads.c"
click node_video "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/video.c"
click node_gpu3d "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/gpu3d.c"
click node_window "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/window.c"
click node_keys "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/keys.c"
click node_sound "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/sound.c"
click node_microphone "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/microphone.c"
click node_settings "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/inifile.c"
click node_save "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/ds.c"
click node_logging "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/log.c"
click node_system_info "https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/sysinfo.c"

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_translator,node_rom_reader,node_code_image,node_function_finder,node_instruction_decoder,node_recompiler,node_arm_emitter,node_thumb_emitter toneBlue
class node_main,node_cpu,node_ds,node_memory,node_threads toneAmber
class node_video,node_gpu3d,node_window,node_keys,node_sound,node_microphone toneMint
class node_settings,node_save,node_logging,node_system_info toneRose
class node_player,node_rom toneIndigo
```

## Components

### Code Translation

- [Translation Driver](https://github.com/ishrak-saleh/drift-ds/blob/main/tools/translate.py): `tools/translate.py`
- [ROM Reader](https://github.com/ishrak-saleh/drift-ds/blob/main/tools/rom_reader.py): `tools/rom_reader.py`
- [Code Image](https://github.com/ishrak-saleh/drift-ds/blob/main/tools/armc/code_image.py): `tools/armc/code_image.py`
- [Function Finder](https://github.com/ishrak-saleh/drift-ds/blob/main/tools/armc/finder.py): `tools/armc/finder.py`
- [Instruction Decoder](https://github.com/ishrak-saleh/drift-ds/blob/main/tools/armc/decode.py): `tools/armc/decode.py`
- [Recompiler](https://github.com/ishrak-saleh/drift-ds/blob/main/tools/armc/recompiler.py): `tools/armc/recompiler.py`
- [ARM Emitter](https://github.com/ishrak-saleh/drift-ds/blob/main/tools/armc/emit_arm.py): `tools/armc/emit_arm.py`
- [Thumb Emitter](https://github.com/ishrak-saleh/drift-ds/blob/main/tools/armc/emit_thumb.py): `tools/armc/emit_thumb.py`

### Emulation Runtime

- [Runtime Boot](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/main.c): `runtime/main.c`
- [CPU Emulation](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/cpu.c): `runtime/cpu.c`
- [DS Hardware](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/ds.c): `runtime/ds.c`
- [Memory Bus](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/memory.c): `runtime/memory.c`
- [Thread Scheduling](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/threads.c): `runtime/threads.c`

### Player Experience

- [2D Video](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/video.c): `runtime/video.c`
- [3D Graphics](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/gpu3d.c): `runtime/gpu3d.c`
- [Window and Display](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/window.c): `runtime/window.c`
- [Input Mapping](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/keys.c): `runtime/keys.c`
- [Sound Output](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/sound.c): `runtime/sound.c`
- [Microphone Input](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/microphone.c): `runtime/microphone.c`

### Runtime Services

- [Settings Parser](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/inifile.c): `runtime/inifile.c`
- [Save State Files](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/ds.c): `runtime/ds.c`
- [Logging and Metrics](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/log.c): `runtime/log.c`
- [System Information](https://github.com/ishrak-saleh/drift-ds/blob/main/runtime/sysinfo.c): `runtime/sysinfo.c`

### Other components

- **Player**
- **Game ROM**

## Connections

- Player → Game ROM: provides (evidence: `README.md`)
- Game ROM → Translation Driver: translates
- Translation Driver → ROM Reader: reads ROM (evidence: `tools/translate.py`)
- Translation Driver → Code Image: builds image (evidence: `tools/translate.py`)
- Translation Driver → Recompiler: recompiles (evidence: `tools/translate.py`)
- Function Finder → Instruction Decoder: decodes instructions (evidence: `tools/armc/finder.py`)
- Recompiler → Function Finder: finds functions (evidence: `tools/armc/recompiler.py`)
- Recompiler → ARM Emitter: emits ARM (evidence: `tools/armc/recompiler.py`)
- Recompiler → Thumb Emitter: emits Thumb (evidence: `tools/armc/recompiler.py`)
- Player → Runtime Boot: starts game (evidence: `README.md`)
- Runtime Boot → DS Hardware: boots processors (evidence: `runtime/main.c`)
- Runtime Boot → Settings Parser: reads settings (evidence: `runtime/main.c`)
- DS Hardware → CPU Emulation: runs processors (evidence: `runtime/ds.c`)
- DS Hardware → 2D Video: draws screens (evidence: `runtime/ds.c`)
- DS Hardware → 3D Graphics: renders 3D (evidence: `runtime/ds.c`)
- DS Hardware → Save State Files: writes saves (evidence: `runtime/ds.c`)
- DS Hardware → Microphone Input: requests input (evidence: `runtime/ds.c`)
- Memory Bus → DS Hardware: uses hardware state (evidence: `runtime/memory.c`)
- Thread Scheduling → DS Hardware: uses processor state (evidence: `runtime/threads.c`)
- Window and Display → 2D Video: presents frames
- Window and Display → Input Mapping: reads controls (evidence: `runtime/window.c`)
- Window and Display → Logging and Metrics: reports display mode
- Sound Output → DS Hardware: uses hardware state (evidence: `runtime/sound.c`)
- Runtime Boot → Logging and Metrics: reports runtime (evidence: `runtime/main.c`)
- Logging and Metrics → System Information: reports machine (evidence: `runtime/log.c`)