# marcialc/pocket-cloud architecture

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

- Interactive diagram: https://gitdiagram.com/marcialc/pocket-cloud
- Repository: https://github.com/marcialc/pocket-cloud

## Overview

Pocket Cloud is a browser-based Game Boy/Game Boy Color emulator with local-first saves and optional account-backed cloud features. The main workflow is selecting a ROM, resolving its save, running it through an emulator adapter, then persisting SRAM locally and optionally syncing it. The graph also includes controls, library organization, email sign-in, cloud ROM storage, and social features. Connections are based on the README and SOURCE INDEX references; unsampled implementation details are not inferred beyond those documented relationships.

Main entry points: [`src/client/App.tsx`](https://github.com/marcialc/pocket-cloud/blob/main/src/client/App.tsx) (App workflow), [`src/worker/index.ts`](https://github.com/marcialc/pocket-cloud/blob/main/src/worker/index.ts) (API router), [`src/client/components/RomPicker.tsx`](https://github.com/marcialc/pocket-cloud/blob/main/src/client/components/RomPicker.tsx) (ROM library UI), [`src/client/components/GameScreen.tsx`](https://github.com/marcialc/pocket-cloud/blob/main/src/client/components/GameScreen.tsx) (Game screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Play experience"]
  node_app["App workflow<br/>[App.tsx]"]
  node_rompicker["ROM library UI<br/>[RomPicker.tsx]"]
  node_game["Game screen<br/>[GameScreen.tsx]"]
  node_controls["Controls UI<br/>[ControlsPanel.tsx]"]
  node_emulatorfactory["Emulator selection<br/>[createEmulator.ts]"]
  node_emulatorinterface["Emulator interface<br/>[Emulator.ts]"]
  node_binjgb["binjgb adapter<br/>[BinjgbEmulator.ts]"]
  node_nostalgist["Nostalgist adapter"]
end

subgraph group_persistence["Library and saves"]
  node_preferences["Device preferences<br/>[preferences.ts]"]
  node_localdb[("IndexedDB library and saves<br/>[localSaves.ts]")]
  node_savesync["Save sync coordinator<br/>[SaveSync.ts]"]
  node_syncrules["Save conflict rules<br/>[sync.ts]"]
  node_cloudapi["Cloud save API client<br/>[cloudApi.ts]"]
  node_shelf["Library organization<br/>[shelf.ts]"]
end

subgraph group_account["Account and social"]
  node_authui["Sign-in client<br/>[authApi.ts]"]
  node_identity["Anonymous identity<br/>[identity.ts]"]
  node_socialui["Friends and social UI<br/>[FriendsPanel.tsx]"]
  node_socialclient["Social API client<br/>[socialApi.ts]"]
end

subgraph group_backend["Worker services"]
  node_worker["API router<br/>[index.ts]"]
  node_authroutes["Authentication routes<br/>[routes.ts]"]
  node_authdo[("Auth durable object<br/>[AuthDO.ts]")]
  node_playerdo[("Player save object<br/>[PlayerSaveDO.ts]")]
  node_romservice["Cloud ROM service<br/>[roms.ts]"]
  node_socialservice["Social service<br/>[social.ts]"]
  node_socialdo[("Social durable object<br/>[SocialDO.ts]")]
end

subgraph group_contracts["Shared contracts"]
  node_platforms["Platform registry<br/>[platforms.ts]"]
  node_romidentity["ROM detection and hash<br/>[rom.ts]"]
  node_wiretypes["API wire types<br/>[api.ts]"]
  node_authcontracts["Auth contracts<br/>[auth.ts]"]
  node_socialcontracts["Social contracts<br/>[social.ts]"]
end

node_player(("Player"))
node_r2[("Cloudflare R2")]
node_emailservice["Email delivery"]

node_player -->|"selects ROM"| node_rompicker
node_rompicker -->|"starts launch"| node_app
node_app -->|"loads library and saves"| node_localdb
node_app -->|"resolves cloud save"| node_savesync
node_app -->|"opens play stage"| node_game
node_game -->|"creates emulator"| node_emulatorfactory
node_emulatorfactory -.->|"returns emulator"| node_emulatorinterface
node_emulatorinterface -->|"implemented by"| node_binjgb
node_emulatorinterface -->|"implemented by"| node_nostalgist
node_emulatorfactory -->|"selects platform core"| node_platforms
node_rompicker -->|"uses ROM hash"| node_romidentity
node_game -->|"uses ROM metadata"| node_romidentity
node_controls -->|"stores bindings"| node_preferences
node_game -->|"reads play settings"| node_preferences
node_game -->|"coordinates save sync"| node_savesync
node_savesync -->|"persists local save"| node_localdb
node_savesync -->|"decides save action"| node_syncrules
node_savesync -->|"fetches and pushes saves"| node_cloudapi
node_rompicker -->|"uses ROM library"| node_localdb
node_rompicker -->|"organizes games"| node_shelf
node_app -->|"syncs library groups"| node_shelf
node_cloudapi -->|"calls save API"| node_worker
node_authui -->|"sends player key"| node_identity
node_app -->|"checks account"| node_authui
node_player -->|"opens friends"| node_socialui
node_socialui -->|"requests social data"| node_socialclient
node_socialclient -.->|"calls social API"| node_worker
node_worker -->|"routes auth requests"| node_authroutes
node_worker -->|"routes ROM requests"| node_romservice
node_worker -->|"routes social requests"| node_socialservice
node_authroutes -->|"issues and verifies codes"| node_authdo
node_authroutes -->|"authorizes session"| node_playerdo
node_authroutes -->|"sends sign-in code"| node_emailservice
node_worker -->|"routes save operations"| node_playerdo
node_romservice -->|"stores cloud ROMs"| node_r2
node_socialservice -->|"dispatches social operations"| node_socialdo
node_cloudapi -->|"uses wire contracts"| node_wiretypes
node_authroutes -->|"uses auth contracts"| node_authcontracts
node_socialservice -->|"uses social contracts"| node_socialcontracts
node_romidentity -->|"detects platform"| node_platforms

click node_app "https://github.com/marcialc/pocket-cloud/blob/main/src/client/App.tsx"
click node_rompicker "https://github.com/marcialc/pocket-cloud/blob/main/src/client/components/RomPicker.tsx"
click node_game "https://github.com/marcialc/pocket-cloud/blob/main/src/client/components/GameScreen.tsx"
click node_controls "https://github.com/marcialc/pocket-cloud/blob/main/src/client/components/ControlsPanel.tsx"
click node_emulatorfactory "https://github.com/marcialc/pocket-cloud/blob/main/src/client/emulator/createEmulator.ts"
click node_emulatorinterface "https://github.com/marcialc/pocket-cloud/blob/main/src/client/emulator/Emulator.ts"
click node_binjgb "https://github.com/marcialc/pocket-cloud/blob/main/src/client/emulator/BinjgbEmulator.ts"
click node_nostalgist "https://github.com/marcialc/pocket-cloud/blob/main/src/client/emulator/NostalgistEmulator.ts"
click node_platforms "https://github.com/marcialc/pocket-cloud/blob/main/src/shared/platforms.ts"
click node_romidentity "https://github.com/marcialc/pocket-cloud/blob/main/src/client/emulator/rom.ts"
click node_preferences "https://github.com/marcialc/pocket-cloud/blob/main/src/client/preferences.ts"
click node_localdb "https://github.com/marcialc/pocket-cloud/blob/main/src/client/saves/localSaves.ts"
click node_savesync "https://github.com/marcialc/pocket-cloud/blob/main/src/client/saves/SaveSync.ts"
click node_syncrules "https://github.com/marcialc/pocket-cloud/blob/main/src/client/saves/sync.ts"
click node_cloudapi "https://github.com/marcialc/pocket-cloud/blob/main/src/client/saves/cloudApi.ts"
click node_shelf "https://github.com/marcialc/pocket-cloud/blob/main/src/shared/shelf.ts"
click node_authui "https://github.com/marcialc/pocket-cloud/blob/main/src/client/saves/authApi.ts"
click node_identity "https://github.com/marcialc/pocket-cloud/blob/main/src/client/saves/identity.ts"
click node_socialui "https://github.com/marcialc/pocket-cloud/blob/main/src/client/components/FriendsPanel.tsx"
click node_socialclient "https://github.com/marcialc/pocket-cloud/blob/main/src/client/saves/socialApi.ts"
click node_worker "https://github.com/marcialc/pocket-cloud/blob/main/src/worker/index.ts"
click node_authroutes "https://github.com/marcialc/pocket-cloud/blob/main/src/worker/auth/routes.ts"
click node_authdo "https://github.com/marcialc/pocket-cloud/blob/main/src/worker/durable-objects/AuthDO.ts"
click node_playerdo "https://github.com/marcialc/pocket-cloud/blob/main/src/worker/durable-objects/PlayerSaveDO.ts"
click node_romservice "https://github.com/marcialc/pocket-cloud/blob/main/src/worker/roms.ts"
click node_socialservice "https://github.com/marcialc/pocket-cloud/blob/main/src/worker/social.ts"
click node_socialdo "https://github.com/marcialc/pocket-cloud/blob/main/src/worker/durable-objects/SocialDO.ts"
click node_wiretypes "https://github.com/marcialc/pocket-cloud/blob/main/src/shared/api.ts"
click node_authcontracts "https://github.com/marcialc/pocket-cloud/blob/main/src/shared/auth.ts"
click node_socialcontracts "https://github.com/marcialc/pocket-cloud/blob/main/src/shared/social.ts"

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_rompicker,node_game,node_controls,node_emulatorfactory,node_emulatorinterface,node_binjgb,node_nostalgist toneBlue
class node_preferences,node_localdb,node_savesync,node_syncrules,node_cloudapi,node_shelf,node_r2 toneAmber
class node_authui,node_identity,node_socialui,node_socialclient toneMint
class node_worker,node_authroutes,node_authdo,node_playerdo,node_romservice,node_socialservice,node_socialdo toneRose
class node_platforms,node_romidentity,node_wiretypes,node_authcontracts,node_socialcontracts,node_player,node_emailservice toneIndigo
```

## Components

### Play experience

- [App workflow](https://github.com/marcialc/pocket-cloud/blob/main/src/client/App.tsx): `src/client/App.tsx`
- [ROM library UI](https://github.com/marcialc/pocket-cloud/blob/main/src/client/components/RomPicker.tsx): `src/client/components/RomPicker.tsx`
- [Game screen](https://github.com/marcialc/pocket-cloud/blob/main/src/client/components/GameScreen.tsx): `src/client/components/GameScreen.tsx`
- [Controls UI](https://github.com/marcialc/pocket-cloud/blob/main/src/client/components/ControlsPanel.tsx): `src/client/components/ControlsPanel.tsx`
- [Emulator selection](https://github.com/marcialc/pocket-cloud/blob/main/src/client/emulator/createEmulator.ts): `src/client/emulator/createEmulator.ts`
- [Emulator interface](https://github.com/marcialc/pocket-cloud/blob/main/src/client/emulator/Emulator.ts): `src/client/emulator/Emulator.ts`
- [binjgb adapter](https://github.com/marcialc/pocket-cloud/blob/main/src/client/emulator/BinjgbEmulator.ts): `src/client/emulator/BinjgbEmulator.ts`
- [Nostalgist adapter](https://github.com/marcialc/pocket-cloud/blob/main/src/client/emulator/NostalgistEmulator.ts): `src/client/emulator/NostalgistEmulator.ts`

### Library and saves

- [Device preferences](https://github.com/marcialc/pocket-cloud/blob/main/src/client/preferences.ts): `src/client/preferences.ts`
- [IndexedDB library and saves](https://github.com/marcialc/pocket-cloud/blob/main/src/client/saves/localSaves.ts): `src/client/saves/localSaves.ts`
- [Save sync coordinator](https://github.com/marcialc/pocket-cloud/blob/main/src/client/saves/SaveSync.ts): `src/client/saves/SaveSync.ts`
- [Save conflict rules](https://github.com/marcialc/pocket-cloud/blob/main/src/client/saves/sync.ts): `src/client/saves/sync.ts`
- [Cloud save API client](https://github.com/marcialc/pocket-cloud/blob/main/src/client/saves/cloudApi.ts): `src/client/saves/cloudApi.ts`
- [Library organization](https://github.com/marcialc/pocket-cloud/blob/main/src/shared/shelf.ts): `src/shared/shelf.ts`

### Account and social

- [Sign-in client](https://github.com/marcialc/pocket-cloud/blob/main/src/client/saves/authApi.ts): `src/client/saves/authApi.ts`
- [Anonymous identity](https://github.com/marcialc/pocket-cloud/blob/main/src/client/saves/identity.ts): `src/client/saves/identity.ts`
- [Friends and social UI](https://github.com/marcialc/pocket-cloud/blob/main/src/client/components/FriendsPanel.tsx): `src/client/components/FriendsPanel.tsx`
- [Social API client](https://github.com/marcialc/pocket-cloud/blob/main/src/client/saves/socialApi.ts): `src/client/saves/socialApi.ts`

### Worker services

- [API router](https://github.com/marcialc/pocket-cloud/blob/main/src/worker/index.ts): `src/worker/index.ts`
- [Authentication routes](https://github.com/marcialc/pocket-cloud/blob/main/src/worker/auth/routes.ts): `src/worker/auth/routes.ts`
- [Auth durable object](https://github.com/marcialc/pocket-cloud/blob/main/src/worker/durable-objects/AuthDO.ts): `src/worker/durable-objects/AuthDO.ts`
- [Player save object](https://github.com/marcialc/pocket-cloud/blob/main/src/worker/durable-objects/PlayerSaveDO.ts): `src/worker/durable-objects/PlayerSaveDO.ts`
- [Cloud ROM service](https://github.com/marcialc/pocket-cloud/blob/main/src/worker/roms.ts): `src/worker/roms.ts`
- [Social service](https://github.com/marcialc/pocket-cloud/blob/main/src/worker/social.ts): `src/worker/social.ts`
- [Social durable object](https://github.com/marcialc/pocket-cloud/blob/main/src/worker/durable-objects/SocialDO.ts): `src/worker/durable-objects/SocialDO.ts`

### Shared contracts

- [Platform registry](https://github.com/marcialc/pocket-cloud/blob/main/src/shared/platforms.ts): `src/shared/platforms.ts`
- [ROM detection and hash](https://github.com/marcialc/pocket-cloud/blob/main/src/client/emulator/rom.ts): `src/client/emulator/rom.ts`
- [API wire types](https://github.com/marcialc/pocket-cloud/blob/main/src/shared/api.ts): `src/shared/api.ts`
- [Auth contracts](https://github.com/marcialc/pocket-cloud/blob/main/src/shared/auth.ts): `src/shared/auth.ts`
- [Social contracts](https://github.com/marcialc/pocket-cloud/blob/main/src/shared/social.ts): `src/shared/social.ts`

### Other components

- **Player**
- **Cloudflare R2**
- **Email delivery**

## Connections

- Player → ROM library UI: selects ROM
- ROM library UI → App workflow: starts launch (evidence: `src/client/App.tsx`)
- App workflow → IndexedDB library and saves: loads library and saves (evidence: `src/client/App.tsx`)
- App workflow → Save sync coordinator: resolves cloud save (evidence: `src/client/App.tsx`)
- App workflow → Game screen: opens play stage (evidence: `src/client/App.tsx`)
- Game screen → Emulator selection: creates emulator (evidence: `src/client/components/GameScreen.tsx`)
- Emulator selection → Emulator interface: returns emulator
- Emulator interface → binjgb adapter: implemented by (evidence: `src/client/emulator/BinjgbEmulator.ts`)
- Emulator interface → Nostalgist adapter: implemented by (evidence: `src/client/emulator/NostalgistEmulator.ts`)
- Emulator selection → Platform registry: selects platform core
- ROM library UI → ROM detection and hash: uses ROM hash (evidence: `src/client/components/RomPicker.tsx`)
- Game screen → ROM detection and hash: uses ROM metadata (evidence: `src/client/components/GameScreen.tsx`)
- Controls UI → Device preferences: stores bindings (evidence: `src/client/preferences.ts`)
- Game screen → Device preferences: reads play settings (evidence: `src/client/components/GameScreen.tsx`)
- Game screen → Save sync coordinator: coordinates save sync (evidence: `src/client/components/GameScreen.tsx`)
- Save sync coordinator → IndexedDB library and saves: persists local save (evidence: `src/client/saves/SaveSync.ts`)
- Save sync coordinator → Save conflict rules: decides save action (evidence: `src/client/saves/SaveSync.ts`)
- Save sync coordinator → Cloud save API client: fetches and pushes saves (evidence: `src/client/saves/SaveSync.ts`)
- ROM library UI → IndexedDB library and saves: uses ROM library (evidence: `src/client/components/RomPicker.tsx`)
- ROM library UI → Library organization: organizes games (evidence: `src/client/components/RomPicker.tsx`)
- App workflow → Library organization: syncs library groups (evidence: `src/client/App.tsx`)
- Cloud save API client → API router: calls save API
- Sign-in client → Anonymous identity: sends player key (evidence: `src/client/saves/authApi.ts`)
- App workflow → Sign-in client: checks account (evidence: `src/client/App.tsx`)
- Player → Friends and social UI: opens friends
- Friends and social UI → Social API client: requests social data (evidence: `src/client/components/FriendsPanel.tsx`)
- Social API client → API router: calls social API
- API router → Authentication routes: routes auth requests (evidence: `src/worker/index.ts`)
- API router → Cloud ROM service: routes ROM requests (evidence: `src/worker/index.ts`)
- API router → Social service: routes social requests (evidence: `src/worker/index.ts`)
- Authentication routes → Auth durable object: issues and verifies codes (evidence: `src/worker/auth/routes.ts`)
- Authentication routes → Player save object: authorizes session (evidence: `src/worker/auth/routes.ts`)
- Authentication routes → Email delivery: sends sign-in code (evidence: `src/worker/auth/routes.ts`)
- API router → Player save object: routes save operations (evidence: `src/worker/index.ts`)
- Cloud ROM service → Cloudflare R2: stores cloud ROMs
- Social service → Social durable object: dispatches social operations (evidence: `src/worker/social.ts`)
- Cloud save API client → API wire types: uses wire contracts (evidence: `src/client/saves/cloudApi.ts`)
- Authentication routes → Auth contracts: uses auth contracts (evidence: `src/worker/auth/routes.ts`)
- Social service → Social contracts: uses social contracts (evidence: `src/worker/social.ts`)
- ROM detection and hash → Platform registry: detects platform (evidence: `src/client/emulator/rom.ts`)