# lidarbtc/hayeon-os architecture

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

- Interactive diagram: https://gitdiagram.com/lidarbtc/hayeon-os
- Repository: https://github.com/lidarbtc/hayeon-os

## Overview

HaYeon OS is a bilingual, Windows XP/7-inspired web desktop for a HaYeon fan community. Visitors boot into a welcome screen, log in to the desktop, then launch windows and use built-in apps for files, photos, music, games, profiles, and a guestbook. The map includes the desktop lifecycle, window management, app registration, and the main domain services. Edges are limited to relationships visible in excerpts or SOURCE INDEX references; unsampled implementations and their internal behavior are not inferred.

Main entry points: [`src/App.svelte`](https://github.com/lidarbtc/hayeon-os/blob/main/src/App.svelte) (App entry), [`src/lib/apps/Explorer.svelte`](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/apps/Explorer.svelte) (File explorer), [`src/lib/apps/Terminal.svelte`](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/apps/Terminal.svelte) (Terminal), [`src/lib/os/apps.ts`](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/apps.ts) (App registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["Desktop lifecycle"]
  node_app["App entry<br/>[App.svelte]"]
  node_session["Session state<br/>[session.svelte.ts]"]
  node_boot["Boot screen<br/>[Boot.svelte]"]
  node_welcome["Welcome screen<br/>[Welcome.svelte]"]
  node_leaving["Leaving screen<br/>[Leaving.svelte]"]
  node_off["Power-off screen<br/>[Off.svelte]"]
end

subgraph group_desktop["Desktop shell"]
  node_desktop["Desktop shell<br/>[Desktop.svelte]"]
  node_window["Window manager<br/>[wm.svelte.ts]"]
  node_registry["App registry<br/>[registry.ts]"]
  node_appdefs["App registration<br/>[apps.ts]"]
  node_icon["Icon renderer<br/>[Icon.svelte]"]
  node_menubar["Menu bar<br/>[MenuBar.svelte]"]
end

subgraph group_apps["Built-in apps"]
  node_explorer["File explorer<br/>[Explorer.svelte]"]
  node_notepad["Notepad<br/>[Notepad.svelte]"]
  node_terminal["Terminal<br/>[Terminal.svelte]"]
  node_otherapps["Other desktop apps"]
  node_hog["Hedgehog game logic<br/>[hog.ts]"]
end

subgraph group_services["OS services"]
  node_disk["Disk model<br/>[disk.ts]"]
  node_filesystem[("User filesystem<br/>[fs.svelte.ts]")]
  node_shellsvc["Shell shortcuts<br/>[shell.ts]"]
  node_settings["User settings<br/>[settings.svelte.ts]"]
  node_i18n["Localization<br/>[i18n.ts]"]
  node_pointer["Pointer state<br/>[pointer.ts]"]
  node_pack["Pack cache<br/>[pack.svelte.ts]"]
end

subgraph group_content["Media and community"]
  node_photos["Photo library<br/>[photos.svelte.ts]"]
  node_player["Media player<br/>[player.svelte.ts]"]
  node_musicengine["Music engine<br/>[synth.ts]"]
  node_score["Music scores<br/>[score.ts]"]
  node_guestbook["Guestbook service"]
  node_nostr["Nostr integration<br/>[nostr.ts]"]
end

node_visitor(("Visitor"))

node_visitor -->|"opens"| node_app
node_app -->|"reads phase"| node_session
node_app -->|"renders"| node_boot
node_app -->|"renders"| node_welcome
node_app -->|"renders"| node_desktop
node_app -->|"renders"| node_leaving
node_app -->|"renders"| node_off
node_welcome -->|"logs in"| node_session
node_session -->|"requests closes"| node_window
node_appdefs -->|"registers apps"| node_registry
node_window -->|"looks up apps"| node_registry
node_appdefs -->|"registers"| node_explorer
node_appdefs -->|"registers"| node_notepad
node_appdefs -->|"registers"| node_terminal
node_appdefs -->|"registers"| node_otherapps
node_explorer -->|"reads"| node_disk
node_explorer -->|"reads"| node_filesystem
node_notepad -->|"reads and writes"| node_filesystem
node_terminal -->|"reads"| node_disk
node_terminal -->|"reads"| node_filesystem
node_terminal -->|"reads"| node_settings
node_terminal -->|"uses shortcuts"| node_shellsvc
node_terminal -->|"closes window"| node_window
node_shellsvc -->|"checks files"| node_filesystem
node_shellsvc -->|"opens apps"| node_window
node_explorer -->|"uses pointer state"| node_pointer
node_notepad -->|"uses pointer state"| node_pointer
node_player -->|"uses"| node_musicengine
node_player -->|"loads scores"| node_score
node_musicengine -->|"reads"| node_score
node_guestbook -->|"uses"| node_nostr
node_settings -->|"uses photo data"| node_photos
node_boot -->|"starts pack"| node_pack
node_explorer -->|"renders icons"| node_icon
node_explorer -.->|"renders menu"| node_menubar
node_otherapps -.->|"game logic"| node_hog
node_otherapps -.->|"photo features"| node_photos
node_otherapps -.->|"guestbook UI"| node_guestbook
node_otherapps -.->|"music UI"| node_player

click node_app "https://github.com/lidarbtc/hayeon-os/blob/main/src/App.svelte"
click node_session "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/session.svelte.ts"
click node_boot "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/screens/Boot.svelte"
click node_welcome "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/screens/Welcome.svelte"
click node_leaving "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/screens/Leaving.svelte"
click node_off "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/screens/Off.svelte"
click node_desktop "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/shell/Desktop.svelte"
click node_window "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/wm.svelte.ts"
click node_registry "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/registry.ts"
click node_appdefs "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/apps.ts"
click node_explorer "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/apps/Explorer.svelte"
click node_notepad "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/apps/Notepad.svelte"
click node_terminal "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/apps/Terminal.svelte"
click node_otherapps "https://github.com/lidarbtc/hayeon-os/tree/main/src/lib/apps"
click node_disk "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/disk.ts"
click node_filesystem "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/fs.svelte.ts"
click node_shellsvc "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/shell.ts"
click node_settings "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/settings.svelte.ts"
click node_i18n "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/i18n.ts"
click node_photos "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/photos.svelte.ts"
click node_player "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/player.svelte.ts"
click node_musicengine "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/synth.ts"
click node_score "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/score.ts"
click node_guestbook "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/guestbook.svelte.ts"
click node_nostr "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/nostr.ts"
click node_hog "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/hog.ts"
click node_icon "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/ui/Icon.svelte"
click node_menubar "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/ui/MenuBar.svelte"
click node_pointer "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/pointer.ts"
click node_pack "https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/pack.svelte.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_session,node_boot,node_welcome,node_leaving,node_off toneBlue
class node_desktop,node_window,node_registry,node_appdefs,node_icon,node_menubar toneAmber
class node_explorer,node_notepad,node_terminal,node_otherapps,node_hog toneMint
class node_disk,node_filesystem,node_shellsvc,node_settings,node_i18n,node_pointer,node_pack toneRose
class node_photos,node_player,node_musicengine,node_score,node_guestbook,node_nostr,node_visitor toneIndigo
```

## Components

### Desktop lifecycle

- [App entry](https://github.com/lidarbtc/hayeon-os/blob/main/src/App.svelte): `src/App.svelte`
- [Session state](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/session.svelte.ts): `src/lib/os/session.svelte.ts`
- [Boot screen](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/screens/Boot.svelte): `src/lib/screens/Boot.svelte`
- [Welcome screen](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/screens/Welcome.svelte): `src/lib/screens/Welcome.svelte`
- [Leaving screen](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/screens/Leaving.svelte): `src/lib/screens/Leaving.svelte`
- [Power-off screen](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/screens/Off.svelte): `src/lib/screens/Off.svelte`

### Desktop shell

- [Desktop shell](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/shell/Desktop.svelte): `src/lib/shell/Desktop.svelte`
- [Window manager](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/wm.svelte.ts): `src/lib/os/wm.svelte.ts`
- [App registry](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/registry.ts): `src/lib/os/registry.ts`
- [App registration](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/apps.ts): `src/lib/os/apps.ts`
- [Icon renderer](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/ui/Icon.svelte): `src/lib/ui/Icon.svelte`
- [Menu bar](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/ui/MenuBar.svelte): `src/lib/ui/MenuBar.svelte`

### Built-in apps

- [File explorer](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/apps/Explorer.svelte): `src/lib/apps/Explorer.svelte`
- [Notepad](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/apps/Notepad.svelte): `src/lib/apps/Notepad.svelte`
- [Terminal](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/apps/Terminal.svelte): `src/lib/apps/Terminal.svelte`
- [Other desktop apps](https://github.com/lidarbtc/hayeon-os/tree/main/src/lib/apps): `src/lib/apps`
- [Hedgehog game logic](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/hog.ts): `src/lib/os/hog.ts`

### OS services

- [Disk model](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/disk.ts): `src/lib/os/disk.ts`
- [User filesystem](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/fs.svelte.ts): `src/lib/os/fs.svelte.ts`
- [Shell shortcuts](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/shell.ts): `src/lib/os/shell.ts`
- [User settings](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/settings.svelte.ts): `src/lib/os/settings.svelte.ts`
- [Localization](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/i18n.ts): `src/lib/os/i18n.ts`
- [Pointer state](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/pointer.ts): `src/lib/os/pointer.ts`
- [Pack cache](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/pack.svelte.ts): `src/lib/os/pack.svelte.ts`

### Media and community

- [Photo library](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/photos.svelte.ts): `src/lib/os/photos.svelte.ts`
- [Media player](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/player.svelte.ts): `src/lib/os/player.svelte.ts`
- [Music engine](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/synth.ts): `src/lib/os/synth.ts`
- [Music scores](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/score.ts): `src/lib/os/score.ts`
- [Guestbook service](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/guestbook.svelte.ts): `src/lib/os/guestbook.svelte.ts`
- [Nostr integration](https://github.com/lidarbtc/hayeon-os/blob/main/src/lib/os/nostr.ts): `src/lib/os/nostr.ts`

### Other components

- **Visitor**

## Connections

- Visitor → App entry: opens (evidence: `README.md`)
- App entry → Session state: reads phase (evidence: `src/App.svelte`)
- App entry → Boot screen: renders (evidence: `src/App.svelte`)
- App entry → Welcome screen: renders (evidence: `src/App.svelte`)
- App entry → Desktop shell: renders (evidence: `src/App.svelte`)
- App entry → Leaving screen: renders (evidence: `src/App.svelte`)
- App entry → Power-off screen: renders (evidence: `src/App.svelte`)
- Welcome screen → Session state: logs in (evidence: `src/lib/screens/Welcome.svelte`)
- Session state → Window manager: requests closes (evidence: `src/lib/os/session.svelte.ts`)
- App registration → App registry: registers apps (evidence: `src/lib/os/apps.ts`)
- Window manager → App registry: looks up apps (evidence: `src/lib/os/wm.svelte.ts`)
- App registration → File explorer: registers (evidence: `src/lib/os/apps.ts`)
- App registration → Notepad: registers (evidence: `src/lib/os/apps.ts`)
- App registration → Terminal: registers (evidence: `src/lib/os/apps.ts`)
- App registration → Other desktop apps: registers (evidence: `src/lib/os/apps.ts`)
- File explorer → Disk model: reads (evidence: `src/lib/apps/Explorer.svelte`)
- File explorer → User filesystem: reads (evidence: `src/lib/apps/Explorer.svelte`)
- Notepad → User filesystem: reads and writes (evidence: `src/lib/apps/Notepad.svelte`)
- Terminal → Disk model: reads (evidence: `src/lib/apps/Terminal.svelte`)
- Terminal → User filesystem: reads (evidence: `src/lib/apps/Terminal.svelte`)
- Terminal → User settings: reads (evidence: `src/lib/apps/Terminal.svelte`)
- Terminal → Shell shortcuts: uses shortcuts (evidence: `src/lib/apps/Terminal.svelte`)
- Terminal → Window manager: closes window (evidence: `src/lib/apps/Terminal.svelte`)
- Shell shortcuts → User filesystem: checks files (evidence: `src/lib/os/shell.ts`)
- Shell shortcuts → Window manager: opens apps (evidence: `src/lib/os/shell.ts`)
- File explorer → Pointer state: uses pointer state (evidence: `src/lib/apps/Explorer.svelte`)
- Notepad → Pointer state: uses pointer state (evidence: `src/lib/apps/Notepad.svelte`)
- Media player → Music engine: uses (evidence: `src/lib/os/player.svelte.ts`)
- Media player → Music scores: loads scores (evidence: `src/lib/os/player.svelte.ts`)
- Music engine → Music scores: reads (evidence: `src/lib/os/synth.ts`)
- Guestbook service → Nostr integration: uses (evidence: `src/lib/os/guestbook.svelte.ts`)
- User settings → Photo library: uses photo data (evidence: `src/lib/os/settings.svelte.ts`)
- Boot screen → Pack cache: starts pack (evidence: `src/lib/screens/Boot.svelte`)
- File explorer → Icon renderer: renders icons (evidence: `src/lib/apps/Explorer.svelte`)
- File explorer → Menu bar: renders menu
- Other desktop apps → Hedgehog game logic: game logic (evidence: `src/lib/apps/HedgehogFinder.svelte`)
- Other desktop apps → Photo library: photo features
- Other desktop apps → Guestbook service: guestbook UI
- Other desktop apps → Media player: music UI (evidence: `src/lib/apps/MediaPlayer.svelte`)
