#+TITLE: Asteroid Radio - Project Development History
#+AUTHOR: Asteroid Radio Development Team
#+DATE: 2026-01-26
#+DESCRIPTION: Comprehensive history of the Asteroid Radio project from inception to present

* Project Overview

Asteroid Radio is a web-based internet radio station built with Common Lisp, featuring a hacker-themed terminal aesthetic. The project combines the Radiance web framework with Icecast/Liquidsoap streaming infrastructure to create a full-featured music streaming platform.

** Technology Stack
- *Backend*: Common Lisp (SBCL), Radiance web framework
- *Streaming*: Icecast2, Liquidsoap
- *Database*: PostgreSQL (configured, ready for migration)
- *Frontend*: HTML5, JavaScript, CLIP templating, LASS (CSS in Lisp)
- *Infrastructure*: Docker, Docker Compose

* Project Timeline

** Phase 1: Project Inception (August 2025)

*** 2025-08-12: Initial Commit
- *Author*: Brian O'Reilly (Fade)
- Project founded and initial repository created
- Basic project structure established
- Core Radiance framework integration begun

** Phase 2: Foundation Building (September - Early October 2025)

*** Core Features Established
- Basic web server setup with Radiance
- Initial music library scanning functionality
- Database integration for track metadata
- Basic authentication system
- Front-end page structure

*** Key Contributors Join
- Glenn Thompson (glenneth) begins major contributions
- Luis Pereira joins for UI/UX improvements
- Collaborative development model established

** Phase 3: Template System & UI Overhaul (October 2025)

*** 2025-10-04 to 2025-10-06: CLIP Template Migration
- *Lead*: Luis Pereira, Glenn Thompson
- Migrated from inline HTML to CLIP templating system
- Established consistent site-wide styling
- Implemented VT323 retro terminal font
- Created reusable template components

*** 2025-10-04 to 2025-10-07: User Management System
- *Lead*: Glenn Thompson
- User profile pages with edit functionality
- Registration and authentication UI
- Role-based access control (admin, DJ, listener)
- User profile management interface

*** 2025-10-05: Navigation Improvements
- *Lead*: Luis Pereira
- Unified navigation bar across all pages
- Improved responsive design
- Better mobile experience

** Phase 4: API Refactoring & Testing (October 8-10, 2025)

*** 2025-10-08: Major API Overhaul
- *Lead*: Glenn Thompson
- Refactored all endpoints to use Radiance's define-api macro
- Standardized JSON API responses
- API-aware authentication (auto-detects API vs web requests)
- Comprehensive automated test suite added

*** 2025-10-08 to 2025-10-09: Frontend JavaScript Updates
- Fixed all frontend code to work with new API endpoints
- Improved error handling
- Better async/await patterns

*** 2025-10-10: Documentation Sprint
- *Lead*: Glenn Thompson
- Major documentation cleanup
- Added comprehensive API documentation
- Created testing guides
- Updated all core documentation files

** Phase 5: Streaming Infrastructure (October 8-14, 2025)

*** 2025-10-08: Liquidsoap DJ Controls
- *Lead*: Glenn Thompson
- Telnet integration with Liquidsoap
- Real-time stream control
- Skip track functionality
- Queue management via telnet commands

*** 2025-10-10: Dynamic Stream URL Support
- *Lead*: Glenn Thompson
- Stream base URL as template variable
- Support for multiple deployment environments
- Preparation for multi-network access

*** 2025-10-14: Stream Queue System
- *Lead*: Brian O'Reilly, Glenn Thompson
- M3U playlist queue management
- Admin UI for queue control
- Add/remove tracks from stream queue
- Real-time queue updates

*** 2025-10-14: Audio Quality Improvements
- ReplayGain volume normalization
- Reduced buffering
- Improved player UI
- Better streaming performance

** Phase 6: Advanced Features (October 12-17, 2025)

*** 2025-10-12: Role-Based Page Flow
- *Lead*: Glenn Thompson
- Intelligent page routing based on user role
- Admin-specific workflows
- DJ control interfaces
- Enhanced user experience

*** 2025-10-13: HTML Partial Hydration
- *Lead*: Luis Pereira
- Now-playing partial component
- Server-side rendering with client updates
- Reduced JavaScript complexity
- Better performance

