# antonioalvromero/ocarina-atlas architecture

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

- Interactive diagram: https://gitdiagram.com/antonioalvromero/ocarina-atlas
- Repository: https://github.com/antonioalvromero/ocarina-atlas

## Overview

Ocarina Atlas combines a browser-based Hyrule atlas and dungeon tracker with Windows/Linux desktop launchers. Players browse places, inspect map items, record progress, and optionally synchronize collectible telemetry from supported games or across LAN devices. The launcher starts the local map service; the browser routes into atlas views backed by game data and persistent state. The README documents several telemetry integrations and launcher behaviors beyond the sampled implementation, so those connections are shown as documented or unverified where appropriate.

Main entry points: [`src/components/PlaceView.tsx`](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/components/PlaceView.tsx) (Place view), [`src/lib/data.ts`](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/data.ts) (Game dataset), [`launcher/win/MainForm.cs`](https://github.com/antonioalvromero/ocarina-atlas/blob/main/launcher/win/MainForm.cs) (Windows launcher), [`src/routes/$zone.tsx`](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/routes/%24zone.tsx) (Atlas routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launchers["Desktop launchers"]
  node_winapp["Windows launcher<br/>[MainForm.cs]"]
  node_entry["Windows entry<br/>[OcarinaAtlas.cs]"]
  node_linuxapp["Linux launcher<br/>[main.cjs]"]
end

subgraph group_atlas["Atlas experience"]
  node_mapserver["Map server<br/>[lichii-server.ts]"]
  node_routes["Atlas routes<br/>[$zone.tsx]"]
  node_placeview["Place view<br/>[PlaceView.tsx]"]
  node_worldmap["World map<br/>[WorldMap.tsx]"]
  node_viewport["Map viewport<br/>[MapViewport.tsx]"]
  node_panels["Atlas panels<br/>[Panels.tsx]"]
  node_search["Quick search"]
  node_trackerpanel["Tracker panel"]
end

subgraph group_domain["Game data and progress"]
  node_dataset["Game dataset<br/>[data.ts]"]
  node_adapter["Game adapter<br/>[game-adapter.ts]"]
  node_searchlib["Atlas search<br/>[search.ts]"]
  node_requirements["Prerequisites<br/>[prerequisites.ts]"]
  node_locale["Localization<br/>[i18n.ts]"]
  node_locales["Locale bundles<br/>[types.ts]"]
end

subgraph group_telemetry["Live telemetry"]
  node_tracker["Telemetry tracker"]
  node_telemetryserver["Telemetry server<br/>[lichii-server.ts]"]
  node_rpc["RPC client<br/>[rpc-client.ts]"]
  node_saveparser["Save parser<br/>[save-parser.ts]"]
end

subgraph group_sync["Persistence and sync"]
  node_storage[("Progress storage<br/>[storage.ts]")]
  node_syncserver["LAN sync server<br/>[sync-server.ts]"]
end

node_player(("Player"))
node_game(("Game or emulator"))
node_seconddevice(("Second-screen device"))

node_player -->|"starts map"| node_winapp
node_winapp -->|"runs"| node_entry
node_winapp -.->|"starts server"| node_mapserver
node_player -->|"starts map"| node_linuxapp
node_linuxapp -.->|"starts server"| node_mapserver
node_player -->|"opens place"| node_routes
node_routes -->|"renders"| node_placeview
node_routes -->|"finds place"| node_dataset
node_player -.->|"browses atlas"| node_worldmap
node_placeview -->|"renders"| node_viewport
node_placeview -->|"renders"| node_panels
node_placeview -->|"renders"| node_trackerpanel
node_placeview -->|"reads places"| node_dataset
node_placeview -->|"reads and writes"| node_storage
node_player -.->|"searches atlas"| node_search
node_search -->|"queries"| node_searchlib
node_searchlib -->|"searches data"| node_dataset
node_dataset -->|"uses"| node_adapter
node_panels -->|"checks prerequisites"| node_requirements
node_placeview -->|"translates view"| node_locale
node_locale -->|"loads locale types"| node_locales
node_game -.->|"serves telemetry"| node_rpc
node_telemetryserver -.->|"requests telemetry"| node_rpc
node_telemetryserver -.->|"parses saves"| node_saveparser
node_tracker -->|"records progress"| node_storage
node_trackerpanel -->|"shows status"| node_tracker
node_storage -.->|"syncs state"| node_syncserver
node_seconddevice -->|"opens LAN map"| node_mapserver

click node_winapp "https://github.com/antonioalvromero/ocarina-atlas/blob/main/launcher/win/MainForm.cs"
click node_entry "https://github.com/antonioalvromero/ocarina-atlas/blob/main/launcher/OcarinaAtlas.cs"
click node_linuxapp "https://github.com/antonioalvromero/ocarina-atlas/blob/main/launcher/linux-appimage/main.cjs"
click node_mapserver "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/lichii-server.ts"
click node_routes "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/routes/%24zone.tsx"
click node_placeview "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/components/PlaceView.tsx"
click node_worldmap "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/components/WorldMap.tsx"
click node_viewport "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/components/MapViewport.tsx"
click node_panels "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/components/Panels.tsx"
click node_search "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/components/QuickSearchModal.tsx"
click node_trackerpanel "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/components/LichiiStatusPanel.tsx"
click node_dataset "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/data.ts"
click node_adapter "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/game-adapter.ts"
click node_searchlib "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/search.ts"
click node_requirements "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/prerequisites.ts"
click node_locale "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/i18n.ts"
click node_tracker "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/useLichiiTracker.ts"
click node_telemetryserver "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/lichii-server.ts"
click node_rpc "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/lichii/rpc-client.ts"
click node_saveparser "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/lichii/save-parser.ts"
click node_storage "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/storage.ts"
click node_syncserver "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/sync-server.ts"
click node_locales "https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/i18n/types.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_winapp,node_entry,node_linuxapp,node_seconddevice toneBlue
class node_mapserver,node_routes,node_placeview,node_worldmap,node_viewport,node_panels,node_search,node_trackerpanel toneAmber
class node_dataset,node_adapter,node_searchlib,node_requirements,node_locale,node_locales toneMint
class node_tracker,node_telemetryserver,node_rpc,node_saveparser toneRose
class node_storage,node_syncserver,node_player,node_game toneIndigo
```

## Components

### Desktop launchers

- [Windows launcher](https://github.com/antonioalvromero/ocarina-atlas/blob/main/launcher/win/MainForm.cs): `launcher/win/MainForm.cs`
- [Windows entry](https://github.com/antonioalvromero/ocarina-atlas/blob/main/launcher/OcarinaAtlas.cs): `launcher/OcarinaAtlas.cs`
- [Linux launcher](https://github.com/antonioalvromero/ocarina-atlas/blob/main/launcher/linux-appimage/main.cjs): `launcher/linux-appimage/main.cjs`

### Atlas experience

- [Map server](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/lichii-server.ts): `src/lib/lichii-server.ts`
- [Atlas routes](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/routes/%24zone.tsx): `src/routes/$zone.tsx`
- [Place view](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/components/PlaceView.tsx): `src/components/PlaceView.tsx`
- [World map](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/components/WorldMap.tsx): `src/components/WorldMap.tsx`
- [Map viewport](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/components/MapViewport.tsx): `src/components/MapViewport.tsx`
- [Atlas panels](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/components/Panels.tsx): `src/components/Panels.tsx`
- [Quick search](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/components/QuickSearchModal.tsx): `src/components/QuickSearchModal.tsx`
- [Tracker panel](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/components/LichiiStatusPanel.tsx): `src/components/LichiiStatusPanel.tsx`

### Game data and progress

- [Game dataset](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/data.ts): `src/lib/data.ts`
- [Game adapter](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/game-adapter.ts): `src/lib/game-adapter.ts`
- [Atlas search](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/search.ts): `src/lib/search.ts`
- [Prerequisites](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/prerequisites.ts): `src/lib/prerequisites.ts`
- [Localization](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/i18n.ts): `src/lib/i18n.ts`
- [Locale bundles](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/i18n/types.ts): `src/lib/i18n/types.ts`

### Live telemetry

- [Telemetry tracker](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/useLichiiTracker.ts): `src/lib/useLichiiTracker.ts`
- [Telemetry server](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/lichii-server.ts): `src/lib/lichii-server.ts`
- [RPC client](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/lichii/rpc-client.ts): `src/lib/lichii/rpc-client.ts`
- [Save parser](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/lichii/save-parser.ts): `src/lib/lichii/save-parser.ts`

### Persistence and sync

- [Progress storage](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/storage.ts): `src/lib/storage.ts`
- [LAN sync server](https://github.com/antonioalvromero/ocarina-atlas/blob/main/src/lib/sync-server.ts): `src/lib/sync-server.ts`

### Other components

- **Player**
- **Game or emulator**
- **Second-screen device**

## Connections

- Player → Windows launcher: starts map
- Windows launcher → Windows entry: runs (evidence: `launcher/OcarinaAtlas.cs`)
- Windows launcher → Map server: starts server
- Player → Linux launcher: starts map
- Linux launcher → Map server: starts server
- Player → Atlas routes: opens place
- Atlas routes → Place view: renders (evidence: `src/routes/$zone.tsx`)
- Atlas routes → Game dataset: finds place (evidence: `src/routes/$zone.tsx`)
- Player → World map: browses atlas
- Place view → Map viewport: renders (evidence: `src/components/PlaceView.tsx`)
- Place view → Atlas panels: renders (evidence: `src/components/PlaceView.tsx`)
- Place view → Tracker panel: renders (evidence: `src/components/PlaceView.tsx`)
- Place view → Game dataset: reads places (evidence: `src/components/PlaceView.tsx`)
- Place view → Progress storage: reads and writes (evidence: `src/components/PlaceView.tsx`)
- Player → Quick search: searches atlas
- Quick search → Atlas search: queries (evidence: `src/components/QuickSearchModal.tsx`)
- Atlas search → Game dataset: searches data (evidence: `src/lib/search.ts`)
- Game dataset → Game adapter: uses (evidence: `src/lib/data.ts`)
- Atlas panels → Prerequisites: checks prerequisites (evidence: `src/components/Panels.tsx`)
- Place view → Localization: translates view (evidence: `src/components/PlaceView.tsx`)
- Localization → Locale bundles: loads locale types (evidence: `src/lib/i18n.ts`)
- Game or emulator → RPC client: serves telemetry
- Telemetry server → RPC client: requests telemetry
- Telemetry server → Save parser: parses saves
- Telemetry tracker → Progress storage: records progress (evidence: `src/lib/useLichiiTracker.ts`)
- Tracker panel → Telemetry tracker: shows status (evidence: `src/components/LichiiStatusPanel.tsx`)
- Progress storage → LAN sync server: syncs state
- Second-screen device → Map server: opens LAN map
