1  #+TITLE: Asteroid Radio - Project Development History
  2  #+AUTHOR: Asteroid Radio Development Team
  3  #+DATE: 2025-10-26
  4  #+DESCRIPTION: Comprehensive history of the Asteroid Radio project from inception to present
  5  
  6  * Project Overview
  7  
  8  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.
  9  
 10  ** Technology Stack
 11  - *Backend*: Common Lisp (SBCL), Radiance web framework
 12  - *Streaming*: Icecast2, Liquidsoap
 13  - *Database*: PostgreSQL (configured, ready for migration)
 14  - *Frontend*: HTML5, JavaScript, CLIP templating, LASS (CSS in Lisp)
 15  - *Infrastructure*: Docker, Docker Compose
 16  
 17  * Project Timeline
 18  
 19  ** Phase 1: Project Inception (August 2025)
 20  
 21  *** 2025-08-12: Initial Commit
 22  - *Author*: Brian O'Reilly (Fade)
 23  - Project founded and initial repository created
 24  - Basic project structure established
 25  - Core Radiance framework integration begun
 26  
 27  ** Phase 2: Foundation Building (September - Early October 2025)
 28  
 29  *** Core Features Established
 30  - Basic web server setup with Radiance
 31  - Initial music library scanning functionality
 32  - Database integration for track metadata
 33  - Basic authentication system
 34  - Front-end page structure
 35  
 36  *** Key Contributors Join
 37  - Glenn Thompson (glenneth) begins major contributions
 38  - Luis Pereira joins for UI/UX improvements
 39  - Collaborative development model established
 40  
 41  ** Phase 3: Template System & UI Overhaul (October 2025)
 42  
 43  *** 2025-10-04 to 2025-10-06: CLIP Template Migration
 44  - *Lead*: Luis Pereira, Glenn Thompson
 45  - Migrated from inline HTML to CLIP templating system
 46  - Established consistent site-wide styling
 47  - Implemented VT323 retro terminal font
 48  - Created reusable template components
 49  
 50  *** 2025-10-04 to 2025-10-07: User Management System
 51  - *Lead*: Glenn Thompson
 52  - User profile pages with edit functionality
 53  - Registration and authentication UI
 54  - Role-based access control (admin, DJ, listener)
 55  - User profile management interface
 56  
 57  *** 2025-10-05: Navigation Improvements
 58  - *Lead*: Luis Pereira
 59  - Unified navigation bar across all pages
 60  - Improved responsive design
 61  - Better mobile experience
 62  
 63  ** Phase 4: API Refactoring & Testing (October 8-10, 2025)
 64  
 65  *** 2025-10-08: Major API Overhaul
 66  - *Lead*: Glenn Thompson
 67  - Refactored all endpoints to use Radiance's define-api macro
 68  - Standardized JSON API responses
 69  - API-aware authentication (auto-detects API vs web requests)
 70  - Comprehensive automated test suite added
 71  
 72  *** 2025-10-08 to 2025-10-09: Frontend JavaScript Updates
 73  - Fixed all frontend code to work with new API endpoints
 74  - Improved error handling
 75  - Better async/await patterns
 76  
 77  *** 2025-10-10: Documentation Sprint
 78  - *Lead*: Glenn Thompson
 79  - Major documentation cleanup
 80  - Added comprehensive API documentation
 81  - Created testing guides
 82  - Updated all core documentation files
 83  
 84  ** Phase 5: Streaming Infrastructure (October 8-14, 2025)
 85  
 86  *** 2025-10-08: Liquidsoap DJ Controls
 87  - *Lead*: Glenn Thompson
 88  - Telnet integration with Liquidsoap
 89  - Real-time stream control
 90  - Skip track functionality
 91  - Queue management via telnet commands
 92  
 93  *** 2025-10-10: Dynamic Stream URL Support
 94  - *Lead*: Glenn Thompson
 95  - Stream base URL as template variable
 96  - Support for multiple deployment environments
 97  - Preparation for multi-network access
 98  
 99  *** 2025-10-14: Stream Queue System