*** 2025-10-15 to 2025-10-16: Configuration System
- *Lead*: Brian O'Reilly
- Dedicated configuration namespace exploration
- Environment-based configuration
- Improved deployment flexibility

*** 2025-10-16: Comprehensive Documentation Update
- *Lead*: Glenn Thompson
- PROJECT-OVERVIEW updated with all features
- Stream queue and ReplayGain documentation
- Complete feature documentation

*** 2025-10-17: Code Quality Improvements
- *Lead*: Glenn Thompson
- Code consistency refactoring
- Bug fixes (track search query variable)
- Maintainability improvements
- Better code organization

** Phase 7: Player Evolution (October 19-25, 2025)

*** 2025-10-19: Pop-Out Player
- *Lead*: Glenn Thompson
- Standalone pop-out player window
- Independent audio playback
- Queue management improvements
- Multi-window support

*** 2025-10-19: Persistent Audio Player (Frameset)
- *Lead*: Glenn Thompson
- Frameset-based persistent player
- Audio continues during navigation
- Bottom-frame player bar
- Seamless listening experience

*** 2025-10-21: Hybrid Player System
- *Lead*: Glenn Thompson
- Combined frameset and pop-out options
- User preference storage (localStorage)
- Flexible playback modes
- Enhanced user choice

*** 2025-10-24: Dynamic Stream URL Detection
- *Lead*: Glenn Thompson
- Automatic host detection from HTTP headers
- Multi-environment support (localhost, Tailscale, LAN)
- Fixed remote access issues
- No configuration needed for different networks

*** 2025-10-25: Typography Consistency Fix
- *Lead*: Glenn Thompson
- Replaced Courier New with VT323 in persistent player
- Consistent font usage site-wide
- Addressed styling feedback
- Improved visual coherence

** Phase 8: Docker Deployment & Documentation (October 26 - November 1, 2025)

*** 2025-10-19: User Initialization Retry Logic
- *Lead*: Luis Pereira (easilok)
- Fixed user initialization retry mechanism
- Improved reliability on startup
- Better error handling

*** 2025-10-26: Custom Environment Variables for Streams
- *Lead*: Luis Pereira (easilok)
- Added MUSIC_LIBRARY environment variable
- Added QUEUE_PLAYLIST environment variable
- Flexible path configuration for Docker deployments

*** 2025-10-26: Docker Setup for Asteroid Application
- *Lead*: Luis Pereira (easilok)
- Created Dockerfile.asteroid for app containerization
- Added docker-compose.asteroid.yml
- Radiance configuration for containerized deployment
- Complete Docker-based deployment solution

*** 2025-10-26: Docker Deployment Documentation
- *Lead*: Luis Pereira (easilok)
- Comprehensive Docker deployment guide in INSTALLATION.org
- Separate sections for stream services and application
- Environment variable documentation
- Build and deployment instructions

*** 2025-10-26: Comprehensive Documentation Update
- *Lead*: Glenn Thompson
- Created PROJECT-HISTORY.org with complete timeline
- Updated all documentation dates to 2025-10-26
- Added current features across all docs
- Updated repository URLs to GitHub
- Documentation version 3.0

*** 2025-10-28: Documentation Refinements
- *Lead*: Glenn Thompson
- Fixed music directory location (asteroid/music/ not docker/music/)
- Removed redundant Python/JavaScript examples from API docs
- Added package manager notes for cross-distribution compatibility
- Clarified symlink support for music directories

*** 2025-11-01: Documentation Merge and Cleanup
- *Lead*: Glenn Thompson
- Merged upstream Docker deployment documentation
- Removed obsolete session notes
- Synchronized with upstream/main
- Prepared comprehensive documentation PR

** Phase 9: Production Launch & Feature Expansion (November - December 2025)

*** Early November: Template & Deployment Stabilization
- *Lead*: Glenn Thompson, Brian O'Reilly
- Changed template extension to match CLIP documentation (.ctml)
- Updated all template paths in calling code
- Refactored for Lispy improvements (templates, strings, error handling)
- Deployment and post-deployment fixes
- Fixed redirection when navigating between frameset views
- Stream quality persistence in local storage
- Security: Removed hardcoded admin credentials from login page
- Stream service containers locked to localhost access

*** Mid-November: Password Management & Data Model Refactoring
- *Lead*: Glenn Thompson, Luis Pereira
- Password management and listener count fixes
- Database schema bug fixes from upstream merge
- User database methods moved to data-model
- Admin button visibility restricted to admin accounts
- Profile password change fixes
- Playlist creation fixes on frontend

