# joethun/joetemulator architecture

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

- Interactive diagram: https://gitdiagram.com/joethun/joetemulator
- Repository: https://github.com/joethun/joetemulator

## Overview

1. **Project purpose**
   - Joe T Emulator is a browser-based multi-system game emulator frontend. Its job is to let users add ROMs, organize them, fetch artwork, and launch games entirely in the browser.

2. **Primary runtime boundary**
   - The core application runs client-side in the browser. The README explicitly says ROMs and save states stay local, so the app’s main architectural boundary is between the browser UI and external asset/services, not a backend API.

3. **Emulation engine integration**
   - The emulator functionality is provided by **EmulatorJS**. This is the main execution engine for running games and supporting the wide range of systems listed in the README.

4. **Library and game management layer**
   - The app includes a game library workflow: users add one or multiple ROM files, assign a system, optionally rename entries, and then launch them from the library. This implies a catalog/index of user-imported games maintained locally in the client.

5. **Metadata and cover art flow**
   - Cover art is fetched automatically from **thumbnails.libretro.com** using hashing or, if needed, a title-based fallback. This is the main external data dependency and affects the library presentation layer rather than gameplay.

6. **User input and import paths**
   - Games can be added through a sidebar “+” action or by drag-and-drop onto the page. That makes file ingestion a key UI subsystem, with multi-file import and per-game assignment steps.

7. **Local customization**
   - Users can override artwork through a context menu and can rename games during import. This suggests per-item metadata editing stored locally alongside each ROM entry.

8. **Storage model**
   - Because the app keeps ROMs and save states in the browser, persistence is likely client-side storage rather than server-side accounts or databases. This is an important architectural constraint: the user’s library is tied to the browser/device unless exported elsewhere.

9. **Supported platform breadth**
   - The supported systems span consoles, handhelds, arcade, and computer platforms. Architecturally, that means the app is a multi-core frontend that routes each imported game to the correct EmulatorJS-supported system configuration.

10. **Deployment surface**
   - The app is hosted at a Netlify URL, which strongly suggests a static web deployment model. The hosting layer likely serves the frontend assets only, with runtime behavior remaining in the browser.

11. **No evidence of a traditional backend**
   - Nothing in the README indicates authentication, remote storage, server-side game indexing, or API-driven gameplay. For an architecture diagram, the safe assumption is: frontend app + external cover-art source + embedded emulation engine.

12. **Diagram-friendly summary**
   - The key components to draw are: browser UI for library management, local browser storage for ROMs/saves/metadata, EmulatorJS as the emulation engine, and thumbnails.libretro.com as the external artwork service, with Netlify as the static hosting entry point.

Main entry points: [`README.md`](https://github.com/joethun/joetemulator/blob/main/README.md) (Browser UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client app"]
  node_ui["Browser UI<br/>Frontend shell<br/>[README.md]"]
  node_import["Game import<br/>File ingestion"]
  node_library[("Game library<br/>Local catalog")]
  node_metadata["Artwork metadata<br/>Cover lookup"]
  node_storage[("Browser storage<br/>Local persistence")]
end

subgraph group_external["External services"]
  node_site["Static site<br/>Netlify deploy"]
  node_emulator{{"EmulatorJS<br/>Emulation engine"}}
  node_covers["Libretro thumbnails<br/>Artwork source"]
end

node_site -->|"serves"| node_ui
node_ui -->|"imports"| node_import
node_ui -->|"browses"| node_library
node_import -->|"creates entries"| node_library
node_library -->|"persists to"| node_storage
node_import -->|"stores files"| node_storage
node_library -->|"requests art"| node_metadata
node_metadata -->|"fetches from"| node_covers
node_library -->|"launches"| node_emulator
node_emulator -->|"reads/writes"| node_storage
node_ui -->|"overrides"| node_metadata

click node_ui "https://github.com/joethun/joetemulator/blob/main/README.md"

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_import,node_library,node_metadata,node_storage toneBlue
class node_site,node_emulator,node_covers toneAmber
```

## Components

### Client app

Browser-based emulator frontend and local data flow

- [Browser UI](https://github.com/joethun/joetemulator/blob/main/README.md): Frontend shell · Main in-browser interface for browsing and launching games · `README.md`
- **Game import**: File ingestion · Adds ROMs via sidebar action or drag-and-drop
- **Game library**: Local catalog · Tracks imported games, systems, and custom names
- **Artwork metadata**: Cover lookup · Resolves cover art by hash or title fallback
- **Browser storage**: Local persistence · Keeps ROMs, save states, and library data on the device

### External services

Third-party runtime and artwork sources

- **Static site**: Netlify deploy · Hosts the frontend bundle
- **EmulatorJS**: Emulation engine · Runs games for the supported systems in the browser
- **Libretro thumbnails**: Artwork source · External cover-art service used for automatic artwork fetching

## Connections

- Static site → Browser UI: serves · Static deployment delivers the browser app
- Browser UI → Game import: imports · Users add ROM files from the interface
- Browser UI → Game library: browses · Library view organizes imported games
- Game import → Game library: creates entries · Imported ROMs become local library items
- Game library → Browser storage: persists to · Game entries and local customization are stored in the browser
- Game import → Browser storage: stores files · ROMs and save-related data remain local
- Game library → Artwork metadata: requests art · Library presentation triggers artwork resolution
- Artwork metadata → Libretro thumbnails: fetches from · Uses thumbnails.libretro.com as the external cover source
- Game library → EmulatorJS: launches · Selected games are routed to the emulation engine
- EmulatorJS → Browser storage: reads/writes · Gameplay and save states use local browser persistence
- Browser UI → Artwork metadata: overrides · Context menu allows manual artwork replacement