web app architecture
edwardsharp the freqhole web app is a browser-based music + video player with offline capabilities that connects to one or more freqhole servers (“remotes”).
remotes
Section titled “remotes”a remote is a freqhole server you connect to.
adding remotes
Section titled “adding remotes”you can add multiple remotes:
- your home server (HTTP)
- a friend’s server (P2P)
- demo server (HTTP)
each remote has:
- connection info (URL or node ID)
- your account on that server
- its own music + video library
switching remotes
Section titled “switching remotes”the currently active remote is shown in the header. switch between remotes to browse different libraries.
the remote ... menu also exposes a profile page when you’re signed in. use it to update your username or generate an account-link code for a new passkey/device.
local storage
Section titled “local storage”the web app stores data in your browser — nothing is written to your file system.
what’s stored
Section titled “what’s stored”- library metadata: songs, albums, artists, playlists, videos, series, and seasons (IndexedDB)
- artwork: album art, artist images, and video posters (IndexedDB)
- media files: music + video saved for offline use (OPFS — a private browser file system)
- user preferences: volume, queue, view settings (IndexedDB)
OPFS (Origin Private File System) is a sandboxed storage area provided by the browser — it’s not visible in your file manager and other sites can’t access it.
see where media lives for a full breakdown of storage across all client types.
offline mode
Section titled “offline mode”the web app works without a network connection.
what works offline
Section titled “what works offline”- browse your entire library (metadata is cached)
- view artwork + posters (cached on first view)
- play cached music + video
- create/edit playlists (syncs when online)
offline indicators
Section titled “offline indicators”- status badge shows “offline”
- uncached media shows a cloud icon
- playback attempts on uncached media show a message
syncing
Section titled “syncing”when the connection returns:
- library changes sync automatically
- queue changes apply
- new artwork downloads
- pending actions complete
caching behavior
Section titled “caching behavior”automatic caching
Section titled “automatic caching”- artwork + posters: cached when viewed
- recently played media: cached after playback
- library metadata: synced periodically
- queue items from remotes are saved locally as they play
see where media lives for details on how remote and P2P media is saved.
manual caching
Section titled “manual caching”download specific content for offline use:
- download album: caches all songs + artwork
- download playlist: caches all songs in playlist
cache management
Section titled “cache management”in settings:
- view cache size per remote
- clear cached media (keeps artwork)
- clear everything
authentication
Section titled “authentication”WebAuthn (passkeys)
Section titled “WebAuthn (passkeys)”the web app uses WebAuthn for authentication:
- no passwords to remember
- uses device biometrics (fingerprint, Face ID)
- secure against phishing
- one passkey per device
session persistence
Section titled “session persistence”- sessions stored in browser
- stay logged in until you log out
- each remote has separate session