# factor-64/ra2snes architecture

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

- Interactive diagram: https://gitdiagram.com/factor-64/ra2snes
- Repository: https://github.com/factor-64/ra2snes

## Overview

RA2Snes connects a real SNES through SD2Snes/QUsb2Snes to RetroAchievements: the user signs in, a detected game is identified, achievement data is loaded, and SNES memory is monitored to evaluate and report unlocks. The graph also captures the QML-facing models, live status, and update capability. Core control flow is supported by sampled sources; some model and update details are inferred only from their exact tree paths and the documented product scope.

Main entry points: [`ra2snes.cpp`](https://github.com/factor-64/ra2snes/blob/master/ra2snes.cpp) (Session controller), [`raclient.cpp`](https://github.com/factor-64/ra2snes/blob/master/raclient.cpp) (RA client), [`ui`](https://github.com/factor-64/ra2snes/tree/master/ui) (QML interface), [`main.cpp`](https://github.com/factor-64/ra2snes/blob/master/main.cpp) (Application entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application and UI"]
  node_entry["Application entry<br/>[main.cpp]"]
  node_qml["QML interface"]
  node_controller["Session controller<br/>[ra2snes.cpp]"]
  node_game["Game model<br/>[gameinfomodel.cpp]"]
  node_profile["User model<br/>[userinfomodel.cpp]"]
  node_achievement_model["Achievement model"]
  node_achievement_filter["Achievement filter"]
end

subgraph group_console["Console integration"]
  node_usb_client["USB2SNES client<br/>[usb2snes.cpp]"]
end

subgraph group_achievements["Achievement runtime"]
  node_memory_reader["Memory reader<br/>[memoryreader.cpp]"]
  node_rcheevos["rcheevos runtime"]
end

subgraph group_services["Network services"]
  node_ra_client["RA client<br/>[raclient.cpp]"]
  node_update_check["Update manager<br/>[ra2snes.cpp]"]
  node_updater["Updater<br/>[updater.cpp]"]
  node_cache[("Network cache")]
end

node_user(("Player"))
node_qusb(("QUsb2Snes server"))
node_console_device(("SD2Snes / SNES"))
node_ra_service(("RetroAchievements"))
node_github(("GitHub releases"))

node_user -->|"uses"| node_qml
node_entry -->|"loads"| node_qml
node_entry -->|"registers"| node_controller
node_qml -->|"controls"| node_controller
node_qml -->|"reads"| node_game
node_qml -->|"reads"| node_profile
node_qml -->|"filters"| node_achievement_filter
node_achievement_filter -->|"filters"| node_achievement_model
node_controller -->|"controls"| node_usb_client
node_usb_client -->|"WebSocket commands"| node_qusb
node_qusb -->|"controls"| node_console_device
node_console_device -->|"memory data"| node_qusb
node_qusb -->|"returns memory"| node_usb_client
node_controller -->|"requests sessions"| node_ra_client
node_ra_client -->|"API requests"| node_ra_service
node_ra_service -->|"game and user data"| node_ra_client
node_ra_client -->|"updates"| node_achievement_model
node_ra_client -->|"updates"| node_game
node_ra_client -->|"updates"| node_profile
node_controller -->|"initializes and polls"| node_memory_reader
node_controller -->|"evaluates triggers"| node_rcheevos
node_memory_reader -->|"builds triggers"| node_rcheevos
node_ra_client -->|"reports unlocks"| node_ra_service
node_controller -->|"checks updates"| node_update_check
node_update_check -->|"queries releases"| node_github
node_update_check -.->|"launches"| node_updater
node_entry -->|"configures network cache"| node_cache

click node_entry "https://github.com/factor-64/ra2snes/blob/master/main.cpp"
click node_qml "https://github.com/factor-64/ra2snes/tree/master/ui"
click node_controller "https://github.com/factor-64/ra2snes/blob/master/ra2snes.cpp"
click node_game "https://github.com/factor-64/ra2snes/blob/master/gameinfomodel.cpp"
click node_profile "https://github.com/factor-64/ra2snes/blob/master/userinfomodel.cpp"
click node_achievement_model "https://github.com/factor-64/ra2snes/blob/master/achievementmodel.cpp"
click node_achievement_filter "https://github.com/factor-64/ra2snes/blob/master/achievementsortfilterproxymodel.cpp"
click node_usb_client "https://github.com/factor-64/ra2snes/blob/master/usb2snes.cpp"
click node_memory_reader "https://github.com/factor-64/ra2snes/blob/master/memoryreader.cpp"
click node_rcheevos "https://github.com/factor-64/ra2snes/tree/master/rcheevos"
click node_ra_client "https://github.com/factor-64/ra2snes/blob/master/raclient.cpp"
click node_update_check "https://github.com/factor-64/ra2snes/blob/master/ra2snes.cpp"
click node_updater "https://github.com/factor-64/ra2snes/blob/master/updater.cpp"
click node_cache "https://github.com/factor-64/ra2snes/blob/master/networkcachemanager.cpp"

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_entry,node_qml,node_controller,node_game,node_profile,node_achievement_model,node_achievement_filter toneBlue
class node_usb_client toneAmber
class node_memory_reader,node_rcheevos,node_qusb toneMint
class node_ra_client,node_update_check,node_updater,node_cache toneRose
class node_user,node_console_device,node_ra_service,node_github toneIndigo
```

## Components

### Application and UI

- [Application entry](https://github.com/factor-64/ra2snes/blob/master/main.cpp): `main.cpp`
- [QML interface](https://github.com/factor-64/ra2snes/tree/master/ui): `ui`
- [Session controller](https://github.com/factor-64/ra2snes/blob/master/ra2snes.cpp): `ra2snes.cpp`
- [Game model](https://github.com/factor-64/ra2snes/blob/master/gameinfomodel.cpp): `gameinfomodel.cpp`
- [User model](https://github.com/factor-64/ra2snes/blob/master/userinfomodel.cpp): `userinfomodel.cpp`
- [Achievement model](https://github.com/factor-64/ra2snes/blob/master/achievementmodel.cpp): `achievementmodel.cpp`
- [Achievement filter](https://github.com/factor-64/ra2snes/blob/master/achievementsortfilterproxymodel.cpp): `achievementsortfilterproxymodel.cpp`

### Console integration

- [USB2SNES client](https://github.com/factor-64/ra2snes/blob/master/usb2snes.cpp): `usb2snes.cpp`

### Achievement runtime

- [Memory reader](https://github.com/factor-64/ra2snes/blob/master/memoryreader.cpp): `memoryreader.cpp`
- [rcheevos runtime](https://github.com/factor-64/ra2snes/tree/master/rcheevos): `rcheevos`

### Network services

- [RA client](https://github.com/factor-64/ra2snes/blob/master/raclient.cpp): `raclient.cpp`
- [Update manager](https://github.com/factor-64/ra2snes/blob/master/ra2snes.cpp): `ra2snes.cpp`
- [Updater](https://github.com/factor-64/ra2snes/blob/master/updater.cpp): `updater.cpp`
- [Network cache](https://github.com/factor-64/ra2snes/blob/master/networkcachemanager.cpp): `networkcachemanager.cpp`

### Other components

- **Player**
- **QUsb2Snes server**
- **SD2Snes / SNES**
- **RetroAchievements**
- **GitHub releases**

## Connections

- Player → QML interface: uses
- Application entry → QML interface: loads
- Application entry → Session controller: registers
- QML interface → Session controller: controls
- QML interface → Game model: reads
- QML interface → User model: reads
- QML interface → Achievement filter: filters
- Achievement filter → Achievement model: filters
- Session controller → USB2SNES client: controls
- USB2SNES client → QUsb2Snes server: WebSocket commands
- QUsb2Snes server → SD2Snes / SNES: controls
- SD2Snes / SNES → QUsb2Snes server: memory data
- QUsb2Snes server → USB2SNES client: returns memory
- Session controller → RA client: requests sessions
- RA client → RetroAchievements: API requests
- RetroAchievements → RA client: game and user data
- RA client → Achievement model: updates
- RA client → Game model: updates
- RA client → User model: updates
- Session controller → Memory reader: initializes and polls
- Session controller → rcheevos runtime: evaluates triggers
- Memory reader → rcheevos runtime: builds triggers
- RA client → RetroAchievements: reports unlocks
- Session controller → Update manager: checks updates
- Update manager → GitHub releases: queries releases
- Update manager → Updater: launches
- Application entry → Network cache: configures network cache