*** Late November: Recently Played & MusicBrainz Integration
- *Lead*: Glenn Thompson
- Recently played tracks feature with MusicBrainz integration
- Favicon and asteroid.png graphics added to front page
- User activate/deactivate routes
- User role update routes
- Track name clickable with external link icon
- Audio player color matched to app panels
- Blinking live cursor added

*** Late November: Spectrum Analyzer & Parenscript Conversion
- *Lead*: Glenn Thompson
- Real-time spectrum analyzer using Web Audio API
- Parenscript (Lisp-to-JavaScript) implementation
- Spectrum analyzer theming and visualization styles
- Monotone theme and dynamic border color
- HTML entity decoding fixes in now playing titles
- JavaScript converted to Parenscript with stream fixes

*** Early December: PostgreSQL Integration & Database Work
- *Lead*: Brian O'Reilly, Glenn Thompson
- PostgreSQL interface integration (i-postmodern)
- Users table case sensitivity fixes
- Database credentials sourced from environment
- M3U files moved to dedicated playlists directory
- Database creation script corrections
- User dump/restore to CSV functionality

*** Mid-December: Player Improvements & Listener Statistics
- *Lead*: Glenn Thompson / Cascade
- Wedged player fix with reconnect button and volume preservation
- Status page for frameset mode with navigation fixes
- Listener statistics feature with geo stats collection
- City-level tracking in geo stats
- Expandable city breakdown in admin view
- Liquidsoap/Icecast controls added
- Library scan fixes

*** Mid-December: Shuffle Mount & Channel Selector
- *Lead*: Glenn Thompson
- Shuffle stream mount with separate recently-played tracking
- Channel/quality selector separation
- Dynamic playlist phase names
- Dynamic channel name updates
- Playlist crossfade transitions
- New playlists in support of variety

*** Late December: Playlist Scheduler & User Features
- *Lead*: Glenn Thompson
- Automatic playlist scheduler with cl-cron
- Admin UI for playlist scheduler with server time display
- Database persistence for playlist schedule
- Track favorites feature with star button
- Listening history tracking
- Listening activity chart on profile page
- Avatar upload functionality
- Track requests and profile enhancements

*** Late December: Custom Playlists & Rate Limiting
- *Lead*: Glenn Thompson, Luis Pereira
- Custom user playlists with submission and admin review
- YP directory listings for internet-radio.com and xiph.org
- Rate limiting macros for define-page and define-api
- Bigger rate limits for now-playing API routes
- Favorites sync between front page and frame player via postMessage
- Listening history refactored to data-model
- Timestamp normalization for PostgreSQL compatibility

*** December 31: Version 1.0 & Operations
- *Lead*: Brian O'Reilly
- Declared "Version 1.0" milestone
- TODO.org updated to reflect production launch
- Operations procedures instituted
- Repository cleanup of interstitial files

* Development Statistics

** Contributors (by commit count)
1. Glenn Thompson (glenneth/Glenneth) - 354 commits
2. Brian O'Reilly (Fade) - 148 commits
3. Luis Pereira (easilok) - 109 commits

** Total Commits: 614 commits

** Pull Requests Merged: 88
1. Glenn Thompson (glenneth1) - 59 PRs
2. Luis Pereira (easilok) - 26 PRs
3. Brian O'Reilly (fade) - 3 PRs

** Active Development Period
- Start: August 12, 2025
- Current: January 26, 2026
- Duration: ~5.5 months of active development

* Major Features Implemented

** Core Functionality
- Music library scanning and metadata extraction
- PostgreSQL database integration (configured, ready for migration)
- Track search and filtering
- Playlist management
- Stream queue control
- Live streaming via Icecast/Liquidsoap

** User Management
- User registration and authentication
- Role-based access control (Admin, DJ, Listener)
- User profiles with edit functionality
- Session management
- Role-based page flow

** Streaming Features
- Multiple quality options (AAC 96k, MP3 128k, MP3 64k)
- ReplayGain volume normalization
- Live now-playing information
- Icecast integration
- Liquidsoap DJ controls
- Stream queue management

** Player Options
- Inline web player
- Pop-out player window
- Persistent frameset player
- Hybrid player system
- Quality selector
- Auto-reconnect on errors

