# xan105/achievement-watcher architecture

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

- Interactive diagram: https://gitdiagram.com/xan105/achievement-watcher
- Repository: https://github.com/xan105/achievement-watcher

## Overview

Achievement Watcher is a Windows desktop achievement viewer and parser, with companion services for achievement notifications, souvenir capture, and playtime tracking. The principal workflow is to discover local game and achievement data, obtain achievement metadata where available, and present it in the app; the watchdog adds live notifications and playtime tracking. The repository also contains a Steam-data HTTP service and an updater. Some links between the desktop parser and companion services are documented only as product capabilities, so those are marked unverified rather than treated as observed calls.

Main entry points: [`app/app.js`](https://github.com/xan105/achievement-watcher/blob/1.x/app/app.js) (App shell), [`service/watchdog/notification/toaster.js`](https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/notification/toaster.js) (Notification dispatch), [`app/parser/steam.js`](https://github.com/xan105/achievement-watcher/blob/1.x/app/parser/steam.js) (Steam and emulator parser), [`server/v2/router.js`](https://github.com/xan105/achievement-watcher/blob/1.x/server/v2/router.js) (API router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_electron["Electron window<br/>[init.js]"]
  node_app_shell["App shell<br/>[app.js]"]
  node_title_bar["Window controls<br/>[titleBar.js]"]
  node_avatar["Avatar component<br/>[avatar.js]"]
  node_settings["Settings<br/>[settings.js]"]
  node_game_ui["Game and achievement UI<br/>[game.js]"]
  node_search_sort["Search and sort<br/>[search.js]"]
  node_refresh["Refresh UI<br/>[refresh.js]"]
end

subgraph group_parsing["Achievement ingestion"]
  node_steam_parser["Steam and emulator parser<br/>[steam.js]"]
  node_other_parsers["Other source parsers"]
  node_achievement_parser["Achievement file parser<br/>[achievements.js]"]
end

subgraph group_steam["Steam data service"]
  node_server["Steam API server<br/>[server.js]"]
  node_router["API router<br/>[router.js]"]
  node_steam_routes["Steam routes<br/>[steam.js]"]
  node_legacy_route["Legacy route wrapper"]
  node_steam_api["Steam API facade<br/>[steam.js]"]
  node_product_info["Steam product info<br/>[steamClient.js]"]
end

subgraph group_watchdog["Live tracking"]
  node_watchdog["Achievement watchdog<br/>[watchdog.js]"]
  node_monitor["Achievement monitoring<br/>[monitor.js]"]
  node_notify["Notification dispatch<br/>[toaster.js]"]
  node_toast["Toast transport<br/>[toast.js]"]
  node_gntp["GNTP transport<br/>[gntp.js]"]
  node_websocket["Websocket notifications<br/>[websocket.js]"]
  node_playtime["Playtime monitor<br/>[monitor.js]"]
  node_playtime_helpers["Playtime tracking helpers<br/>[track.js]"]
  node_souvenirs["Screenshots and video<br/>[toaster.js]"]
end

subgraph group_maintenance["Updates"]
  node_updater["Application updater<br/>[updater.js]"]
end

node_user(("User"))
node_local_sources["Local game files"]
node_steam_external["Steam services"]
node_processes["Running games"]

node_user -->|"opens app"| node_electron
node_electron -->|"loads view"| node_app_shell
node_app_shell -.->|"uses parser"| node_steam_parser
node_app_shell -.->|"presents games"| node_game_ui
node_app_shell -.->|"opens settings"| node_settings
node_app_shell -->|"registers component"| node_title_bar
node_app_shell -->|"registers component"| node_avatar
node_user -->|"has game data"| node_local_sources
node_local_sources -.->|"reads files"| node_steam_parser
node_local_sources -.->|"provides source files"| node_other_parsers
node_steam_parser -.->|"parses achievements"| node_achievement_parser
node_steam_parser -.->|"fetches metadata"| node_steam_external
node_achievement_parser -.->|"supplies results"| node_game_ui
node_game_ui -.->|"supports browsing"| node_search_sort
node_user -.->|"requests data"| node_server
node_server -->|"mounts routes"| node_router
node_router -->|"mounts endpoint"| node_steam_routes
node_router -->|"mounts endpoint"| node_legacy_route
node_steam_routes -->|"calls API"| node_steam_api
node_legacy_route -->|"calls API"| node_steam_api
node_steam_api -->|"requests product info"| node_product_info
node_product_info -->|"requests Steam data"| node_steam_external
node_watchdog -.->|"monitors unlocks"| node_monitor
node_monitor -.->|"dispatches notifications"| node_notify
node_notify -->|"sends toast"| node_toast
node_notify -->|"sends GNTP"| node_gntp
node_notify -->|"dispatches websocket"| node_websocket
node_notify -->|"captures media"| node_souvenirs
node_processes -.->|"provides process events"| node_playtime
node_playtime -->|"uses tracking helpers"| node_playtime_helpers
node_user -.->|"requests update"| node_updater

click node_electron "https://github.com/xan105/achievement-watcher/blob/1.x/app/electron/init.js"
click node_app_shell "https://github.com/xan105/achievement-watcher/blob/1.x/app/app.js"
click node_title_bar "https://github.com/xan105/achievement-watcher/blob/1.x/app/components/titleBar/titleBar.js"
click node_avatar "https://github.com/xan105/achievement-watcher/blob/1.x/app/components/userAvatar/avatar.js"
click node_settings "https://github.com/xan105/achievement-watcher/blob/1.x/app/ui/settings.js"
click node_game_ui "https://github.com/xan105/achievement-watcher/blob/1.x/app/ui/game.js"
click node_search_sort "https://github.com/xan105/achievement-watcher/blob/1.x/app/ui/search.js"
click node_refresh "https://github.com/xan105/achievement-watcher/blob/1.x/app/ui/refresh.js"
click node_steam_parser "https://github.com/xan105/achievement-watcher/blob/1.x/app/parser/steam.js"
click node_other_parsers "https://github.com/xan105/achievement-watcher/tree/1.x/app/parser"
click node_achievement_parser "https://github.com/xan105/achievement-watcher/blob/1.x/app/parser/achievements.js"
click node_server "https://github.com/xan105/achievement-watcher/blob/1.x/server/v2/server.js"
click node_router "https://github.com/xan105/achievement-watcher/blob/1.x/server/v2/router.js"
click node_steam_routes "https://github.com/xan105/achievement-watcher/blob/1.x/server/v2/route/steam.js"
click node_legacy_route "https://github.com/xan105/achievement-watcher/blob/1.x/server/v2/route/legacy/steam_v1_wrapper.js"
click node_steam_api "https://github.com/xan105/achievement-watcher/blob/1.x/server/v2/api/steam/steam.js"
click node_product_info "https://github.com/xan105/achievement-watcher/blob/1.x/server/v2/api/steam/steamClient.js"
click node_watchdog "https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/watchdog.js"
click node_monitor "https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/monitor.js"
click node_notify "https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/notification/toaster.js"
click node_toast "https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/notification/transport/toast.js"
click node_gntp "https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/notification/transport/gntp.js"
click node_websocket "https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/websocket.js"
click node_playtime "https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/playtime/monitor.js"
click node_playtime_helpers "https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/playtime/track.js"
click node_souvenirs "https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/notification/toaster.js"
click node_updater "https://github.com/xan105/achievement-watcher/blob/1.x/service/updater/updater.js"

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_electron,node_app_shell,node_title_bar,node_avatar,node_settings,node_game_ui,node_search_sort,node_refresh,node_user toneBlue
class node_steam_parser,node_other_parsers,node_achievement_parser toneAmber
class node_server,node_router,node_steam_routes,node_legacy_route,node_steam_api,node_product_info toneMint
class node_watchdog,node_monitor,node_notify,node_toast,node_gntp,node_websocket,node_playtime,node_playtime_helpers,node_souvenirs toneRose
class node_updater,node_local_sources,node_steam_external,node_processes toneIndigo
```

## Components

### Desktop app

- [Electron window](https://github.com/xan105/achievement-watcher/blob/1.x/app/electron/init.js): `app/electron/init.js`
- [App shell](https://github.com/xan105/achievement-watcher/blob/1.x/app/app.js): `app/app.js`
- [Window controls](https://github.com/xan105/achievement-watcher/blob/1.x/app/components/titleBar/titleBar.js): `app/components/titleBar/titleBar.js`
- [Avatar component](https://github.com/xan105/achievement-watcher/blob/1.x/app/components/userAvatar/avatar.js): `app/components/userAvatar/avatar.js`
- [Settings](https://github.com/xan105/achievement-watcher/blob/1.x/app/ui/settings.js): `app/ui/settings.js`
- [Game and achievement UI](https://github.com/xan105/achievement-watcher/blob/1.x/app/ui/game.js): `app/ui/game.js`
- [Search and sort](https://github.com/xan105/achievement-watcher/blob/1.x/app/ui/search.js): `app/ui/search.js`
- [Refresh UI](https://github.com/xan105/achievement-watcher/blob/1.x/app/ui/refresh.js): `app/ui/refresh.js`

### Achievement ingestion

- [Steam and emulator parser](https://github.com/xan105/achievement-watcher/blob/1.x/app/parser/steam.js): `app/parser/steam.js`
- [Other source parsers](https://github.com/xan105/achievement-watcher/tree/1.x/app/parser): `app/parser`
- [Achievement file parser](https://github.com/xan105/achievement-watcher/blob/1.x/app/parser/achievements.js): `app/parser/achievements.js`

### Steam data service

- [Steam API server](https://github.com/xan105/achievement-watcher/blob/1.x/server/v2/server.js): `server/v2/server.js`
- [API router](https://github.com/xan105/achievement-watcher/blob/1.x/server/v2/router.js): `server/v2/router.js`
- [Steam routes](https://github.com/xan105/achievement-watcher/blob/1.x/server/v2/route/steam.js): `server/v2/route/steam.js`
- [Legacy route wrapper](https://github.com/xan105/achievement-watcher/blob/1.x/server/v2/route/legacy/steam_v1_wrapper.js): `server/v2/route/legacy/steam_v1_wrapper.js`
- [Steam API facade](https://github.com/xan105/achievement-watcher/blob/1.x/server/v2/api/steam/steam.js): `server/v2/api/steam/steam.js`
- [Steam product info](https://github.com/xan105/achievement-watcher/blob/1.x/server/v2/api/steam/steamClient.js): `server/v2/api/steam/steamClient.js`

### Live tracking

- [Achievement watchdog](https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/watchdog.js): `service/watchdog/watchdog.js`
- [Achievement monitoring](https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/monitor.js): `service/watchdog/monitor.js`
- [Notification dispatch](https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/notification/toaster.js): `service/watchdog/notification/toaster.js`
- [Toast transport](https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/notification/transport/toast.js): `service/watchdog/notification/transport/toast.js`
- [GNTP transport](https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/notification/transport/gntp.js): `service/watchdog/notification/transport/gntp.js`
- [Websocket notifications](https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/websocket.js): `service/watchdog/websocket.js`
- [Playtime monitor](https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/playtime/monitor.js): `service/watchdog/playtime/monitor.js`
- [Playtime tracking helpers](https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/playtime/track.js): `service/watchdog/playtime/track.js`
- [Screenshots and video](https://github.com/xan105/achievement-watcher/blob/1.x/service/watchdog/notification/toaster.js): `service/watchdog/notification/toaster.js`

### Updates

- [Application updater](https://github.com/xan105/achievement-watcher/blob/1.x/service/updater/updater.js): `service/updater/updater.js`

### Other components

- **User**
- **Local game files**
- **Steam services**
- **Running games**

## Connections

- User → Electron window: opens app
- Electron window → App shell: loads view (evidence: `app/electron/init.js`)
- App shell → Steam and emulator parser: uses parser
- App shell → Game and achievement UI: presents games
- App shell → Settings: opens settings
- App shell → Window controls: registers component
- App shell → Avatar component: registers component
- User → Local game files: has game data
- Local game files → Steam and emulator parser: reads files
- Local game files → Other source parsers: provides source files
- Steam and emulator parser → Achievement file parser: parses achievements
- Steam and emulator parser → Steam services: fetches metadata
- Achievement file parser → Game and achievement UI: supplies results
- Game and achievement UI → Search and sort: supports browsing
- User → Steam API server: requests data
- Steam API server → API router: mounts routes (evidence: `server/v2/server.js`)
- API router → Steam routes: mounts endpoint (evidence: `server/v2/router.js`)
- API router → Legacy route wrapper: mounts endpoint (evidence: `server/v2/router.js`)
- Steam routes → Steam API facade: calls API (evidence: `server/v2/route/steam.js`)
- Legacy route wrapper → Steam API facade: calls API (evidence: `server/v2/route/legacy/steam_v1_wrapper.js`)
- Steam API facade → Steam product info: requests product info (evidence: `server/v2/api/steam/steam.js`)
- Steam product info → Steam services: requests Steam data (evidence: `server/v2/api/steam/steamClient.js`)
- Achievement watchdog → Achievement monitoring: monitors unlocks
- Achievement monitoring → Notification dispatch: dispatches notifications
- Notification dispatch → Toast transport: sends toast (evidence: `service/watchdog/notification/toaster.js`)
- Notification dispatch → GNTP transport: sends GNTP (evidence: `service/watchdog/notification/toaster.js`)
- Notification dispatch → Websocket notifications: dispatches websocket (evidence: `service/watchdog/notification/toaster.js`)
- Notification dispatch → Screenshots and video: captures media (evidence: `service/watchdog/notification/toaster.js`)
- Running games → Playtime monitor: provides process events
- Playtime monitor → Playtime tracking helpers: uses tracking helpers (evidence: `service/watchdog/playtime/monitor.js`)
- User → Application updater: requests update