100  - *Lead*: Brian O'Reilly, Glenn Thompson
101  - M3U playlist queue management
102  - Admin UI for queue control
103  - Add/remove tracks from stream queue
104  - Real-time queue updates
105  
106  *** 2025-10-14: Audio Quality Improvements
107  - ReplayGain volume normalization
108  - Reduced buffering
109  - Improved player UI
110  - Better streaming performance
111  
112  ** Phase 6: Advanced Features (October 12-17, 2025)
113  
114  *** 2025-10-12: Role-Based Page Flow
115  - *Lead*: Glenn Thompson
116  - Intelligent page routing based on user role
117  - Admin-specific workflows
118  - DJ control interfaces
119  - Enhanced user experience
120  
121  *** 2025-10-13: HTML Partial Hydration
122  - *Lead*: Luis Pereira
123  - Now-playing partial component
124  - Server-side rendering with client updates
125  - Reduced JavaScript complexity
126  - Better performance
127  
128  *** 2025-10-15 to 2025-10-16: Configuration System
129  - *Lead*: Brian O'Reilly
130  - Dedicated configuration namespace exploration
131  - Environment-based configuration
132  - Improved deployment flexibility
133  
134  *** 2025-10-16: Comprehensive Documentation Update
135  - *Lead*: Glenn Thompson
136  - PROJECT-OVERVIEW updated with all features
137  - Stream queue and ReplayGain documentation
138  - Complete feature documentation
139  
140  *** 2025-10-17: Code Quality Improvements
141  - *Lead*: Glenn Thompson
142  - Code consistency refactoring
143  - Bug fixes (track search query variable)
144  - Maintainability improvements
145  - Better code organization
146  
147  ** Phase 7: Player Evolution (October 19-25, 2025)
148  
149  *** 2025-10-19: Pop-Out Player
150  - *Lead*: Glenn Thompson
151  - Standalone pop-out player window
152  - Independent audio playback
153  - Queue management improvements
154  - Multi-window support
155  
156  *** 2025-10-19: Persistent Audio Player (Frameset)
157  - *Lead*: Glenn Thompson
158  - Frameset-based persistent player
159  - Audio continues during navigation
160  - Bottom-frame player bar
161  - Seamless listening experience
162  
163  *** 2025-10-21: Hybrid Player System
164  - *Lead*: Glenn Thompson
165  - Combined frameset and pop-out options
166  - User preference storage (localStorage)
167  - Flexible playback modes
168  - Enhanced user choice
169  
170  *** 2025-10-24: Dynamic Stream URL Detection
171  - *Lead*: Glenn Thompson
172  - Automatic host detection from HTTP headers
173  - Multi-environment support (localhost, Tailscale, LAN)
174  - Fixed remote access issues
175  - No configuration needed for different networks
176  
177  *** 2025-10-25: Typography Consistency Fix
178  - *Lead*: Glenn Thompson
179  - Replaced Courier New with VT323 in persistent player
180  - Consistent font usage site-wide
181  - Addressed styling feedback
182  - Improved visual coherence
183  
184  ** Phase 8: Docker Deployment & Documentation (October 26 - November 1, 2025)
185  
186  *** 2025-10-19: User Initialization Retry Logic
187  - *Lead*: Luis Pereira (easilok)
188  - Fixed user initialization retry mechanism
189  - Improved reliability on startup
190  - Better error handling
191  
192  *** 2025-10-26: Custom Environment Variables for Streams
193  - *Lead*: Luis Pereira (easilok)
194  - Added MUSIC_LIBRARY environment variable
195  - Added QUEUE_PLAYLIST environment variable
196  - Flexible path configuration for Docker deployments
197  
198  *** 2025-10-26: Docker Setup for Asteroid Application
199  - *Lead*: Luis Pereira (easilok)
200  - Created Dockerfile.asteroid for app containerization
201  - Added docker-compose.asteroid.yml
202  - Radiance configuration for containerized deployment
203  - Complete Docker-based deployment solution
204  
205  *** 2025-10-26: Docker Deployment Documentation
206  - *Lead*: Luis Pereira (easilok)
207  - Comprehensive Docker deployment guide in INSTALLATION.org
208  - Separate sections for stream services and application
209  - Environment variable documentation
210  - Build and deployment instructions
211  
212  *** 2025-10-26: Comprehensive Documentation Update
213  - *Lead*: Glenn Thompson
214  - Created PROJECT-HISTORY.org with complete timeline
215  - Updated all documentation dates to 2025-10-26
216  - Added current features across all docs
217  - Updated repository URLs to GitHub
218  - Documentation version 3.0
219  
220  *** 2025-10-28: Documentation Refinements
221  - *Lead*: Glenn Thompson
222  - Fixed music directory location (asteroid/music/ not docker/music/)
223  - Removed redundant Python/JavaScript examples from API docs
224  - Added package manager notes for cross-distribution compatibility
225  - Clarified symlink support for music directories
226  
227  *** 2025-11-01: Documentation Merge and Cleanup
228  - *Lead*: Glenn Thompson
229  - Merged upstream Docker deployment documentation
230  - Removed obsolete session notes
231  - Synchronized with upstream/main
232  - Prepared comprehensive documentation PR
233  
234  * Development Statistics
235  
236  ** Contributors (by commit count)
237  1. Glenn Thompson (glenneth/Glenneth) - 135+ commits
238  2. Brian O'Reilly (Fade) - 55+ commits
239  3. Luis Pereira (easilok) - 23+ commits
240  
241  ** Total Commits: 213+ commits
242  
243  ** Active Development Period
244  - Start: August 12, 2025
245  - Current: November 1, 2025
246  - Duration: ~2.75 months of active development
247  
248  * Major Features Implemented
249  
250  ** Core Functionality
251  - ✅ Music library scanning and metadata extraction
252  - ✅ PostgreSQL database integration (configured, ready for migration)
253  - ✅ Track search and filtering
254  - ✅ Playlist management
255  - ✅ Stream queue control
256  - ✅ Live streaming via Icecast/Liquidsoap
257  
258  ** User Management
259  - ✅ User registration and authentication
260  - ✅ Role-based access control (Admin, DJ, Listener)
261  - ✅ User profiles with edit functionality
262  - ✅ Session management
263  - ✅ Role-based page flow
264  
265  ** Streaming Features
266  - ✅ Multiple quality options (AAC 96k, MP3 128k, MP3 64k)
267  - ✅ ReplayGain volume normalization
268  - ✅ Live now-playing information
269  - ✅ Icecast integration
270  - ✅ Liquidsoap DJ controls
271  - ✅ Stream queue management
272  
273  ** Player Options
274  - ✅ Inline web player
275  - ✅ Pop-out player window
276  - ✅ Persistent frameset player
277  - ✅ Hybrid player system
278  - ✅ Quality selector
279  - ✅ Auto-reconnect on errors
280  
281  ** API & Integration
282  - ✅ RESTful JSON API
283  - ✅ API-aware authentication
284  - ✅ Comprehensive test suite
285  - ✅ Telnet integration with Liquidsoap
286  - ✅ Real-time status updates
287  
288  ** UI/UX
289  - ✅ Retro terminal aesthetic (VT323 font)
290  - ✅ Responsive design
291  - ✅ CLIP templating system
292  - ✅ LASS CSS preprocessing
293  - ✅ Consistent navigation
294  - ✅ HTML partial hydration
295  
296  ** Infrastructure
297  - ✅ Docker containerization (streams and application)
298  - ✅ Docker Compose orchestration
299  - ✅ Dockerfile for Asteroid application
300  - ✅ Environment variable configuration
301  - ✅ PostgreSQL database (configured)
302  - ✅ Multi-environment support
303  - ✅ Dynamic URL detection
304  
305  * Technical Milestones
306  
307  ** Architecture Evolution
308  1. *Initial*: Monolithic HTML generation
309  2. *Template Migration*: CLIP templating system
310  3. *API Standardization*: Radiance define-api macros
311  4. *Component Architecture*: HTML partials and hydration
312  5. *Multi-Mode Player*: Hybrid player system
313  
314  ** Code Quality Improvements
315  - Comprehensive test suite
316  - API refactoring for consistency
317  - Code organization and maintainability
318  - Documentation standards
319  - Consistent error handling
320  
321  ** Performance Optimizations
322  - ReplayGain normalization
323  - Reduced buffering
324  - Efficient database queries
325  - Parallel music scanning
326  - Client-side caching
327  
328  * Current State (November 2025)
329  
330  ** Production Ready Features
331  - Full music streaming platform
332  - User management system
333  - Admin control panel
334  - DJ controls
335  - Multiple player modes
336  - Complete Docker deployment (streams + application)
337  - Multi-environment support with dynamic URLs
338  - Comprehensive documentation
339  
340  ** Active Development Areas
341  - PostgreSQL migration (configured, ready for data migration)
342  - JavaScript code cleanup and refactoring
343  - Additional UI improvements
344  - Performance optimization
345  - Feature expansion based on user feedback
346  
347  ** Recent Achievements
348  - ✅ Complete Docker containerization
349  - ✅ Environment variable configuration
350  - ✅ Comprehensive documentation overhaul
351  - ✅ Cross-distribution package manager support
352  - ✅ Streamlined deployment process
353  
354  ** Known Issues & Future Work
355  - PostgreSQL migration (configured, pending data migration)
356  - Continued UI/UX refinement
357  - Additional streaming features (per design.org)
358  - Enhanced playlist functionality
359  - Live chat and song requests
360  - Mobile app considerations
361  - Scalability improvements
362  
363  * Project Philosophy
364  
365  ** Design Principles
366  - *Hacker Aesthetic*: Terminal-inspired retro design
367  - *User Choice*: Multiple player modes and options
368  - *Simplicity*: Clean, focused interface
369  - *Performance*: Fast, responsive experience
370  - *Flexibility*: Multi-environment support
371  
372  ** Development Approach
373  - Collaborative development
374  - Iterative improvements
375  - Comprehensive testing
376  - Documentation-first
377  - User feedback driven
378  
379  * Acknowledgments
380  
381  ** Core Team
382  - *Brian O'Reilly (Fade)*: Project founder, architecture, streaming infrastructure
383  - *Glenn Thompson (glenneth)*: Major features, API, player systems, documentation
384  - *Luis Pereira*: UI/UX, templating, frontend improvements
385  
386  ** Technologies
387  - Radiance web framework
388  - Icecast streaming server
389  - Liquidsoap audio processing
390  - PostgreSQL database
391  - Common Lisp ecosystem
392  
393  * Conclusion
394  
395  Asteroid Radio has evolved from a simple concept into a full-featured internet radio platform in just 2.75 months of active development. The project demonstrates the power of Common Lisp for web development and the collaborative nature of open-source development.
396  
397  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.
398  
399  ** Project Links
400  - Repository: https://github.com/fade/asteroid
401  - Contributors: https://github.com/fade/asteroid/graphs/contributors
402  - IRC: #asteroid.music on irc.libera.chat
403  
404  ---
405  
406  *Last Updated: 2025-11-01*