# thomasj/fm1-sidj architecture

> Architecture diagram of the GitHub repository thomasj/fm1-sidj, 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/thomasj/fm1-sidj
- Repository: https://github.com/thomasj/fm1-sidj

## Overview

SiDJ is FM-1 firmware for playing C64 SID tunes and remixing them live. The main device workflow is song selection and loading, cycle-counted C64 emulation, remix processing, SID synthesis, then audio and optional external outputs. UI actions reach the audio engine through queued events; the engine owns the emulation/output work. The README also documents USB audio, ASID, MIDI clock, screen-reader support, and browser-based installation and song management. Several peripheral implementations were not sampled, so only documented or indexed relationships are shown.

Main entry points: [`firmware/src/app/engine.c`](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/engine.c) (Playback engine), [`firmware/src/app/ui.c`](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/ui.c) (Panel UI), [`firmware/src/usb.c`](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/usb.c) (USB and MIDI), [`web/site/fm1songs.js`](https://github.com/thomasj/fm1-sidj/blob/main/web/site/fm1songs.js) (Browser install and songs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["FM-1 player"]
  node_ui["Panel UI<br/>[ui.c]"]
  node_songs[("Song library<br/>[songs.c]")]
  node_storage[("Settings storage<br/>[storage.c]")]
  node_app["FM-1 application<br/>[main_fm1.c]"]
  node_platform["FM-1 platform<br/>[plat_fm1.c]"]
end

subgraph group_audio["Tune and audio engine"]
  node_sidfile["SID file parser<br/>[sidfile.c]"]
  node_c64["C64 emulator<br/>[c64.c]"]
  node_engine["Playback engine<br/>[engine.c]"]
  node_remix["Live remix<br/>[remix.c]"]
  node_sid["SID synthesis<br/>[sid.c]"]
  node_sidtables["SID model tables<br/>[sid_tables.c]"]
  node_beat["Beat detection<br/>[beat.c]"]
  node_audioout["FM-1 audio output<br/>[fm1_audio.h]"]
end

subgraph group_connectivity["Computer and MIDI"]
  node_usb["USB and MIDI<br/>[usb.c]"]
  node_asid["ASID output<br/>[asid.h]"]
  node_screenreader["Screen-reader output<br/>[announce.c]"]
  node_browser["Browser install and songs<br/>[fm1songs.js]"]
end

subgraph group_updates["Firmware updates"]
  node_ota["OTA service<br/>[ota.c]"]
  node_loader["Update loader<br/>[ldr_core.c]"]
  node_flash[("Flash access<br/>[fm1_flash.h]")]
end

node_player(("Listener / performer"))
node_computer(("Computer"))
node_asiddevice["ASID receiver"]
node_midi["MIDI keyboard / clock"]

node_player -->|"operates"| node_ui
node_ui -->|"posts events"| node_engine
node_ui -->|"selects tunes"| node_songs
node_songs -.->|"loads tune data"| node_sidfile
node_engine -->|"runs tune"| node_c64
node_engine -->|"loads tune"| node_sidfile
node_engine -->|"processes writes"| node_remix
node_engine -->|"renders chips"| node_sid
node_engine -->|"sends chip state"| node_asid
node_engine -->|"uses detection"| node_beat
node_sid -->|"uses tables"| node_sidtables
node_engine -.->|"renders audio"| node_audioout
node_engine -.->|"outputs audio and MIDI"| node_usb
node_platform -.->|"supplies controls"| node_ui
node_app -.->|"runs interface"| node_ui
node_ui -.->|"saves settings"| node_storage
node_usb -.->|"receives and sends"| node_midi
node_asid -->|"sends remix"| node_asiddevice
node_usb -->|"provides USB audio"| node_computer
node_engine -.->|"announces screen"| node_screenreader
node_computer -->|"opens site"| node_browser
node_browser -.->|"manages songs"| node_songs
node_browser -.->|"installs firmware"| node_ota
node_ota -->|"serves update package"| node_loader
node_loader -->|"writes app image"| node_flash

click node_ui "https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/ui.c"
click node_songs "https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/songs.c"
click node_storage "https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/storage.c"
click node_app "https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/main_fm1.c"
click node_platform "https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/plat_fm1.c"
click node_sidfile "https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/c64/sidfile.c"
click node_c64 "https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/c64/c64.c"
click node_engine "https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/engine.c"
click node_remix "https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/remix.c"
click node_sid "https://github.com/thomasj/fm1-sidj/blob/main/sid/sid.c"
click node_sidtables "https://github.com/thomasj/fm1-sidj/blob/main/sid/sid_tables.c"
click node_beat "https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/beat.c"
click node_audioout "https://github.com/thomasj/fm1-sidj/blob/main/firmware/hal/fm1_audio.h"
click node_usb "https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/usb.c"
click node_asid "https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/asid.h"
click node_screenreader "https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/announce.c"
click node_browser "https://github.com/thomasj/fm1-sidj/blob/main/web/site/fm1songs.js"
click node_ota "https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/ota.c"
click node_loader "https://github.com/thomasj/fm1-sidj/blob/main/firmware/loader/ldr_core.c"
click node_flash "https://github.com/thomasj/fm1-sidj/blob/main/firmware/hal/fm1_flash.h"

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_ui,node_songs,node_storage,node_app,node_platform toneBlue
class node_sidfile,node_c64,node_engine,node_remix,node_sid,node_sidtables,node_beat,node_audioout toneAmber
class node_usb,node_asid,node_screenreader,node_browser toneMint
class node_ota,node_loader,node_flash toneRose
class node_player,node_computer,node_asiddevice,node_midi toneIndigo
```

## Components

### FM-1 player

- [Panel UI](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/ui.c): `firmware/src/app/ui.c`
- [Song library](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/songs.c): `firmware/src/app/songs.c`
- [Settings storage](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/storage.c): `firmware/src/storage.c`
- [FM-1 application](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/main_fm1.c): `firmware/src/app/main_fm1.c`
- [FM-1 platform](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/plat_fm1.c): `firmware/src/app/plat_fm1.c`

### Tune and audio engine

- [SID file parser](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/c64/sidfile.c): `firmware/src/c64/sidfile.c`
- [C64 emulator](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/c64/c64.c): `firmware/src/c64/c64.c`
- [Playback engine](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/engine.c): `firmware/src/app/engine.c`
- [Live remix](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/remix.c): `firmware/src/app/remix.c`
- [SID synthesis](https://github.com/thomasj/fm1-sidj/blob/main/sid/sid.c): `sid/sid.c`
- [SID model tables](https://github.com/thomasj/fm1-sidj/blob/main/sid/sid_tables.c): `sid/sid_tables.c`
- [Beat detection](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/beat.c): `firmware/src/app/beat.c`
- [FM-1 audio output](https://github.com/thomasj/fm1-sidj/blob/main/firmware/hal/fm1_audio.h): `firmware/hal/fm1_audio.h`

### Computer and MIDI

- [USB and MIDI](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/usb.c): `firmware/src/usb.c`
- [ASID output](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/app/asid.h): `firmware/src/app/asid.h`
- [Screen-reader output](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/announce.c): `firmware/src/announce.c`
- [Browser install and songs](https://github.com/thomasj/fm1-sidj/blob/main/web/site/fm1songs.js): `web/site/fm1songs.js`

### Firmware updates

- [OTA service](https://github.com/thomasj/fm1-sidj/blob/main/firmware/src/ota.c): `firmware/src/ota.c`
- [Update loader](https://github.com/thomasj/fm1-sidj/blob/main/firmware/loader/ldr_core.c): `firmware/loader/ldr_core.c`
- [Flash access](https://github.com/thomasj/fm1-sidj/blob/main/firmware/hal/fm1_flash.h): `firmware/hal/fm1_flash.h`

### Other components

- **Listener / performer**
- **Computer**
- **ASID receiver**
- **MIDI keyboard / clock**

## Connections

- Listener / performer → Panel UI: operates (evidence: `README.md`)
- Panel UI → Playback engine: posts events
- Panel UI → Song library: selects tunes (evidence: `README.md`)
- Song library → SID file parser: loads tune data
- Playback engine → C64 emulator: runs tune
- Playback engine → SID file parser: loads tune
- Playback engine → Live remix: processes writes
- Playback engine → SID synthesis: renders chips
- Playback engine → ASID output: sends chip state
- Playback engine → Beat detection: uses detection (evidence: `firmware/src/app/engine.c`)
- SID synthesis → SID model tables: uses tables (evidence: `sid/sid.c`)
- Playback engine → FM-1 audio output: renders audio
- Playback engine → USB and MIDI: outputs audio and MIDI
- FM-1 platform → Panel UI: supplies controls
- FM-1 application → Panel UI: runs interface
- Panel UI → Settings storage: saves settings
- USB and MIDI → MIDI keyboard / clock: receives and sends
- ASID output → ASID receiver: sends remix (evidence: `README.md`)
- USB and MIDI → Computer: provides USB audio (evidence: `README.md`)
- Playback engine → Screen-reader output: announces screen
- Computer → Browser install and songs: opens site (evidence: `README.md`)
- Browser install and songs → Song library: manages songs
- Browser install and songs → OTA service: installs firmware
- OTA service → Update loader: serves update package (evidence: `firmware/loader/ldr_core.c`)
- Update loader → Flash access: writes app image (evidence: `firmware/loader/ldr_core.c`)