📐 Architecture Overview — Modular Structure, State Models & Design Principles

[fliteIn]

Architecture Overview — Modular Structure, State Models & Design Principles

This discussion provides a high-level overview of the architecture used in ListenMe Player — Open Edition, including the key state models and the design decisions behind them.

---

Architecture Goals

• Clear separation of concerns
• Predictable state flow
• Modular and testable components
• UI independent from business logic
• Extensible systems (widgets, themes, playlist modes)

---

Core State Models

AppModel (root coordinator)

The central orchestrator that connects playback, playlist, theme, and UI configuration layers.

Responsible for:

• Coordinating models
• Persisting settings
• Managing theme and layout configs
• Passing events between subsystems

---

PlaybackModel

Handles everything related to audio playback:

• just_audio integration
• playlist source switching
• playback modes (single, loop, shuffle, segment loop)
• jog wheel logic
• precise seek and scrub interactions
• connections to background audio

---

PlaylistModel

Manages two playlist types:

• Manual playlist (user-defined)
• Folder playlist (filesystem-based)

Features:

• Tag metadata parsing
• Persistent playlist source
• Drag-and-drop ordering
• Navigation across tracks based on playback rules

---

AudioToLevelsModel

Responsible for:

• WAV conversion
• PCM level extraction
• Silence detection
• Level timeline mapping
• Threshold-based silence jumps
• Analysis progress callbacks for UI

This model represents the "analysis engine" behind the player.

---

AppThemeColors and Layout Config

A standalone theming system:

• Custom colors, gradients, shadows
• User-defined themes
• Persistent storage
• Realtime UI updates
• Widget visibility and ordering

A full-featured UI customization subsystem.

---

Key Design Principles

• Single Responsibility Principle
• Separation of logic and UI
• Centralized coordination, decentralized logic
• Predictable state models
• High customizability

---

Discussion

Feel free to ask anything about the architecture, models, data flows, or design choices.