** API & Integration
- RESTful JSON API
- API-aware authentication
- Comprehensive test suite
- Telnet integration with Liquidsoap
- Real-time status updates

** UI/UX
- Retro terminal aesthetic (VT323 font)
- Responsive design
- CLIP templating system
- LASS CSS preprocessing
- Consistent navigation
- HTML partial hydration

** Infrastructure
- Docker containerization (streams and application)
- Docker Compose orchestration
- Dockerfile for Asteroid application
- Environment variable configuration
- PostgreSQL database (configured)
- Multi-environment support
- Dynamic URL detection

* Technical Milestones

** Architecture Evolution
1. *Initial*: Monolithic HTML generation
2. *Template Migration*: CLIP templating system
3. *API Standardization*: Radiance define-api macros
4. *Component Architecture*: HTML partials and hydration
5. *Multi-Mode Player*: Hybrid player system

** Code Quality Improvements
- Comprehensive test suite
- API refactoring for consistency
- Code organization and maintainability
- Documentation standards
- Consistent error handling

** Performance Optimizations
- ReplayGain normalization
- Reduced buffering
- Efficient database queries
- Parallel music scanning
- Client-side caching

** Phase 10: Documentation Overhaul (January 2026)

*** 2026-01-26: Comprehensive Documentation Update
- *Lead*: Glenn Thompson / Cascade
- Major documentation alignment with current codebase
- Standardized all API endpoint references to `/api/asteroid/` base path
- Updated UI route documentation to reflect root `/` mounting
- Corrected template file extensions from `.chtml` to `.ctml`
- Fixed Docker music library paths (`music/library/` standardization)
- Updated stream queue file location to `playlists/stream-queue.m3u`
- Expanded API-ENDPOINTS.org with playlist management, stream control, and admin APIs
- Updated all metadata dates to 2026-01-26
- Bumped documentation version to 3.1
- Author metadata standardization (Glenn → Glenn Thompson where applicable)

* Current State (January 2026)

** Production Ready Features
- Full music streaming platform
- User management system
- Admin control panel
- DJ controls
- Multiple player modes
- Complete Docker deployment (streams + application)
- Multi-environment support with dynamic URLs
- Comprehensive documentation

** Active Development Areas
- PostgreSQL migration (configured, ready for data migration)
- JavaScript code cleanup and refactoring
- Additional UI improvements
- Performance optimization
- Feature expansion based on user feedback

** Recent Achievements (January 2026)
- Complete documentation overhaul aligning docs with codebase
- API endpoint standardization (`/api/asteroid/` base path)
- Docker deployment fully documented
- Documentation version 3.1 released
- All metadata updated and consistent

** Known Issues & Future Work
- PostgreSQL migration (configured, pending data migration)
- Continued UI/UX refinement
- Additional streaming features (per design.org)
- Enhanced playlist functionality
- Live chat and song requests
- Mobile app considerations
- Scalability improvements

* Project Philosophy

** Design Principles
- *Hacker Aesthetic*: Terminal-inspired retro design
- *User Choice*: Multiple player modes and options
- *Simplicity*: Clean, focused interface
- *Performance*: Fast, responsive experience
- *Flexibility*: Multi-environment support

** Development Approach
- Collaborative development
- Iterative improvements
- Comprehensive testing
- Documentation-first
- User feedback driven

* Acknowledgments

** Core Team
- *Brian O'Reilly (Fade)*: Project founder, architecture, streaming infrastructure
- *Glenn Thompson (glenneth)*: Major features, API, player systems, documentation
- *Luis Pereira*: UI/UX, templating, frontend improvements

** Technologies
- Radiance web framework
- Icecast streaming server
- Liquidsoap audio processing
- PostgreSQL database
- Common Lisp ecosystem

* Conclusion

Asteroid Radio has evolved from a simple concept into a full-featured internet radio platform over 5+ months of active development. The project demonstrates the power of Common Lisp for web development and the collaborative nature of open-source development.

With complete Docker deployment, comprehensive documentation, and a growing feature set, Asteroid Radio is ready for production use while continuing to evolve with regular improvements, bug fixes, and new features based on user needs and technical requirements.

** Project Links
- Repository: https://github.com/fade/asteroid
- Contributors: https://github.com/fade/asteroid/graphs/contributors
- IRC: #asteroid.music on irc.libera.chat

---

*Last Updated: 2026-01-26*