skip to content
Aurras

Aurras Architecture Overview

5 min read

Understand the core architecture and design patterns that make Aurras a powerful and extensible terminal music player.

# aurras
# architecture
# design
# development
# technical
Aurras Developer Documentation

System Architecture

Aurras is built with a modular, event-driven architecture that prioritizes performance, maintainability, and extensibility.

High-Level Overview

┌─────────────────────────────────────────────────────────────────┐
│                        Aurras Application                       │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌──────────┐ │
│  │     UI      │  │   Audio     │  │  Library    │  │ Plugin   │ │
│  │   Layer     │  │   Engine    │  │  Manager    │  │ System   │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └──────────┘ │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                 Event System & State Management            │ │
│  └─────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌──────────┐ │
│  │ File System │  │   Network   │  │  Database   │  │ Config   │ │
│  │    I/O      │  │  Services   │  │   Layer     │  │ Manager  │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └──────────┘ │
└─────────────────────────────────────────────────────────────────┘

Core Components

1. User Interface Layer

Responsibilities:

  • Terminal UI rendering and interaction
  • Event handling and user input processing
  • Theme management and visual customization
  • Real-time visualizations and animations

Key Technologies:

  • Custom TUI framework built on terminal capabilities
  • Event-driven rendering system
  • Immediate mode graphics for visualizations
  • Unicode-based drawing primitives

Design Patterns:

  • Model-View-Controller: Clear separation of concerns
  • Observer Pattern: UI components subscribe to state changes
  • Command Pattern: User actions as composable commands

2. Audio Engine

Responsibilities:

  • Audio decoding and format support
  • Real-time audio processing and effects
  • Playback control and queue management
  • Audio device abstraction

Architecture:

Audio Files → Decoder → DSP Chain → Mixer → Output Device
                ↓         ↓        ↓
              Metadata  Effects  Volume
              Extractor Pipeline Control

Key Features:

  • Multi-format support: MP3, FLAC, WAV, OGG, AAC, M4A
  • Real-time DSP: Equalizer, reverb, chorus, compression
  • Gapless playback: Seamless track transitions
  • Low-latency processing: Optimized for real-time performance

3. Library Manager

Responsibilities:

  • Music library indexing and metadata management
  • Search and filtering capabilities
  • Playlist organization and smart playlists
  • File system monitoring and updates

Database Schema:

-- Core entities
tracks (id, path, title, artist, album, duration, format)
albums (id, title, artist, year, artwork_path)
artists (id, name, bio, image_path)
playlists (id, name, description, created_at, updated_at)
 
-- Relationships
playlist_tracks (playlist_id, track_id, position)
track_metadata (track_id, key, value)
listening_history (track_id, played_at, duration_played)

Indexing Strategy:

  • Full-text search: Track titles, artists, albums
  • Metadata indexing: Genre, year, bitrate, etc.
  • File path tracking: Efficient file system monitoring
  • Incremental updates: Only scan changed directories

4. Plugin System

Architecture:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Core APIs     │    │  Plugin Loader  │    │   Plugins       │
│                 │    │                 │    │                 │
│ • Audio API     │◄──►│ • Discovery     │◄──►│ • Audio Effects │
│ • UI API        │    │ • Loading       │    │ • Visualizers   │
│ • Events API    │    │ • Lifecycle     │    │ • Sources       │
│ • Config API    │    │ • Sandboxing    │    │ • UI Extensions │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Plugin Types:

  • Audio Effects: Custom DSP processing
  • Visualizers: New visualization modes
  • Source Plugins: Support for streaming services
  • UI Extensions: Custom interface components
  • Integration Plugins: External service connections

Event System

Event Flow

User Input → Event Queue → Event Dispatcher → Event Handlers → State Updates
     ↓             ↓              ↓                ↓              ↓
Command Parser → Validation → Route to Handler → Execute Action → Notify UI

Event Types

enum AurrasEvent {
    // Playback events
    PlayTrack(TrackId),
    PausePlayback,
    StopPlayback,
    VolumeChange(f32),
    
    // UI events
    KeyPress(Key),
    WindowResize(u16, u16),
    ThemeChange(String),
    
    // Library events
    LibraryScanComplete,
    TrackAdded(Track),
    PlaylistModified(PlaylistId),
    
    // System events
    ConfigChanged(ConfigKey),
    PluginLoaded(PluginId),
    ErrorOccurred(Error),
}

State Management

Centralized State Store

struct AppState {
    // Playback state
    current_track: Option<Track>,
    playback_status: PlaybackStatus,
    volume: f32,
    queue: VecDeque<Track>,
    
    // UI state
    current_view: ViewType,
    selected_item: Option<ItemId>,
    theme: Theme,
    
    // Library state
    tracks: HashMap<TrackId, Track>,
    playlists: HashMap<PlaylistId, Playlist>,
    search_results: Vec<SearchResult>,
    
    // Configuration
    settings: ConfigManager,
    plugins: PluginManager,
}

State Updates

  • Immutable Updates: State modifications create new state versions
  • Event Sourcing: All changes tracked as events for debugging
  • Optimistic Updates: UI updates immediately, reverts on failure
  • Persistence: Critical state automatically saved to disk

Threading Model

Thread Architecture

Main Thread (UI)
├── Event Processing
├── UI Rendering
└── User Input Handling

Audio Thread
├── Audio Decoding
├── DSP Processing
└── Output Management

Background Threads
├── File System Scanning
├── Metadata Extraction
├── Network Operations
└── Database Operations

Thread Communication

  • Message Passing: Channels for inter-thread communication
  • Lock-Free Structures: Atomic operations for shared data
  • Thread Pools: Managed pools for concurrent operations
  • Priority Scheduling: Audio thread gets highest priority

Performance Optimizations

Memory Management

  • Pool Allocation: Reuse audio buffers to prevent garbage collection
  • Lazy Loading: Load metadata and artwork on demand
  • Weak References: Prevent memory leaks in event handlers
  • Memory Mapping: Efficient file access for large libraries

I/O Optimizations

  • Async Operations: Non-blocking file system operations
  • Batch Processing: Group database operations for efficiency
  • Caching Strategy: LRU cache for frequently accessed data
  • Prefetching: Anticipate and load next tracks

Audio Optimizations

  • Sample Rate Conversion: Efficient resampling algorithms
  • SIMD Instructions: Vectorized audio processing
  • Double Buffering: Smooth audio playback without gaps
  • Adaptive Quality: Adjust processing based on system load

Security & Safety

Plugin Sandboxing

  • API Boundaries: Plugins can only access approved APIs
  • Resource Limits: CPU, memory, and file access restrictions
  • Permission System: Explicit permissions for sensitive operations
  • Code Signing: Verify plugin authenticity and integrity

Data Protection

  • Configuration Encryption: Sensitive settings encrypted at rest
  • Secure Networking: TLS for all external communications
  • Input Validation: Sanitize all user input and file metadata
  • Error Handling: Graceful degradation without exposing internals

Testing Strategy

Test Pyramid

                   ┌──────────────┐
                  ┌┤ E2E Tests    ├┐
                 ┌┤└──────────────┘├┐
                ┌┤ Integration Tests ├┐
               ┌┤└──────────────────┘├┐
              ┌┤    Unit Tests         ├┐
             └┤──────────────────────────┘└

Testing Approaches

  • Unit Tests: Individual component testing with mocks
  • Integration Tests: Component interaction testing
  • Performance Tests: Benchmarking audio processing latency
  • UI Tests: Automated terminal interface testing
  • Compatibility Tests: Cross-platform validation

Extensibility Points

Plugin Development

// Plugin trait example
trait AudioPlugin {
    fn initialize(&mut self, config: &PluginConfig) -> Result<()>;
    fn process_audio(&mut self, buffer: &mut AudioBuffer) -> Result<()>;
    fn get_parameters(&self) -> Vec<Parameter>;
    fn set_parameter(&mut self, id: u32, value: f32) -> Result<()>;
}

Configuration Schema

[plugins.my_reverb]
enabled = true
parameters = { room_size = 0.7, damping = 0.3 }
 
[theme.custom]
colors = { accent = "#ff6b6b", background = "#1a1a1a" }

Future Architecture Considerations

Scalability Improvements

  • Microservices: Split into smaller, focused services
  • Event Streaming: Apache Kafka for event processing
  • Distributed Storage: Support for cloud-based libraries
  • Load Balancing: Multiple audio processing nodes

Cloud Integration

  • Sync Services: Cross-device state synchronization
  • Remote Processing: Cloud-based audio enhancement
  • Collaborative Features: Real-time shared playlists
  • Analytics Pipeline: Usage data for recommendations

Want to contribute to Aurras? Check out our Contributing Guide and explore the codebase on GitHub.