# debanjan110d/wallpaper-sync-app architecture

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

- Interactive diagram: https://gitdiagram.com/debanjan110d/wallpaper-sync-app
- Repository: https://github.com/debanjan110d/wallpaper-sync-app

## Overview

Wallpaper Sync is a Windows tray app for managing a local wallpaper collection, rotating wallpapers on a schedule, and optionally syncing from a server. Its principal workflow is adding or syncing images, managing and viewing the local catalog, then applying wallpapers automatically. The optional web app provides an admin dashboard and APIs for wallpaper uploads, metadata, collections, and tags; the separate launching site presents downloads, updates, and reviews. README documentation supports the product-level desktop workflow, while sampled route and UI excerpts confirm only some internal wiring, so uncertain connections are omitted.

Main entry points: [`web/utils/supabase/server.ts`](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/utils/supabase/server.ts) (Supabase data and storage), [`ui/app.js`](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/ui/app.js) (UI coordinator), [`web/app/page.tsx`](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/page.tsx) (Admin dashboard), [`main.js`](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/main.js) (Electron main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_electron_main["Electron main<br/>[main.js]"]
  node_preload["Preload bridge<br/>[preload.js]"]
  node_ui_app["UI coordinator<br/>[app.js]"]
  node_ui_store["UI state<br/>[store.js]"]
  node_catalog["Catalog and viewer<br/>[gallery.js]"]
  node_player["Image viewer<br/>[player.js]"]
  node_wallpaper_manager["Wallpaper rotation"]
  node_settings["App settings<br/>[settings.js]"]
  node_downloader["Remote sync<br/>[downloader.js]"]
  node_metadata_cache[("Metadata cache<br/>[metadataCache.js]")]
  node_desktop_files[("Local wallpaper files")]
end

subgraph group_web["Web admin and API"]
  node_web_admin["Admin dashboard<br/>[page.tsx]"]
  node_login["Admin login<br/>[route.ts]"]
  node_upload["Image upload<br/>[route.ts]"]
  node_wallpaper_api["Wallpaper sync API<br/>[route.ts]"]
  node_catalog_apis["Catalog APIs<br/>[route.ts]"]
  node_tag_api["Tag API<br/>[route.ts]"]
  node_bulk_update["Bulk catalog edits<br/>[route.ts]"]
  node_reviews_api["Reviews API<br/>[route.ts]"]
  node_supabase[("Supabase data and storage<br/>[server.ts]")]
end

subgraph group_ai["Metadata services"]
  node_batch_index["Batch indexing<br/>[route.ts]"]
  node_migration["Metadata migration<br/>[route.ts]"]
  node_collection_discovery["Collection discovery<br/>[route.ts]"]
  node_ai_processor["AI metadata processing<br/>[aiProcessor.ts]"]
end

subgraph group_launch["Launch site"]
  node_launch_home["Download and feature pages<br/>[page.tsx]"]
  node_release_feed["GitHub releases<br/>[githubReleases.ts]"]
  node_launch_reviews["Reviews page<br/>[page.tsx]"]
  node_analytics_api["Analytics endpoint<br/>[route.ts]"]
  node_analytics_store[("Analytics store<br/>[analyticsStore.ts]")]
end

node_desktop_user(("Desktop user"))
node_ai_provider{{"AI provider"}}
node_site_visitor(("Site visitor"))
node_web_admin_user(("Web admin"))

node_desktop_user -->|"manages catalog"| node_ui_app
node_ui_app -->|"updates state"| node_ui_store
node_ui_app -->|"renders catalog"| node_catalog
node_ui_app -->|"opens viewer"| node_player
node_desktop_user -->|"sets preferences"| node_electron_main
node_electron_main -->|"reads settings"| node_settings
node_desktop_user -->|"adds images"| node_desktop_files
node_ui_app -->|"invokes desktop actions"| node_preload
node_preload -->|"bridges requests"| node_electron_main
node_electron_main -->|"controls rotation"| node_wallpaper_manager
node_wallpaper_manager -->|"applies images"| node_desktop_files
node_electron_main -->|"requests sync"| node_downloader
node_downloader -->|"fetches wallpapers"| node_wallpaper_api
node_downloader -->|"syncs images"| node_desktop_files
node_ui_app -->|"refreshes metadata"| node_metadata_cache
node_web_admin_user -->|"authenticates"| node_login
node_web_admin_user -->|"manages library"| node_web_admin
node_web_admin -->|"submits images"| node_upload
node_upload -->|"stores image and row"| node_supabase
node_web_admin -->|"manages collections"| node_catalog_apis
node_web_admin -->|"manages tags"| node_tag_api
node_web_admin -->|"edits catalog"| node_bulk_update
node_wallpaper_api -->|"reads and deletes"| node_supabase
node_catalog_apis -->|"reads and writes"| node_supabase
node_tag_api -->|"reads and writes"| node_supabase
node_bulk_update -->|"updates assignments"| node_supabase
node_batch_index -->|"reads wallpaper rows"| node_supabase
node_batch_index -->|"processes images"| node_ai_processor
node_migration -->|"reads wallpaper rows"| node_supabase
node_migration -->|"processes images"| node_ai_processor
node_ai_processor -.->|"requests analysis"| node_ai_provider
node_collection_discovery -.->|"requests suggestions"| node_ai_provider
node_collection_discovery -->|"saves collections"| node_supabase
node_collection_discovery -->|"assigns collections"| node_ai_processor
node_site_visitor -->|"views download info"| node_launch_home
node_launch_home -->|"loads release data"| node_release_feed
node_site_visitor -->|"views reviews"| node_launch_reviews
node_launch_reviews -->|"loads reviews"| node_reviews_api
node_reviews_api -->|"reads and stores reviews"| node_supabase
node_site_visitor -->|"records activity"| node_analytics_api
node_analytics_api -->|"stores events"| node_analytics_store

click node_electron_main "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/main.js"
click node_preload "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/preload.js"
click node_ui_app "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/ui/app.js"
click node_ui_store "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/ui/store.js"
click node_catalog "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/ui/modules/gallery.js"
click node_player "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/ui/modules/player.js"
click node_wallpaper_manager "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/wallpaperManager.js"
click node_settings "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/settings.js"
click node_downloader "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/downloader.js"
click node_metadata_cache "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/metadataCache.js"
click node_web_admin "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/page.tsx"
click node_login "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/login/route.ts"
click node_upload "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/upload/route.ts"
click node_wallpaper_api "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/wallpapers/route.ts"
click node_catalog_apis "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/collections/route.ts"
click node_tag_api "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/tags/route.ts"
click node_bulk_update "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/wallpapers/bulk-update/route.ts"
click node_reviews_api "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/reviews/route.ts"
click node_supabase "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/utils/supabase/server.ts"
click node_batch_index "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/wallpapers/batch-index/route.ts"
click node_migration "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/wallpapers/migrate/route.ts"
click node_collection_discovery "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/collections/discover/route.ts"
click node_ai_processor "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/utils/aiProcessor.ts"
click node_launch_home "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/launching_page/app/page.tsx"
click node_release_feed "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/launching_page/app/_lib/githubReleases.ts"
click node_launch_reviews "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/launching_page/app/reviews/page.tsx"
click node_analytics_api "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/launching_page/app/api/analytics/route.ts"
click node_analytics_store "https://github.com/debanjan110d/wallpaper-sync-app/blob/main/launching_page/app/_lib/analyticsStore.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_electron_main,node_preload,node_ui_app,node_ui_store,node_catalog,node_player,node_wallpaper_manager,node_settings,node_downloader,node_metadata_cache,node_desktop_files,node_desktop_user toneBlue
class node_web_admin,node_login,node_upload,node_wallpaper_api,node_catalog_apis,node_tag_api,node_bulk_update,node_reviews_api,node_supabase toneAmber
class node_batch_index,node_migration,node_collection_discovery,node_ai_processor toneMint
class node_launch_home,node_release_feed,node_launch_reviews,node_analytics_api,node_analytics_store toneRose
class node_ai_provider,node_site_visitor,node_web_admin_user toneIndigo
```

## Components

### Desktop app

- [Electron main](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/main.js): `main.js`
- [Preload bridge](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/preload.js): `preload.js`
- [UI coordinator](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/ui/app.js): `ui/app.js`
- [UI state](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/ui/store.js): `ui/store.js`
- [Catalog and viewer](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/ui/modules/gallery.js): `ui/modules/gallery.js`
- [Image viewer](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/ui/modules/player.js): `ui/modules/player.js`
- [Wallpaper rotation](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/wallpaperManager.js): `wallpaperManager.js`
- [App settings](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/settings.js): `settings.js`
- [Remote sync](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/downloader.js): `downloader.js`
- [Metadata cache](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/metadataCache.js): `metadataCache.js`
- **Local wallpaper files**

### Web admin and API

- [Admin dashboard](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/page.tsx): `web/app/page.tsx`
- [Admin login](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/login/route.ts): `web/app/api/login/route.ts`
- [Image upload](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/upload/route.ts): `web/app/api/upload/route.ts`
- [Wallpaper sync API](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/wallpapers/route.ts): `web/app/api/wallpapers/route.ts`
- [Catalog APIs](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/collections/route.ts): `web/app/api/collections/route.ts`
- [Tag API](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/tags/route.ts): `web/app/api/tags/route.ts`
- [Bulk catalog edits](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/wallpapers/bulk-update/route.ts): `web/app/api/wallpapers/bulk-update/route.ts`
- [Reviews API](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/reviews/route.ts): `web/app/api/reviews/route.ts`
- [Supabase data and storage](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/utils/supabase/server.ts): `web/utils/supabase/server.ts`

### Metadata services

- [Batch indexing](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/wallpapers/batch-index/route.ts): `web/app/api/wallpapers/batch-index/route.ts`
- [Metadata migration](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/wallpapers/migrate/route.ts): `web/app/api/wallpapers/migrate/route.ts`
- [Collection discovery](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/app/api/collections/discover/route.ts): `web/app/api/collections/discover/route.ts`
- [AI metadata processing](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/web/utils/aiProcessor.ts): `web/utils/aiProcessor.ts`

### Launch site

- [Download and feature pages](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/launching_page/app/page.tsx): `launching_page/app/page.tsx`
- [GitHub releases](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/launching_page/app/_lib/githubReleases.ts): `launching_page/app/_lib/githubReleases.ts`
- [Reviews page](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/launching_page/app/reviews/page.tsx): `launching_page/app/reviews/page.tsx`
- [Analytics endpoint](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/launching_page/app/api/analytics/route.ts): `launching_page/app/api/analytics/route.ts`
- [Analytics store](https://github.com/debanjan110d/wallpaper-sync-app/blob/main/launching_page/app/_lib/analyticsStore.ts): `launching_page/app/_lib/analyticsStore.ts`

### Other components

- **Desktop user**
- **AI provider**
- **Site visitor**
- **Web admin**

## Connections

- Desktop user → UI coordinator: manages catalog
- UI coordinator → UI state: updates state
- UI coordinator → Catalog and viewer: renders catalog
- UI coordinator → Image viewer: opens viewer
- Desktop user → Electron main: sets preferences
- Electron main → App settings: reads settings
- Desktop user → Local wallpaper files: adds images
- UI coordinator → Preload bridge: invokes desktop actions
- Preload bridge → Electron main: bridges requests
- Electron main → Wallpaper rotation: controls rotation
- Wallpaper rotation → Local wallpaper files: applies images
- Electron main → Remote sync: requests sync
- Remote sync → Wallpaper sync API: fetches wallpapers
- Remote sync → Local wallpaper files: syncs images
- UI coordinator → Metadata cache: refreshes metadata
- Web admin → Admin login: authenticates
- Web admin → Admin dashboard: manages library
- Admin dashboard → Image upload: submits images
- Image upload → Supabase data and storage: stores image and row
- Admin dashboard → Catalog APIs: manages collections
- Admin dashboard → Tag API: manages tags
- Admin dashboard → Bulk catalog edits: edits catalog
- Wallpaper sync API → Supabase data and storage: reads and deletes
- Catalog APIs → Supabase data and storage: reads and writes
- Tag API → Supabase data and storage: reads and writes
- Bulk catalog edits → Supabase data and storage: updates assignments
- Batch indexing → Supabase data and storage: reads wallpaper rows
- Batch indexing → AI metadata processing: processes images
- Metadata migration → Supabase data and storage: reads wallpaper rows
- Metadata migration → AI metadata processing: processes images
- AI metadata processing → AI provider: requests analysis
- Collection discovery → AI provider: requests suggestions
- Collection discovery → Supabase data and storage: saves collections
- Collection discovery → AI metadata processing: assigns collections
- Site visitor → Download and feature pages: views download info
- Download and feature pages → GitHub releases: loads release data
- Site visitor → Reviews page: views reviews
- Reviews page → Reviews API: loads reviews
- Reviews API → Supabase data and storage: reads and stores reviews
- Site visitor → Analytics endpoint: records activity
- Analytics endpoint → Analytics store: stores events