Skip to content

System Architecture Overview

Cantus is built following Clean Architecture principles to separate concerns, ensure testability, and isolate external third-party dependencies (such as Spotify Web API and LRCLIB) from core domain business logic.

5-Layer Architectural Design

The system is organized into five distinct layers:

flowchart TB
    subgraph Layer1["1. Client Presentation Layer"]
        UnoUI["Uno Platform Client<br/>(WASM Browser / Linux Skia / Windows)"]
        VM["MVVM ViewModels<br/>(LyricsViewModel, LyricLineViewModel)"]
        UnoUI --> VM
    end

    subgraph Layer2["2. Server Engine & Application Layer"]
        Hub["SignalR PlaybackHub<br/>(WebSocket Real-Time Broadcast)"]
        Engine["Adaptive Polling Engine<br/>(ActiveUsersPlaybackMonitor)"]
        Endpoints["ASP.NET Core Minimal APIs<br/>(/api/auth, /api/lyrics, /api/health)"]
    end

    subgraph Layer3["3. Core Domain Layer"]
        Models["Domain Models<br/>(PlaybackState, SyncedLyrics, LyricLine)"]
        Parser["LRC Parser Engine<br/>(LrcParser, Timestamp Normalizer)"]
        Interfaces["Repository Interfaces<br/>(ILyricsCacheRepository, ISessionRepository)"]
    end

    subgraph Layer4["4. Infrastructure & Persistence Layer"]
        Spotify["Spotify Integration<br/>(SpotifyAuthService, SpotifyPlayerClient)"]
        LRCLIB["Lyrics Provider<br/>(LrclibLyricsProvider)"]
        DB["SQLite Database & EF Core<br/>(CantusDbContext)"]
        Crypto["ASP.NET Core Data Protection<br/>(DataProtectionTokenEncryptionService)"]
    end

    subgraph Layer5["5. DevOps & Deployment"]
        Docker["Multi-Arch Container<br/>(amd64 / arm64)"]
    end

    Layer1 -->|SignalR / HTTP| Layer2
    Layer2 --> Layer3
    Layer2 --> Layer4
    Layer4 --> Layer3
    Layer5 -. Hosts .-> Layer2
    Layer5 -. Serves .-> Layer1

Architectural Layers Explained

1. Client Presentation (Uno Platform)

  • Technology: Uno Platform (C# / XAML), Skia Linux/Windows, WebAssembly.
  • Responsibilities: Renders high-frame-rate scrolling lyrics, extracts dynamic color palettes from album artwork, performs local sub-millisecond clock interpolation, and dispatches UI events.

2. Server Engine & Real-Time Hub (ASP.NET Core)

  • Technology: ASP.NET Core 10 Minimal APIs, Microsoft SignalR.
  • Responsibilities: Coordinates connected client display rooms, manages the background adaptive polling engine (featuring end-of-track acceleration, graduated backoff, client tab visibility throttling, and on-demand refresh), orchestrates Spotify token renewal, and handles 4-timestamp NTP clock sync pings.

3. Core Domain Models & Contracts

  • Technology: Pure .NET 10 Standard library (Zero external framework dependencies).
  • Responsibilities: Contains entity definitions (PlaybackState, SyncedLyrics, LyricLine, UserSession), parsing algorithms (LrcParser), and abstract provider/repository contracts.

4. Infrastructure & External Services

  • Technology: Entity Framework Core with SQLite, ASP.NET Core Data Protection, HttpClient.
  • Responsibilities: Implements Spotify OAuth PKCE exchanges and token renewal, queries LRCLIB for synchronized lyrics with fuzzy matching, manages SQLite caching with 30-day negative caching for instrumental songs, and encrypts OAuth refresh tokens at rest.

5. DevOps & Containerization

  • Technology: Multi-stage Docker build, Docker Compose, GitHub Actions.
  • Responsibilities: Compiles the Uno WebAssembly static bundle and ASP.NET Core backend into a single unified container for effortless self-hosting.

Core Conceptual Deep Dives

To explore specific subsystems in depth: