How marcialc/pocket-cloud works
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: App.tsx App workflow · index.ts API router · RomPicker.tsx ROM library UI · GameScreen.tsx Game screen
Components 33
Play experience
- App workflow
src/client/App.tsx - ROM library UI
src/client/components/RomPicker.tsx - Game screen
src/client/components/GameScreen.tsx - Controls UI
src/client/components/ControlsPanel.tsx - Emulator selection
src/client/emulator/createEmulator.ts - Emulator interface
src/client/emulator/Emulator.ts - binjgb adapter
src/client/emulator/BinjgbEmulator.ts - Nostalgist adapter
src/client/emulator/NostalgistEmulator.ts
Library and saves
- Device preferences
src/client/preferences.ts - IndexedDB library and saves
src/client/saves/localSaves.ts - Save sync coordinator
src/client/saves/SaveSync.ts - Save conflict rules
src/client/saves/sync.ts - Cloud save API client
src/client/saves/cloudApi.ts - Library organization
src/shared/shelf.ts
Account and social
- Sign-in client
src/client/saves/authApi.ts - Anonymous identity
src/client/saves/identity.ts - Friends and social UI
src/client/components/FriendsPanel.tsx - Social API client
src/client/saves/socialApi.ts
Worker services
- API router
src/worker/index.ts - Authentication routes
src/worker/auth/routes.ts - Auth durable object
src/worker/durable-objects/AuthDO.ts - Player save object
src/worker/durable-objects/PlayerSaveDO.ts - Cloud ROM service
src/worker/roms.ts - Social service
src/worker/social.ts - Social durable object
src/worker/durable-objects/SocialDO.ts
Shared contracts
- Platform registry
src/shared/platforms.ts - ROM detection and hash
src/client/emulator/rom.ts - API wire types
src/shared/api.ts - Auth contracts
src/shared/auth.ts - Social contracts
src/shared/social.ts
Other components
- Player
- Cloudflare R2
- Email delivery
Connections 40
- Player → ROM library UI: selects ROM
- ROM library UI → App workflow: starts launch
src/client/App.tsx - App workflow → IndexedDB library and saves: loads library and saves
src/client/App.tsx - App workflow → Save sync coordinator: resolves cloud save
src/client/App.tsx - App workflow → Game screen: opens play stage
src/client/App.tsx - Game screen → Emulator selection: creates emulator
src/client/components/GameScreen.tsx - Emulator selection → Emulator interface: returns emulator
- Emulator interface → binjgb adapter: implemented by
src/client/emulator/BinjgbEmulator.ts - Emulator interface → Nostalgist adapter: implemented by
src/client/emulator/NostalgistEmulator.ts - Emulator selection → Platform registry: selects platform core
- ROM library UI → ROM detection and hash: uses ROM hash
src/client/components/RomPicker.tsx - Game screen → ROM detection and hash: uses ROM metadata
src/client/components/GameScreen.tsx - Controls UI → Device preferences: stores bindings
src/client/preferences.ts - Game screen → Device preferences: reads play settings
src/client/components/GameScreen.tsx - Game screen → Save sync coordinator: coordinates save sync
src/client/components/GameScreen.tsx - Save sync coordinator → IndexedDB library and saves: persists local save
src/client/saves/SaveSync.ts - Save sync coordinator → Save conflict rules: decides save action
src/client/saves/SaveSync.ts - Save sync coordinator → Cloud save API client: fetches and pushes saves
src/client/saves/SaveSync.ts - ROM library UI → IndexedDB library and saves: uses ROM library
src/client/components/RomPicker.tsx - ROM library UI → Library organization: organizes games
src/client/components/RomPicker.tsx - App workflow → Library organization: syncs library groups
src/client/App.tsx - Cloud save API client → API router: calls save API
- Sign-in client → Anonymous identity: sends player key
src/client/saves/authApi.ts - App workflow → Sign-in client: checks account
src/client/App.tsx - Player → Friends and social UI: opens friends
- Friends and social UI → Social API client: requests social data
src/client/components/FriendsPanel.tsx - Social API client → API router: calls social API
- API router → Authentication routes: routes auth requests
src/worker/index.ts - API router → Cloud ROM service: routes ROM requests
src/worker/index.ts - API router → Social service: routes social requests
src/worker/index.ts - Authentication routes → Auth durable object: issues and verifies codes
src/worker/auth/routes.ts - Authentication routes → Player save object: authorizes session
src/worker/auth/routes.ts - Authentication routes → Email delivery: sends sign-in code
src/worker/auth/routes.ts - API router → Player save object: routes save operations
src/worker/index.ts - Cloud ROM service → Cloudflare R2: stores cloud ROMs
- Social service → Social durable object: dispatches social operations
src/worker/social.ts - Cloud save API client → API wire types: uses wire contracts
src/client/saves/cloudApi.ts - Authentication routes → Auth contracts: uses auth contracts
src/worker/auth/routes.ts - Social service → Social contracts: uses social contracts
src/worker/social.ts - ROM detection and hash → Platform registry: detects platform
src/client/emulator/rom.ts