# adamgoodridge/sequence-track-player architecture

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

- Interactive diagram: https://gitdiagram.com/adamgoodridge/sequence-track-player
- Repository: https://github.com/adamgoodridge/sequence-track-player

## Overview

Media Player Shuffler is a Spring Boot podcast player. Users navigate filesystem-backed feeds or request random playback; the server builds track state, exposes playback/navigation, and supports bookmarks and calendar/statistics views. Settings and shortcuts shape playback and organization. The README documents these capabilities, while sampled services and the source index confirm selected internal calls. Several controllers and filesystem details were not sampled, so their workflow links are shown as unverified rather than asserted.

Main entry points: [`src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedService.java`](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedService.java) (Feed orchestration), [`src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/AudioIOFileManagerService.java`](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/AudioIOFileManagerService.java) (Track selection), [`src/main/java/net/adamgoodridge/sequencetrackplayer/shortcut/ShortcutService.java`](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/shortcut/ShortcutService.java) (Feed shortcuts), [`src/main/java/net/adamgoodridge/sequencetrackplayer/filesystem/NasConnectorFileSystem.java`](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/filesystem/NasConnectorFileSystem.java) (NAS filesystem)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and navigation"]
  node_browser["Directory browser"]
  node_feed_http["Feed endpoints"]
  node_feed_api["Feed JSON API"]
end

subgraph group_playback["Feed playback"]
  node_feed_service["Feed orchestration<br/>[FeedService.java]"]
  node_audio_build["Track selection"]
  node_feed_state[("Loaded feed state<br/>[AudioFeeder.java]")]
  node_track_state["Track position"]
  node_sequence["ID sequencing"]
  node_track_actions["Track controls<br/>[TrackControl.java]"]
end

subgraph group_media["Filesystem media"]
  node_filesystem["NAS filesystem"]
  node_directory_service["Directory service"]
  node_feed_items["Feed item model<br/>[DataItem.java]"]
  node_calendar["Calendar dates"]
  node_filesystem_constants["Filesystem constants"]
end

subgraph group_organization["Organization and preferences"]
  node_bookmarks["Track bookmarks"]
  node_bookmark_record[("Bookmark records")]
  node_settings["Playback settings"]
  node_setting_name["Setting definitions<br/>[SettingName.java]"]
  node_shortcuts["Feed shortcuts"]
  node_shortcut_record[("Shortcut records<br/>[Shortcut.java]")]
  node_constants["Playback constants<br/>[ConstantText.java]"]
end

subgraph group_insights["Playback insights"]
  node_statistics["Playback statistics"]
  node_stat_record[("Statistic records<br/>[Statistic.java]")]
  node_live_feeder["Live feed status"]
end

node_listener(("Listener"))

node_listener -.->|"browses"| node_browser
node_listener -.->|"requests playback"| node_feed_http
node_browser -.->|"requests feeds"| node_feed_service
node_feed_http -.->|"delegates to"| node_feed_service
node_feed_api -.->|"delegates to"| node_feed_service
node_feed_service -->|"creates feeds"| node_audio_build
node_feed_service -->|"stores state"| node_feed_state
node_feed_service -->|"resets sequence"| node_sequence
node_feed_service -->|"lists feeds"| node_filesystem
node_feed_service -->|"reads preferences"| node_settings
node_feed_service -->|"loads shortcuts"| node_shortcuts
node_feed_service -->|"moves tracks"| node_track_actions
node_audio_build -->|"reads preferences"| node_settings
node_audio_build -->|"creates position state"| node_track_state
node_directory_service -->|"returns items"| node_feed_items
node_directory_service -->|"returns calendar dates"| node_calendar
node_bookmarks -->|"retrieves loaded track"| node_feed_service
node_bookmarks -->|"saves bookmarks"| node_bookmark_record
node_shortcuts -->|"resolves logos"| node_filesystem
node_shortcuts -->|"saves shortcuts"| node_shortcut_record
node_settings -->|"uses definitions"| node_setting_name
node_statistics -->|"reads and writes"| node_stat_record
node_filesystem -.->|"uses path settings"| node_filesystem_constants
node_audio_build -->|"uses playback values"| node_constants
node_listener -.->|"views listening summaries"| node_statistics
node_listener -.->|"views live status"| node_live_feeder

