# jnpetersen/remote-falcon architecture

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

- Interactive diagram: https://gitdiagram.com/jnpetersen/remote-falcon
- Repository: https://github.com/jnpetersen/remote-falcon

## Overview

Remote Falcon lets show owners configure a public Viewer Page and lets visitors request or vote for songs; the plugin-facing API supports show playback and queue synchronization. The principal flow is viewer interaction through the web app and API into queue/vote state, with the plugin reading playback decisions. The graph preserves account/control-panel, viewer, plugin, and data responsibilities documented by the tree and README. Several API controllers and service implementations were not sampled, so their internal links are omitted; the web-to-API boundary is documented at a high level.

Main entry points: [`remote-falcon-api/src/main/java/com/remotefalcon/api/Application.java`](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/Application.java) (HTTP API), [`remote-falcon-api/src/main/java/com/remotefalcon/api/service/ControlPanelService.java`](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/service/ControlPanelService.java) (Owner settings), [`remote-falcon-api/src/main/java/com/remotefalcon/api/service/PluginService.java`](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/service/PluginService.java) (Plugin synchronization), [`remote-falcon-web/src/App.js`](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-web/src/App.js) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web application<br/>[App.js]"]
  node_authui["Sign-in UI<br/>[Login.js]"]
  node_controlui["Control panel UI"]
  node_viewerui["Viewer page UI<br/>[index.js]"]
  node_authsvc["Authentication client"]
  node_controlsvc["Control panel clients"]
  node_viewersvc["Viewer client"]
end

subgraph group_api["API workflows"]
  node_api["HTTP API<br/>[Application.java]"]
  node_account["Account workflows"]
  node_control["Owner settings"]
  node_viewer["Viewer interactions"]
  node_pluginflow["Plugin synchronization<br/>[PluginService.java]"]
  node_auth["JWT access checks<br/>[AuthUtil.java]"]
end

subgraph group_data["Show state"]
  node_remote[("Show account<br/>[Remote.java]")]
  node_prefs[("Show preferences")]
  node_playlists[("Song catalog<br/>[Playlist.java]")]
  node_juke[("Request queue<br/>[RemoteJuke.java]")]
  node_playlistrepo["Playlist persistence"]
  node_remoterepo["Account persistence"]
  node_jukerepo["Queue persistence"]
  node_db[("SQL database")]
end

node_owner(("Show owner"))
node_visitor(("Viewer"))
node_plugin["FPP / xSchedule"]

node_owner -->|"uses"| node_webapp
node_visitor -->|"visits"| node_webapp
node_webapp -->|"routes to"| node_authui
node_webapp -->|"routes to"| node_controlui
node_webapp -->|"routes to"| node_viewerui
node_authui -->|"authenticates via"| node_authsvc
node_controlui -.->|"loads data via"| node_controlsvc
node_viewerui -->|"loads page via"| node_viewersvc
node_authsvc -.->|"calls"| node_api
node_controlsvc -.->|"calls"| node_api
node_viewersvc -.->|"calls"| node_api
node_api -.->|"dispatches"| node_account
node_api -->|"dispatches"| node_control
node_api -.->|"dispatches"| node_viewer
node_api -.->|"dispatches"| node_pluginflow
node_control -->|"reads / updates"| node_remote
node_control -->|"updates"| node_prefs
node_control -->|"manages"| node_playlists
node_viewer -->|"reads"| node_playlists
node_viewer -->|"queues requests"| node_juke
node_pluginflow -->|"synchronizes"| node_playlists
node_pluginflow -->|"updates queue"| node_juke
node_auth -->|"validates identity"| node_remote
node_control -->|"uses"| node_playlistrepo
node_viewer -->|"queries"| node_playlistrepo
node_pluginflow -->|"queries / saves"| node_playlistrepo
node_pluginflow -->|"queries / saves"| node_jukerepo
node_playlistrepo -.->|"persists"| node_db
node_remoterepo -.->|"persists"| node_db
node_jukerepo -.->|"persists"| node_db
node_plugin -->|"synchronizes show"| node_api

