# abduznik/freegosy architecture

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

## Overview

Freegosy is a cross-platform Flutter client for browsing a RomM library, downloading games, and launching them through installed emulators. Users browse or filter games, download ROMs, then launch a game; launching can also trigger save backup/synchronization and play-session tracking. Other major capabilities include offline metadata, emulator and BIOS management, controller configuration, RetroArch core selection, and headless commands. The README documents these behaviors, but the sampled source is mostly platform bootstrap code, so detailed internal call wiring is not verified; uncertain links are omitted.

Main entry points: [`lib/app.dart`](https://github.com/abduznik/freegosy/blob/main/lib/app.dart) (Flutter app), [`lib/core/emulator/game_launch_service.dart`](https://github.com/abduznik/freegosy/blob/main/lib/core/emulator/game_launch_service.dart) (Game launcher), [`lib/core/romm/romm_service.dart`](https://github.com/abduznik/freegosy/blob/main/lib/core/romm/romm_service.dart) (RomM client), [`lib/ui/screens/game_detail_screen.dart`](https://github.com/abduznik/freegosy/blob/main/lib/ui/screens/game_detail_screen.dart) (Game details UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["App interface"]
  node_app["Flutter app<br/>[app.dart]"]
  node_entry["App entry<br/>[main.dart]"]
  node_library_ui["Game library UI"]
  node_detail_ui["Game details UI"]
  node_settings_ui["Settings UI"]
  node_download_ui["Download UI"]
  node_providers["App state providers"]
end

subgraph group_library["Library services"]
  node_romm_provider["RomM provider<br/>[romm_provider.dart]"]
  node_romm_service["RomM client<br/>[romm_service.dart]"]
  node_metadata_cache["Metadata cache"]
  node_download_service["ROM downloader"]
end

subgraph group_play["Game execution"]
  node_launch_service["Game launcher"]
  node_strategy_registry["Emulator strategies"]
  node_emulator_management["Emulator management"]
  node_firmware["BIOS and firmware"]
  node_retroarch["RetroArch cores"]
end

subgraph group_sync["Saves and sync"]
  node_save_sync["Save synchronization"]
  node_backup["Save backups"]
  node_sync_queue["Background sync queue"]
  node_session_tracker["Play session tracking"]
end

subgraph group_platform["Platform features"]
  node_cli["Headless commands<br/>[main_cli.dart]"]
  node_input["Controller input"]
  node_achievements["RetroAchievements"]
end

node_user(("Player"))
node_romm_server(("RomM server"))

node_user -->|"uses"| node_app
node_entry -->|"starts"| node_app
node_app -->|"presents"| node_library_ui
node_app -->|"presents"| node_detail_ui
node_app -->|"presents"| node_settings_ui
node_app -->|"presents"| node_download_ui
node_library_ui -->|"reads state"| node_providers
node_detail_ui -->|"reads state"| node_providers
node_download_ui -->|"reads state"| node_providers
node_providers -->|"delegates"| node_romm_provider
node_romm_provider -->|"requests"| node_romm_service
node_romm_service -->|"fetches library"| node_romm_server
node_romm_service -->|"caches metadata"| node_metadata_cache
node_download_ui -->|"requests download"| node_download_service
node_download_service -->|"downloads ROM"| node_romm_server
node_detail_ui -->|"requests launch"| node_launch_service
node_launch_service -->|"selects strategy"| node_strategy_registry
node_settings_ui -->|"manages emulators"| node_emulator_management
node_settings_ui -->|"manages BIOS"| node_firmware
node_settings_ui -->|"configures cores"| node_retroarch
node_launch_service -->|"runs save pipeline"| node_save_sync
node_save_sync -->|"creates backups"| node_backup
node_save_sync -->|"syncs saves"| node_romm_service
node_save_sync -->|"queues offline work"| node_sync_queue
node_launch_service -->|"records sessions"| node_session_tracker
node_user -->|"runs commands"| node_cli
node_cli -->|"uses account"| node_romm_service
node_cli -->|"downloads ROM"| node_download_service
node_cli -->|"launches game"| node_launch_service
node_user -->|"controls games"| node_input
node_detail_ui -.->|"shows achievements"| node_achievements

click node_app "https://github.com/abduznik/freegosy/blob/main/lib/app.dart"
click node_entry "https://github.com/abduznik/freegosy/blob/main/lib/main.dart"
click node_library_ui "https://github.com/abduznik/freegosy/blob/main/lib/ui/screens/library_screen.dart"
click node_detail_ui "https://github.com/abduznik/freegosy/blob/main/lib/ui/screens/game_detail_screen.dart"
click node_settings_ui "https://github.com/abduznik/freegosy/blob/main/lib/ui/screens/settings_screen.dart"
click node_download_ui "https://github.com/abduznik/freegosy/blob/main/lib/ui/screens/download_screen.dart"
click node_providers "https://github.com/abduznik/freegosy/tree/main/lib/providers"
click node_romm_provider "https://github.com/abduznik/freegosy/blob/main/lib/providers/romm_provider.dart"
click node_romm_service "https://github.com/abduznik/freegosy/blob/main/lib/core/romm/romm_service.dart"
click node_metadata_cache "https://github.com/abduznik/freegosy/blob/main/lib/core/storage/metadata_cache_service.dart"
click node_download_service "https://github.com/abduznik/freegosy/blob/main/lib/core/downloader/download_service.dart"
click node_launch_service "https://github.com/abduznik/freegosy/blob/main/lib/core/emulator/game_launch_service.dart"
click node_strategy_registry "https://github.com/abduznik/freegosy/blob/main/lib/core/emulator/strategy_registry.dart"
click node_emulator_management "https://github.com/abduznik/freegosy/blob/main/lib/core/emulator/emulator_download_service.dart"
click node_firmware "https://github.com/abduznik/freegosy/blob/main/lib/core/emulator/firmware_service.dart"
click node_retroarch "https://github.com/abduznik/freegosy/blob/main/lib/core/emulator/retroarch_core_list.dart"
click node_save_sync "https://github.com/abduznik/freegosy/blob/main/lib/core/save/save_sync_service.dart"
click node_backup "https://github.com/abduznik/freegosy/blob/main/lib/core/save/backup_service.dart"
click node_sync_queue "https://github.com/abduznik/freegosy/blob/main/lib/core/save/background_sync_queue.dart"
click node_session_tracker "https://github.com/abduznik/freegosy/blob/main/lib/core/romm/activity_session_tracker.dart"
click node_cli "https://github.com/abduznik/freegosy/blob/main/lib/main_cli.dart"
click node_input "https://github.com/abduznik/freegosy/blob/main/lib/core/input/gamepad_service.dart"
click node_achievements "https://github.com/abduznik/freegosy/blob/main/lib/core/retroachievements/retroachievements_service.dart"

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_app,node_entry,node_library_ui,node_detail_ui,node_settings_ui,node_download_ui,node_providers toneBlue
class node_romm_provider,node_romm_service,node_metadata_cache,node_download_service toneAmber
class node_launch_service,node_strategy_registry,node_emulator_management,node_firmware,node_retroarch,node_romm_server toneMint
class node_save_sync,node_backup,node_sync_queue,node_session_tracker toneRose
class node_cli,node_input,node_achievements,node_user toneIndigo
```

## Components

### App interface

- [Flutter app](https://github.com/abduznik/freegosy/blob/main/lib/app.dart): `lib/app.dart`
- [App entry](https://github.com/abduznik/freegosy/blob/main/lib/main.dart): `lib/main.dart`
- [Game library UI](https://github.com/abduznik/freegosy/blob/main/lib/ui/screens/library_screen.dart): `lib/ui/screens/library_screen.dart`
- [Game details UI](https://github.com/abduznik/freegosy/blob/main/lib/ui/screens/game_detail_screen.dart): `lib/ui/screens/game_detail_screen.dart`
- [Settings UI](https://github.com/abduznik/freegosy/blob/main/lib/ui/screens/settings_screen.dart): `lib/ui/screens/settings_screen.dart`
- [Download UI](https://github.com/abduznik/freegosy/blob/main/lib/ui/screens/download_screen.dart): `lib/ui/screens/download_screen.dart`
- [App state providers](https://github.com/abduznik/freegosy/tree/main/lib/providers): `lib/providers`

### Library services

- [RomM provider](https://github.com/abduznik/freegosy/blob/main/lib/providers/romm_provider.dart): `lib/providers/romm_provider.dart`
- [RomM client](https://github.com/abduznik/freegosy/blob/main/lib/core/romm/romm_service.dart): `lib/core/romm/romm_service.dart`
- [Metadata cache](https://github.com/abduznik/freegosy/blob/main/lib/core/storage/metadata_cache_service.dart): `lib/core/storage/metadata_cache_service.dart`
- [ROM downloader](https://github.com/abduznik/freegosy/blob/main/lib/core/downloader/download_service.dart): `lib/core/downloader/download_service.dart`

### Game execution

- [Game launcher](https://github.com/abduznik/freegosy/blob/main/lib/core/emulator/game_launch_service.dart): `lib/core/emulator/game_launch_service.dart`
- [Emulator strategies](https://github.com/abduznik/freegosy/blob/main/lib/core/emulator/strategy_registry.dart): `lib/core/emulator/strategy_registry.dart`
- [Emulator management](https://github.com/abduznik/freegosy/blob/main/lib/core/emulator/emulator_download_service.dart): `lib/core/emulator/emulator_download_service.dart`
- [BIOS and firmware](https://github.com/abduznik/freegosy/blob/main/lib/core/emulator/firmware_service.dart): `lib/core/emulator/firmware_service.dart`
- [RetroArch cores](https://github.com/abduznik/freegosy/blob/main/lib/core/emulator/retroarch_core_list.dart): `lib/core/emulator/retroarch_core_list.dart`

### Saves and sync

- [Save synchronization](https://github.com/abduznik/freegosy/blob/main/lib/core/save/save_sync_service.dart): `lib/core/save/save_sync_service.dart`
- [Save backups](https://github.com/abduznik/freegosy/blob/main/lib/core/save/backup_service.dart): `lib/core/save/backup_service.dart`
- [Background sync queue](https://github.com/abduznik/freegosy/blob/main/lib/core/save/background_sync_queue.dart): `lib/core/save/background_sync_queue.dart`
- [Play session tracking](https://github.com/abduznik/freegosy/blob/main/lib/core/romm/activity_session_tracker.dart): `lib/core/romm/activity_session_tracker.dart`

### Platform features

- [Headless commands](https://github.com/abduznik/freegosy/blob/main/lib/main_cli.dart): `lib/main_cli.dart`
- [Controller input](https://github.com/abduznik/freegosy/blob/main/lib/core/input/gamepad_service.dart): `lib/core/input/gamepad_service.dart`
- [RetroAchievements](https://github.com/abduznik/freegosy/blob/main/lib/core/retroachievements/retroachievements_service.dart): `lib/core/retroachievements/retroachievements_service.dart`

### Other components

- **Player**
- **RomM server**

## Connections

- Player → Flutter app: uses
- App entry → Flutter app: starts
- Flutter app → Game library UI: presents
- Flutter app → Game details UI: presents
- Flutter app → Settings UI: presents
- Flutter app → Download UI: presents
- Game library UI → App state providers: reads state
- Game details UI → App state providers: reads state
- Download UI → App state providers: reads state
- App state providers → RomM provider: delegates
- RomM provider → RomM client: requests
- RomM client → RomM server: fetches library
- RomM client → Metadata cache: caches metadata
- Download UI → ROM downloader: requests download
- ROM downloader → RomM server: downloads ROM
- Game details UI → Game launcher: requests launch
- Game launcher → Emulator strategies: selects strategy
- Settings UI → Emulator management: manages emulators
- Settings UI → BIOS and firmware: manages BIOS
- Settings UI → RetroArch cores: configures cores
- Game launcher → Save synchronization: runs save pipeline
- Save synchronization → Save backups: creates backups
- Save synchronization → RomM client: syncs saves
- Save synchronization → Background sync queue: queues offline work
- Game launcher → Play session tracking: records sessions
- Player → Headless commands: runs commands
- Headless commands → RomM client: uses account
- Headless commands → ROM downloader: downloads ROM
- Headless commands → Game launcher: launches game
- Player → Controller input: controls games
- Game details UI → RetroAchievements: shows achievements