click node_browser "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/browser/BrowserController.java"
click node_feed_http "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedController.java"
click node_feed_api "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedJsonController.java"
click node_feed_service "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedService.java"
click node_audio_build "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/AudioIOFileManagerService.java"
click node_feed_state "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/AudioFeeder.java"
click node_track_state "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/AudioIOFileManager.java"
click node_sequence "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/sequence/SequenceGeneratorService.java"
click node_track_actions "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/trackcontrol/TrackControl.java"
click node_filesystem "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/filesystem/NasConnectorFileSystem.java"
click node_directory_service "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/filesystem/directory/NasConnectorService.java"
click node_feed_items "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/DataItem.java"
click node_bookmarks "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/bookmark/BookmarkedAudioService.java"
click node_bookmark_record "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/bookmark/BookmarkedAudio.java"
click node_settings "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/settings/SettingService.java"
click node_setting_name "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/settings/SettingName.java"
click node_shortcuts "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/shortcut/ShortcutService.java"
click node_shortcut_record "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/shortcut/Shortcut.java"
click node_calendar "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/thymeleaf/DateForCalendarView.java"
click node_constants "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/constanttext/ConstantText.java"
click node_filesystem_constants "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/constanttext/ConstantTextFileSystem.java"
click node_statistics "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/statistic/StatisticService.java"
click node_stat_record "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/statistic/Statistic.java"
click node_live_feeder "https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/livefeeder/LiveFeederService.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_browser,node_feed_http,node_feed_api toneBlue
class node_feed_service,node_audio_build,node_feed_state,node_track_state,node_sequence,node_track_actions toneAmber
class node_filesystem,node_directory_service,node_feed_items,node_calendar,node_filesystem_constants toneMint
class node_bookmarks,node_bookmark_record,node_settings,node_setting_name,node_shortcuts,node_shortcut_record,node_constants toneRose
class node_statistics,node_stat_record,node_live_feeder,node_listener toneIndigo
```

## Components

### Web and navigation

- [Directory browser](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/browser/BrowserController.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/browser/BrowserController.java`
- [Feed endpoints](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedController.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedController.java`
- [Feed JSON API](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedJsonController.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedJsonController.java`

### Feed playback

- [Feed orchestration](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedService.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedService.java`
- [Track selection](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/AudioIOFileManagerService.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/AudioIOFileManagerService.java`
- [Loaded feed state](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/AudioFeeder.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/AudioFeeder.java`
- [Track position](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/AudioIOFileManager.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/AudioIOFileManager.java`
- [ID sequencing](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/sequence/SequenceGeneratorService.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/sequence/SequenceGeneratorService.java`
- [Track controls](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/trackcontrol/TrackControl.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/trackcontrol/TrackControl.java`

### Filesystem media

- [NAS filesystem](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/filesystem/NasConnectorFileSystem.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/filesystem/NasConnectorFileSystem.java`
- [Directory service](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/filesystem/directory/NasConnectorService.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/filesystem/directory/NasConnectorService.java`
- [Feed item model](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/DataItem.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/DataItem.java`
- [Calendar dates](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/thymeleaf/DateForCalendarView.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/thymeleaf/DateForCalendarView.java`
- [Filesystem constants](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/constanttext/ConstantTextFileSystem.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/constanttext/ConstantTextFileSystem.java`

### Organization and preferences

- [Track bookmarks](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/bookmark/BookmarkedAudioService.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/bookmark/BookmarkedAudioService.java`
- [Bookmark records](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/bookmark/BookmarkedAudio.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/bookmark/BookmarkedAudio.java`
- [Playback settings](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/settings/SettingService.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/settings/SettingService.java`
- [Setting definitions](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/settings/SettingName.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/settings/SettingName.java`
- [Feed shortcuts](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/shortcut/ShortcutService.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/shortcut/ShortcutService.java`
- [Shortcut records](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/shortcut/Shortcut.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/shortcut/Shortcut.java`
- [Playback constants](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/constanttext/ConstantText.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/constanttext/ConstantText.java`

### Playback insights

- [Playback statistics](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/statistic/StatisticService.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/statistic/StatisticService.java`
- [Statistic records](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/statistic/Statistic.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/statistic/Statistic.java`
- [Live feed status](https://github.com/adamgoodridge/sequence-track-player/blob/main/src/main/java/net/adamgoodridge/sequencetrackplayer/livefeeder/LiveFeederService.java): `src/main/java/net/adamgoodridge/sequencetrackplayer/livefeeder/LiveFeederService.java`

### Other components

- **Listener**

## Connections

- Listener → Directory browser: browses
- Listener → Feed endpoints: requests playback
- Directory browser → Feed orchestration: requests feeds (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/browser/BrowserController.java`)
- Feed endpoints → Feed orchestration: delegates to
- Feed JSON API → Feed orchestration: delegates to
- Feed orchestration → Track selection: creates feeds (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedService.java`)
- Feed orchestration → Loaded feed state: stores state (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedService.java`)
- Feed orchestration → ID sequencing: resets sequence (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedService.java`)
- Feed orchestration → NAS filesystem: lists feeds (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedService.java`)
- Feed orchestration → Playback settings: reads preferences (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedService.java`)
- Feed orchestration → Feed shortcuts: loads shortcuts (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedService.java`)
- Feed orchestration → Track controls: moves tracks (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/FeedService.java`)
- Track selection → Playback settings: reads preferences (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/AudioIOFileManagerService.java`)
- Track selection → Track position: creates position state (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/AudioIOFileManagerService.java`)
- Directory service → Feed item model: returns items (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/filesystem/directory/NasConnectorService.java`)
- Directory service → Calendar dates: returns calendar dates (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/filesystem/directory/NasConnectorService.java`)
- Track bookmarks → Feed orchestration: retrieves loaded track (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/bookmark/BookmarkedAudioService.java`)
- Track bookmarks → Bookmark records: saves bookmarks (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/bookmark/BookmarkedAudioService.java`)
- Feed shortcuts → NAS filesystem: resolves logos (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/shortcut/ShortcutService.java`)
- Feed shortcuts → Shortcut records: saves shortcuts (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/shortcut/ShortcutService.java`)
- Playback settings → Setting definitions: uses definitions (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/settings/SettingService.java`)
- Playback statistics → Statistic records: reads and writes (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/statistic/StatisticService.java`)
- NAS filesystem → Filesystem constants: uses path settings (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/filesystem/NasConnectorFileSystem.java`)
- Track selection → Playback constants: uses playback values (evidence: `src/main/java/net/adamgoodridge/sequencetrackplayer/feeder/AudioIOFileManagerService.java`)
- Listener → Playback statistics: views listening summaries
- Listener → Live feed status: views live status