click node_webapp "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-web/src/App.js"
click node_authui "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-web/src/views/pages/authentication/Login.js"
click node_controlui "https://github.com/jnpetersen/remote-falcon/tree/main/remote-falcon-web/src/views/pages/controlPanel"
click node_viewerui "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-web/src/views/pages/externalViewer/index.js"
click node_authsvc "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-web/src/services/authentication/authentication.service.js"
click node_controlsvc "https://github.com/jnpetersen/remote-falcon/tree/main/remote-falcon-web/src/services/controlPanel"
click node_viewersvc "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-web/src/services/viewer/viewerPage.service.js"
click node_api "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/Application.java"
click node_account "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/service/AccountService.java"
click node_control "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/service/ControlPanelService.java"
click node_viewer "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/service/ViewerPageService.java"
click node_pluginflow "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/service/PluginService.java"
click node_auth "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/util/AuthUtil.java"
click node_remote "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/entity/Remote.java"
click node_prefs "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/entity/RemotePreference.java"
click node_playlists "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/entity/Playlist.java"
click node_juke "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/entity/RemoteJuke.java"
click node_playlistrepo "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/repository/PlaylistRepository.java"
click node_remoterepo "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/repository/RemoteRepository.java"
click node_jukerepo "https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/repository/RemoteJukeRepository.java"

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_webapp,node_authui,node_controlui,node_viewerui,node_authsvc,node_controlsvc,node_viewersvc,node_visitor toneBlue
class node_api,node_account,node_control,node_viewer,node_pluginflow,node_auth toneAmber
class node_remote,node_prefs,node_playlists,node_juke,node_playlistrepo,node_remoterepo,node_jukerepo,node_db toneMint
class node_owner,node_plugin toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-web/src/App.js): `remote-falcon-web/src/App.js`
- [Sign-in UI](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-web/src/views/pages/authentication/Login.js): `remote-falcon-web/src/views/pages/authentication/Login.js`
- [Control panel UI](https://github.com/jnpetersen/remote-falcon/tree/main/remote-falcon-web/src/views/pages/controlPanel): `remote-falcon-web/src/views/pages/controlPanel`
- [Viewer page UI](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-web/src/views/pages/externalViewer/index.js): `remote-falcon-web/src/views/pages/externalViewer/index.js`
- [Authentication client](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-web/src/services/authentication/authentication.service.js): `remote-falcon-web/src/services/authentication/authentication.service.js`
- [Control panel clients](https://github.com/jnpetersen/remote-falcon/tree/main/remote-falcon-web/src/services/controlPanel): `remote-falcon-web/src/services/controlPanel`
- [Viewer client](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-web/src/services/viewer/viewerPage.service.js): `remote-falcon-web/src/services/viewer/viewerPage.service.js`

### API workflows

- [HTTP API](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/Application.java): `remote-falcon-api/src/main/java/com/remotefalcon/api/Application.java`
- [Account workflows](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/service/AccountService.java): `remote-falcon-api/src/main/java/com/remotefalcon/api/service/AccountService.java`
- [Owner settings](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/service/ControlPanelService.java): `remote-falcon-api/src/main/java/com/remotefalcon/api/service/ControlPanelService.java`
- [Viewer interactions](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/service/ViewerPageService.java): `remote-falcon-api/src/main/java/com/remotefalcon/api/service/ViewerPageService.java`
- [Plugin synchronization](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/service/PluginService.java): `remote-falcon-api/src/main/java/com/remotefalcon/api/service/PluginService.java`
- [JWT access checks](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/util/AuthUtil.java): `remote-falcon-api/src/main/java/com/remotefalcon/api/util/AuthUtil.java`

### Show state

- [Show account](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/entity/Remote.java): `remote-falcon-api/src/main/java/com/remotefalcon/api/entity/Remote.java`
- [Show preferences](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/entity/RemotePreference.java): `remote-falcon-api/src/main/java/com/remotefalcon/api/entity/RemotePreference.java`
- [Song catalog](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/entity/Playlist.java): `remote-falcon-api/src/main/java/com/remotefalcon/api/entity/Playlist.java`
- [Request queue](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/entity/RemoteJuke.java): `remote-falcon-api/src/main/java/com/remotefalcon/api/entity/RemoteJuke.java`
- [Playlist persistence](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/repository/PlaylistRepository.java): `remote-falcon-api/src/main/java/com/remotefalcon/api/repository/PlaylistRepository.java`
- [Account persistence](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/repository/RemoteRepository.java): `remote-falcon-api/src/main/java/com/remotefalcon/api/repository/RemoteRepository.java`
- [Queue persistence](https://github.com/jnpetersen/remote-falcon/blob/main/remote-falcon-api/src/main/java/com/remotefalcon/api/repository/RemoteJukeRepository.java): `remote-falcon-api/src/main/java/com/remotefalcon/api/repository/RemoteJukeRepository.java`
- **SQL database**

### Other components

- **Show owner**
- **Viewer**
- **FPP / xSchedule**

## Connections

- Show owner → Web application: uses (evidence: `README.md`)
- Viewer → Web application: visits (evidence: `README.md`)
- Web application → Sign-in UI: routes to
- Web application → Control panel UI: routes to
- Web application → Viewer page UI: routes to
- Sign-in UI → Authentication client: authenticates via (evidence: `remote-falcon-web/src/services/authentication/authentication.service.js`)
- Control panel UI → Control panel clients: loads data via
- Viewer page UI → Viewer client: loads page via
- Authentication client → HTTP API: calls
- Control panel clients → HTTP API: calls
- Viewer client → HTTP API: calls
- HTTP API → Account workflows: dispatches
- HTTP API → Owner settings: dispatches
- HTTP API → Viewer interactions: dispatches
- HTTP API → Plugin synchronization: dispatches
- Owner settings → Show account: reads / updates (evidence: `remote-falcon-api/src/main/java/com/remotefalcon/api/service/ControlPanelService.java`)
- Owner settings → Show preferences: updates (evidence: `remote-falcon-api/src/main/java/com/remotefalcon/api/controller/ControlPanelController.java`)
- Owner settings → Song catalog: manages (evidence: `remote-falcon-api/src/main/java/com/remotefalcon/api/controller/ControlPanelController.java`)
- Viewer interactions → Song catalog: reads (evidence: `remote-falcon-api/src/main/java/com/remotefalcon/api/service/ViewerPageService.java`)
- Viewer interactions → Request queue: queues requests (evidence: `remote-falcon-api/src/main/java/com/remotefalcon/api/service/ViewerPageService.java`)
- Plugin synchronization → Song catalog: synchronizes (evidence: `remote-falcon-api/src/main/java/com/remotefalcon/api/service/PluginService.java`)
- Plugin synchronization → Request queue: updates queue (evidence: `remote-falcon-api/src/main/java/com/remotefalcon/api/service/PluginService.java`)
- JWT access checks → Show account: validates identity (evidence: `remote-falcon-api/src/main/java/com/remotefalcon/api/util/AuthUtil.java`)
- Owner settings → Playlist persistence: uses (evidence: `remote-falcon-api/src/main/java/com/remotefalcon/api/service/ControlPanelService.java`)
- Viewer interactions → Playlist persistence: queries (evidence: `remote-falcon-api/src/main/java/com/remotefalcon/api/service/ViewerPageService.java`)
- Plugin synchronization → Playlist persistence: queries / saves (evidence: `remote-falcon-api/src/main/java/com/remotefalcon/api/service/PluginService.java`)
- Plugin synchronization → Queue persistence: queries / saves (evidence: `remote-falcon-api/src/main/java/com/remotefalcon/api/service/PluginService.java`)
- Playlist persistence → SQL database: persists
- Account persistence → SQL database: persists
- Queue persistence → SQL database: persists
- FPP / xSchedule → HTTP API: synchronizes show (evidence: `README.md`)
