README.org

@@ -1,45 +1,35 @@
-#+TITLE: Asteroid Radio - Internet Radio Streaming Platform
-#+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2025-10-26
+#+TITLE: Asteroid Radio - Internet Streaming Implementation
+#+AUTHOR: Database Implementation Branch
+#+DATE: 2025-09-11
 
 * Overview
 
-Asteroid Radio is a complete internet radio streaming platform 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 with live broadcasting capabilities.
-
-** Project Links
-- *Repository*: https://github.com/fade/asteroid
-- *IRC*: #asteroid.music on irc.libera.chat
-- *Documentation*: See =docs/= directory for comprehensive guides
+This branch implements a complete internet radio streaming system for Asteroid Radio, transforming it from a simple web interface into a fully functional streaming radio station with live broadcasting capabilities.
 
 * Key Features
 
 ** Live Internet Radio Streaming
-- Multiple quality streams: 128kbps MP3, 96kbps AAC, 64kbps MP3
-- Professional audio processing with crossfading and ReplayGain normalization
+- Continuous MP3 streaming at 128kbps stereo
+- Professional audio processing with crossfading and normalization
 - Icecast2 streaming server integration
 - Liquidsoap audio pipeline for reliable broadcasting
-- Stream queue control for curated programming
 
 ** Music Library Management
 - Database-backed track storage with metadata extraction
 - Support for MP3, FLAC, OGG, and WAV formats
 - Automatic metadata extraction using taglib
-- Track search, filtering, sorting, and pagination
-- Recursive directory scanning
+- Track search, filtering, and sorting capabilities
 
 ** Web Interface
 - RADIANCE framework with CLIP templating
-- Admin dashboard for library and user management
-- Multiple player modes: inline, pop-out, and persistent frameset
+- Admin dashboard for library management
+- Web player with HTML5 audio controls
 - Live stream integration with embedded player
-- Responsive design for desktop and mobile
-- Role-based access control (Admin/DJ/Listener)
 
 ** Network Broadcasting
-- Dynamic stream URL detection for multi-environment support
+- WSL-compatible networking for internal network access
 - Professional streaming URLs for media players
 - Multi-listener support via Icecast2
-- Docker-based deployment for easy setup
 
 * Architecture Changes
 
@@ -50,82 +40,46 @@ Asteroid Radio is a complete internet radio streaming platform built with Common
 - Database abstraction layer for track storage
 
 ** Streaming Stack
-- *Icecast2*: Streaming server (port 8000) - Docker containerized
-- *Liquidsoap*: Audio processing and streaming pipeline - Docker containerized
+- *Icecast2*: Streaming server (port 8000)
+- *Liquidsoap*: Audio processing and streaming pipeline
 - *RADIANCE*: Web server and API (port 8080)
-- *PostgreSQL*: Database backend (configured, ready for migration)
-- *Docker Compose*: Container orchestration
+- *Database*: Track metadata and playlist storage
 
 ** File Structure
 #+BEGIN_SRC
 asteroid/
 ├── asteroid.lisp              # Main server with RADIANCE routes
 ├── asteroid.asd               # System definition with dependencies
-├── stream-control.lisp        # Stream queue management
-├── user-management.lisp       # User administration
-├── playlist-management.lisp   # Playlist operations
-├── test-server.sh             # Automated test suite
-├── docker/                    # Docker infrastructure
-│   ├── docker-compose.yml     # Container orchestration
-│   ├── asteroid-radio-docker.liq  # Liquidsoap config
-│   ├── icecast.xml            # Icecast configuration
-│   └── music/                 # Music library mount
+├── asteroid-radio.liq         # Liquidsoap streaming configuration
+├── playlist.m3u               # Generated playlist for streaming
+├── start-asteroid-radio.sh    # Launch script for all services
+├── stop-asteroid-radio.sh     # Stop script for all services
 ├── template/                  # CLIP HTML templates
 │   ├── front-page.chtml       # Main page with live stream
 │   ├── admin.chtml            # Admin dashboard
-│   ├── player.chtml           # Web player interface
-│   └── users.chtml            # User management
+│   └── player.chtml           # Web player interface
 ├── static/                    # CSS and assets
 │   └── asteroid.lass          # LASS stylesheet
-├── docs/                      # Comprehensive documentation
-│   ├── README.org             # Documentation index
-│   ├── PROJECT-OVERVIEW.org   # Architecture overview
-│   ├── PROJECT-HISTORY.org    # Development timeline
-│   ├── INSTALLATION.org       # Setup guide
-│   └── ...                    # Additional guides
-└── music/                     # Music library (local dev)
+└── music/                     # Music library
+    ├── incoming/              # Upload staging area
+    └── library/               # Processed music files
 #+END_SRC
 
-* Quick Start
+* Track Upload Workflow
 
-** Docker Installation (Recommended)
-#+BEGIN_SRC bash
-# Clone repository
-git clone https://github.com/fade/asteroid
-cd asteroid/docker
+** Current Implementation (Manual Upload)
+1. *Copy files to staging*: Place MP3/FLAC files in =music/incoming/=
+2. *Access admin panel*: Navigate to =http://[IP]:8080/asteroid/admin=
+3. *Process files*: Click "Copy Files from Incoming" button
+4. *Database update*: Files are moved to =music/library/= and metadata extracted
+5. *Automatic playlist*: =playlist.m3u= is regenerated for streaming
 
-# Start all services
-docker compose up -d
-
-# Verify streams are working
-curl -I http://localhost:8000/asteroid.mp3
-curl -I http://localhost:8000/asteroid.aac
-curl -I http://localhost:8000/asteroid-low.mp3
-#+END_SRC
-
-** Access Points
-- *Web Interface*: http://localhost:8080/asteroid/
-- *Admin Panel*: http://localhost:8080/asteroid/admin
-- *High Quality MP3*: http://localhost:8000/asteroid.mp3 (128kbps)
-- *High Quality AAC*: http://localhost:8000/asteroid.aac (96kbps)
-- *Low Quality MP3*: http://localhost:8000/asteroid-low.mp3 (64kbps)
-- *Icecast Admin*: http://localhost:8000/admin/ (admin/asteroid_admin_2024)
-
-* Music Library Management
-
-** Adding Music
-1. *Copy files*: Place MP3/FLAC files in =docker/music/= directory
-2. *Access admin panel*: Navigate to =http://localhost:8080/asteroid/admin=
-3. *Scan library*: Click "Scan Library" to index new tracks
-4. *Metadata extraction*: Track information automatically extracted
-5. *Stream queue*: Optionally add tracks to broadcast queue
-
-** Library Scanning
-1. Recursive directory scanning of music folder
-2. Metadata extracted using taglib (title, artist, album, duration)
-3. Database records created with file paths and metadata
-4. Tracks immediately available for playback and streaming
-5. Supports nested folder structures
+** File Processing Steps
+1. Files copied from =music/incoming/= to =music/library/=
+2. Metadata extracted using taglib (title, artist, album, duration, bitrate)
+3. Database record created with file path and metadata
+4. Playlist file updated for Liquidsoap streaming
+5. Files immediately available for on-demand streaming
 
 ** Supported Formats
 - *MP3*: Primary format, best compatibility
@@ -136,259 +90,216 @@ curl -I http://localhost:8000/asteroid-low.mp3
 * Icecast2 Integration
 
 ** Configuration
-- *Server*: localhost:8000 (Docker container)
-- *Mount points*: =/asteroid.mp3=, =/asteroid.aac=, =/asteroid-low.mp3=
-- *Password*: =H1tn31EhsyLrfRmo= (configured in Docker setup)
-- *Formats*: MP3 128kbps, AAC 96kbps, MP3 64kbps
-
-** Docker Setup
-Icecast2 runs in a Docker container - no manual installation needed.
+- *Server*: localhost:8000
+- *Mount point*: =/asteroid.mp3=
+- *Password*: =b3l0wz3r0= (configured in Liquidsoap)
+- *Format*: MP3 128kbps stereo
 
+** Installation (Ubuntu/Debian)
 #+BEGIN_SRC bash
-# Managed via docker-compose
-cd docker
-docker compose up -d icecast
+sudo apt update
+sudo apt install icecast2
+sudo systemctl enable icecast2
+sudo systemctl start icecast2
 #+END_SRC
 
 ** Stream Access
-- *High Quality MP3*: =http://localhost:8000/asteroid.mp3= (128kbps)
-- *High Quality AAC*: =http://localhost:8000/asteroid.aac= (96kbps)
-- *Low Quality MP3*: =http://localhost:8000/asteroid-low.mp3= (64kbps)
-- *Admin interface*: =http://localhost:8000/admin/= (admin/asteroid_admin_2024)
-- *Statistics*: =http://localhost:8000/status.xsl=
+- *Direct URL*: =http://[IP]:8000/asteroid.mp3=
+- *Admin interface*: =http://[IP]:8000/admin/=
+- *Statistics*: =http://[IP]:8000/status.xsl=
 
 * Liquidsoap Integration
 
-** Docker Configuration
-Liquidsoap runs in a Docker container with configuration in =docker/asteroid-radio-docker.liq=
+** Configuration File: =asteroid-radio.liq=
+#+BEGIN_SRC liquidsoap
+#!/usr/bin/liquidsoap
 
-** Key Features
-- *Multiple outputs*: Generates 3 simultaneous streams (MP3 128k, AAC 96k, MP3 64k)
-- *Audio processing*: Crossfading, normalization, ReplayGain
-- *Stream queue*: Reads from M3U playlist for curated programming
-- *Telnet control*: Remote control interface on port 1234
-- *Metadata*: Broadcasts track information to listeners
+# Set log level for debugging
+settings.log.level := 4
 
-** Management
-#+BEGIN_SRC bash
-# Start Liquidsoap container
-cd docker
-docker compose up -d liquidsoap
+# Create playlist from directory
+radio = playlist(mode="randomize", reload=3600, "/path/to/music/library/")
 
-# View logs
-docker compose logs -f liquidsoap
+# Add audio processing
+radio = amplify(1.0, radio)
 
-# Restart streaming
-docker compose restart liquidsoap
+# Fallback with sine wave for debugging
+radio = fallback(track_sensitive=false, [radio, sine(440.0)])
+
+# Output to Icecast2
+output.icecast(
+  %mp3(bitrate=128),
+  host="localhost",
+  port=8000,
+  password="b3l0wz3r0",
+  mount="asteroid.mp3",
+  name="Asteroid Radio",
+  description="Music for Hackers - Streaming from the Asteroid",
+  genre="Electronic/Alternative",
+  url="http://localhost:8080/asteroid/",
+  radio
+)
 #+END_SRC
 
-** Telnet Control
+** Installation (Ubuntu/Debian)
 #+BEGIN_SRC bash
-# Connect to Liquidsoap
-telnet localhost 1234
-
-# Or use netcat for scripting
-echo "request.queue" | nc localhost 1234
-echo "request.skip" | nc localhost 1234
+sudo apt update
+sudo apt install liquidsoap
 #+END_SRC
 
-* User Management
+** Features
+- *Random playlist*: Shuffles music library continuously
+- *Auto-reload*: Playlist refreshes every hour
+- *Audio processing*: Amplification and normalization
+- *Fallback*: Sine tone if no music available (debugging)
+- *Metadata*: Station info broadcast to listeners
 
-** Roles
-- *Admin*: Full system access, user management, stream control
-- *DJ*: Content management, playlist creation, library access
-- *Listener*: Basic playback and personal playlists
+* Network Access
 
-** Default Credentials
-- Username: =admin=
-- Password: =asteroid123=
-- ⚠️ Change default password after first login
+** Local Development
+- *Web Interface*: =http://localhost:8080/asteroid/=
+- *Live Stream*: =http://localhost:8000/asteroid.mp3=
+- *Admin Panel*: =http://localhost:8080/asteroid/admin=
 
-** User Administration
-- Create/manage users via admin panel
-- Role-based access control
-- User profiles and preferences
-- Session management
+** WSL Network Access
+- *WSL IP*: Check with =ip addr show eth0=
+- *Web Interface*: =http://[WSL-IP]:8080/asteroid/=
+- *Live Stream*: =http://[WSL-IP]:8000/asteroid.mp3=
 
-* Player Modes
+** Internal Network Broadcasting
+- Services bind to all interfaces (0.0.0.0)
+- Accessible from any device on local network
+- Compatible with media players (VLC, iTunes, etc.)
 
-** Inline Player
-- Embedded in web pages
-- Standard HTML5 audio controls
-- Queue management
+* Usage Instructions
 
-** Pop-Out Player
-- Standalone player window
-- Independent from main browser window
-- Persistent across page navigation
+** Starting the Radio Station
+#+BEGIN_SRC bash
+# Launch all services
+./start-asteroid-radio.sh
+#+END_SRC
 
-** Frameset Player
-- Bottom-frame persistent player
-- Audio continues during site navigation
-- Seamless listening experience
+** Stopping the Radio Station
+#+BEGIN_SRC bash
+# Stop all services
+./stop-asteroid-radio.sh
+#+END_SRC
+
+** Adding Music
+1. Copy MP3/FLAC files to =music/incoming/=
+2. Visit admin panel: =http://[IP]:8080/asteroid/admin=
+3. Click "Copy Files from Incoming"
+4. Files are processed and added to streaming playlist
+
+** Listening to the Stream
+- *Web Browser*: Visit main page for embedded player
+- *Media Player*: Open =http://[IP]:8000/asteroid.mp3=
+- *Mobile Apps*: Use internet radio apps with stream URL
 
 * API Endpoints
 
-Asteroid Radio provides a comprehensive REST API with 15+ endpoints.
-
-** Status & Authentication
-- =GET /api/asteroid/status= - Server status
-- =GET /api/asteroid/auth-status= - Authentication status
-- =GET /api/asteroid/icecast-status= - Streaming status
-
 ** Track Management
-- =GET /api/asteroid/tracks= - List all tracks
-- =GET /api/asteroid/admin/tracks= - Admin track listing
-- =POST /api/asteroid/admin/scan-library= - Scan music library
+- =GET /api/tracks= - List all tracks with metadata
+- =GET /tracks/{id}/stream= - Stream individual track
+- =POST /api/scan-library= - Scan and update music library
+- =POST /api/copy-files= - Process files from incoming directory
 
 ** Player Control
-- =GET /api/asteroid/player/status= - Player status
-- =POST /api/asteroid/player/play= - Play track
-- =POST /api/asteroid/player/pause= - Pause playback
-- =POST /api/asteroid/player/stop= - Stop playback
-- =POST /api/asteroid/player/resume= - Resume playback
+- =POST /api/player/play= - Start playback
+- =POST /api/player/pause= - Pause playback
+- =POST /api/player/stop= - Stop playback
+- =GET /api/status= - Get server status
 
-** Playlist Management
-- =GET /api/asteroid/playlists= - List user playlists
-- =POST /api/asteroid/playlists/create= - Create playlist
-- =GET /api/asteroid/playlists/get= - Get playlist details
-- =POST /api/asteroid/playlists/add-track= - Add track to playlist
+** Search and Filter
+- =GET /api/tracks?search={query}= - Search tracks
+- =GET /api/tracks?sort={field}= - Sort by field
+- =GET /api/tracks?artist={name}= - Filter by artist
 
-** Stream Queue Control (Admin)
-- =GET /api/asteroid/stream/queue= - Get broadcast queue
-- =POST /api/asteroid/stream/queue/add= - Add track to queue
-- =POST /api/asteroid/stream/queue/remove= - Remove from queue
-- =POST /api/asteroid/stream/queue/clear= - Clear queue
+* Database Schema
 
-See =docs/API-ENDPOINTS.org= for complete API documentation.
+** Tracks Collection
+#+BEGIN_SRC lisp
+(db:create "tracks" '((title :text)
+                      (artist :text)
+                      (album :text)
+                      (duration :integer)
+                      (file-path :text)
+                      (format :text)
+                      (bitrate :integer)
+                      (added-date :integer)
+                      (play-count :integer)))
+#+END_SRC
 
-* Database
-
-** Current: Radiance DB
-- File-based database abstraction
-- Tracks, users, playlists, sessions
-- Suitable for development and small deployments
-
-** PostgreSQL (Configured)
-- Docker container ready
-- Full schema defined
-- Migration pending
-- See =docs/POSTGRESQL-SETUP.org= for details
-
-* Documentation
-
-Comprehensive documentation available in the =docs/= directory:
-
-- *README.org* - Documentation index
-- *PROJECT-OVERVIEW.org* - Architecture and features
-- *PROJECT-HISTORY.org* - Development timeline and milestones
-- *INSTALLATION.org* - Complete installation guide
-- *DEVELOPMENT.org* - Developer setup and guidelines
-- *DOCKER-STREAMING.org* - Docker streaming infrastructure
-- *API-ENDPOINTS.org* - REST API reference
-- *STREAM-CONTROL.org* - Stream queue management
-- *USER-MANAGEMENT-SYSTEM.org* - User administration
-- *PLAYLIST-SYSTEM.org* - Playlist functionality
-- *TESTING.org* - Automated testing guide
-- *POSTGRESQL-SETUP.org* - Database setup
+** Playlists Collection (Future)
+#+BEGIN_SRC lisp
+(db:create "playlists" '((name :text)
+                         (description :text)
+                         (created-date :integer)
+                         (track-ids :text)))
+#+END_SRC
 
 * Dependencies
 
-** Lisp Dependencies
-- =radiance= - Web framework
-- =r-clip= - CLIP templating
-- =lass= - CSS preprocessing
-- =cl-json= - JSON handling
-- =alexandria= - Common Lisp utilities
-- =local-time= - Time handling
-- =taglib= - Audio metadata extraction
+** Lisp Dependencies (asteroid.asd)
+- =:radiance= - Web framework
+- =:r-clip= - Templating system
+- =:lass= - CSS generation
+- =:cl-json= - JSON handling
+- =:alexandria= - Utilities
+- =:local-time= - Time handling
 
-** System Dependencies (Docker)
-- Docker Engine 20.10+
-- Docker Compose 2.0+
-- All streaming components containerized
+** System Dependencies
+- =icecast2= - Streaming server
+- =liquidsoap= - Audio processing
+- =taglib= - Metadata extraction (via audio-streams)
 
-* Testing
+* Development Notes
 
-** Automated Test Suite
-#+BEGIN_SRC bash
-# Run comprehensive tests
-./test-server.sh
+** RADIANCE Configuration
+- Domain: "asteroid"
+- Routes use =#@= syntax for URL patterns
+- Database abstraction via =db:= functions
+- CLIP templates with =data-text= attributes
 
-# Verbose mode
-./test-server.sh -v
-#+END_SRC
+** Database Queries
+- Use quoted symbols for field names: =(:= '_id id)=
+- RADIANCE returns hash tables with string keys
+- Primary key is "_id" internally, "id" in JSON responses
 
-** Test Coverage
-- 25+ automated tests
-- API endpoint validation
-- HTML page rendering
-- Static file serving
-- JSON response format
-- Authentication flows
+** Streaming Considerations
+- MP3 files with spaces in names require playlist.m3u approach
+- Liquidsoap fallback prevents stream silence
+- Icecast2 mount points must match Liquidsoap configuration
 
-* Contributing
+* Future Enhancements
 
-** Development Workflow
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Run test suite
-5. Submit pull request
+** Planned Features
+- Playlist creation and management interface
+- Now-playing status tracking and display
+- Direct browser file uploads with progress
+- Listener statistics and analytics
+- Scheduled programming and automation
 
-** Community
-- *IRC*: #asteroid.music on irc.libera.chat
-- *Issues*: GitHub issue tracker
-- *Discussions*: GitHub discussions
-
-** Core Team
-- Brian O'Reilly (Fade) - Project founder
-- Glenn Thompson (glenneth) - Core developer
-- Luis Pereira - UI/UX
+** Technical Improvements
+- WebSocket integration for real-time updates
+- Advanced audio processing options
+- Multi-bitrate streaming support
+- Mobile-responsive interface enhancements
 
 * Troubleshooting
 
-** Docker Issues
-#+BEGIN_SRC bash
-# Check container status
-docker compose ps
+** Common Issues
+- *No audio in stream*: Check Liquidsoap logs, verify MP3 files
+- *Database errors*: Ensure proper field name quoting in queries
+- *Network access*: Verify WSL IP and firewall settings
+- *File upload issues*: Check permissions on music directories
 
-# View logs
-docker compose logs icecast
-docker compose logs liquidsoap
-
-# Restart services
-docker compose restart
-#+END_SRC
-
-** Stream Not Playing
-- Verify containers are running
-- Check music files exist in =docker/music/=
-- Test stream URLs with curl
-- Review Liquidsoap logs
-
-** Database Issues
-- Check Radiance DB file permissions
-- Verify database collections exist
-- Review application logs
-
-For detailed troubleshooting, see documentation in =docs/= directory.
+** Debugging
+- Enable Liquidsoap debug logging: =settings.log.level := 4=
+- Check Icecast admin interface for stream status
+- Monitor RADIANCE logs for web server issues
+- Verify database connectivity and collections
 
 * License
 
-See LICENSE file for details.
-
-* Acknowledgments
-
-Built with:
-- Common Lisp (SBCL)
-- Radiance web framework
-- Icecast2 streaming server
-- Liquidsoap audio processing
-- Docker containerization
-
-Special thanks to all contributors and the Common Lisp community.
-
----
-
-*Last Updated: 2025-10-26*
+This implementation maintains compatibility with the original Asteroid Radio project license while adding comprehensive streaming capabilities for internet radio broadcasting.

SESSION-NOTES-2025-10-12.org

@@ -0,0 +1,193 @@
+#+TITLE: Session Notes - Page Flow Feature Implementation
+#+DATE: 2025-10-12
+#+AUTHOR: Glenn
+
+* Session Objective
+Implement role-based page flow for Asteroid Radio application where:
+- Admin users are redirected to ~/asteroid/admin~ upon login
+- Regular users (listener, dj) are redirected to ~/asteroid/profile~ upon login
+- User registration redirects to ~/asteroid/profile~ page
+- Navigation links display conditionally based on authentication status and user role
+
+* What Was Accomplished
+
+** Core Feature: Role-Based Page Flow ✅
+- Implemented login redirect logic based on user role
+- Admin users → ~/asteroid/admin~ dashboard
+- Regular users → ~/asteroid/profile~ page
+- Registration flow → ~/asteroid/profile~ for new users
+- Session persistence across page navigation
+
+** User Management API Endpoints ✅
+Converted user management endpoints to use Radiance's ~define-api~ standard:
+- ~/api/asteroid/users~ - Get all users (admin only)
+- ~/api/asteroid/user-stats~ - Get user statistics (admin only)
+- ~/api/asteroid/users/create~ - Create new user (admin only)
+
+** Profile Page API Endpoints ✅
+Added new API endpoints for user profile functionality:
+- ~/api/asteroid/user/profile~ - Get current user profile information
+- ~/api/asteroid/user/listening-stats~ - Get user listening statistics (placeholder)
+- ~/api/asteroid/user/recent-tracks~ - Get recently played tracks (placeholder)
+- ~/api/asteroid/user/top-artists~ - Get top artists (placeholder)
+
+** Authentication & Authorization Improvements ✅
+- Fixed ~require-role~ function to properly handle API requests
+- Added proper JSON error responses for authorization failures
+- Improved password verification with debug logging
+- Added ~reset-user-password~ function for admin use
+
+** JavaScript API Response Handling ✅
+Fixed all JavaScript files to properly handle Radiance's ~api-output~ wrapper format:
+- Response structure: ~{status: 200, message: "Ok.", data: {...}}~
+- Updated all fetch calls to extract ~result.data~ before processing
+- Added fallback handling: ~const data = result.data || result~
+
+* Files Modified
+
+** Backend (Common Lisp)
+*** ~asteroid.lisp~
+- Added profile page API endpoints (~user/profile~, ~user/listening-stats~, ~user/recent-tracks~, ~user/top-artists~)
+- All endpoints use ~define-api~ and ~api-output~ for proper JSON responses
+- Added ~require-authentication~ checks for protected endpoints
+
+*** ~auth-routes.lisp~
+- Fixed user management API endpoints to properly use ~api-output~
+- Updated ~/api/asteroid/users~ endpoint for proper JSON responses
+- Updated ~/api/asteroid/user-stats~ endpoint for proper JSON responses
+- Updated ~/api/asteroid/users/create~ endpoint for proper JSON responses
+- Added proper error handling with HTTP status codes (400, 404, 500)
+
+*** ~user-management.lisp~
+- Modified ~require-role~ function to return ~nil~ for failed API authorization
+- Removed problematic ~radiance:api-output~ calls
+- Responsibility for JSON error responses moved to calling endpoints
+- Added debug logging for authentication flow
+
+** Frontend (JavaScript)
+*** ~static/js/users.js~
+- Fixed ~loadUserStats()~ to handle ~api-output~ wrapper
+- Fixed ~loadUsers()~ to handle ~api-output~ wrapper
+- Fixed ~createNewUser()~ to handle ~api-output~ wrapper
+- Updated to properly extract ~result.data~ before processing
+
+*** ~static/js/auth-ui.js~
+- Fixed ~checkAuthStatus()~ to handle ~api-output~ wrapper
+- Session persistence now working correctly across navigation
+- Conditional nav links display properly based on auth status
+
+*** ~static/js/profile.js~
+- Fixed ~loadProfileData()~ to handle ~api-output~ wrapper
+- Fixed ~loadListeningStats()~ to handle ~api-output~ wrapper
+- Fixed ~loadRecentTracks()~ to handle ~api-output~ wrapper
+- Fixed ~loadTopArtists()~ to handle ~api-output~ wrapper
+- Added safe handling for empty arrays (no errors when no data)
+- Used optional chaining (~?.~) for safer DOM queries
+
+** Documentation
+*** ~TODO.org~
+- Marked "Page Flow" section as complete [2/2] ✅
+- Updated notes to reflect working implementation
+
+* Technical Details
+
+** API Response Format
+All API endpoints now return responses in this format:
+#+BEGIN_SRC json
+{
+  "status": 200,
+  "message": "Ok.",
+  "data": {
+    "status": "success",
+    "users": [...]
+  }
+}
+#+END_SRC
+
+JavaScript must extract the ~data~ property before processing.
+
+** Authentication Flow
+1. User submits login form
+2. ~authenticate-user~ validates credentials
+3. Session field "user-id" is set
+4. User role is checked
+5. Redirect based on role:
+   - ~:admin~ → ~/asteroid/admin~
+   - ~:listener~ or ~:dj~ → ~/asteroid/profile~
+
+** Authorization Pattern
+#+BEGIN_SRC lisp
+(define-api asteroid/endpoint () ()
+  "API endpoint description"
+  (require-role :admin)  ; or (require-authentication)
+  (handler-case
+      (let ((data (get-some-data)))
+        (api-output `(("status" . "success")
+                      ("data" . ,data))))
+    (error (e)
+      (api-output `(("status" . "error")
+                    ("message" . ,(format nil "Error: ~a" e)))
+                  :status 500))))
+#+END_SRC
+
+* Testing Results
+
+** Successful Tests
+- ✅ Admin login redirects to ~/asteroid/admin~
+- ✅ Regular user login redirects to ~/asteroid/profile~
+- ✅ User registration redirects to ~/asteroid/profile~
+- ✅ Session persists across page navigation
+- ✅ Nav links display correctly based on role (Profile/Admin/Logout vs Login/Register)
+- ✅ User statistics display correctly (3 users, 1 admin, 0 DJs)
+- ✅ "View All Users" table displays all users
+- ✅ "Create New User" functionality working
+- ✅ Profile page loads without errors
+- ✅ All API endpoints return proper JSON responses
+
+** Test User Created
+- Username: ~testuser~
+- Email: ~test@asteroid123~
+- Role: ~listener~
+- Status: Active
+
+* Git Commits
+
+Three clean commits on ~feature/user-page-flow~ branch:
+
+1. ~c6ac876~ - feat: Implement role-based page flow and user management APIs
+2. ~0b5bde8~ - fix: Complete UI fixes for page flow feature
+3. ~10bd8b4~ - docs: Mark Page Flow feature as complete in TODO
+
+* Known Limitations
+
+** Profile Page Data
+- Listening statistics return placeholder data (all zeros)
+- Recent tracks return empty array
+- Top artists return empty array
+- These are ready for future implementation when listening history tracking is added
+
+** Future Enhancements
+- Implement actual listening history tracking
+- Add user profile editing functionality
+- Add user avatar/photo support
+- Implement password reset via email
+
+* Notes for Integration
+
+** For Fade (PostgreSQL Migration)
+- User management API endpoints are now standardized with ~define-api~
+- All endpoints use ~api-output~ for consistent JSON responses
+- Session handling is working correctly
+- Ready for database migration - just need to update ~find-user-by-id~, ~get-all-users~, etc.
+
+** For easilokkx (UI Work)
+- All JavaScript files now properly handle ~api-output~ wrapper format
+- Pattern: ~const data = result.data || result;~
+- Profile page has placeholder API endpoints ready for real data
+- Auth UI system working correctly for conditional display
+
+* Branch Status
+- Branch: ~feature/user-page-flow~
+- Status: Complete and tested
+- Ready for: Pull Request to upstream/main
+- Conflicts: None expected (isolated feature work)

asteroid.lisp

@@ -519,7 +519,7 @@
 ;; Front page - regular view by default
 (define-page front-page #@"/" ()
   "Main front page"
-  (let ((template-path (merge-pathnames "template/front-page.ctml" 
+  (let ((template-path (merge-pathnames "template/front-page.chtml" 
                                        (asdf:system-source-directory :asteroid))))
     (clip:process-to-string 
      (plump:parse (alexandria:read-file-into-string template-path))
@@ -540,7 +540,7 @@
 ;; Frameset wrapper for persistent player mode
 (define-page frameset-wrapper #@"/frameset" ()
   "Frameset wrapper with persistent audio player"
-  (let ((template-path (merge-pathnames "template/frameset-wrapper.ctml" 
+  (let ((template-path (merge-pathnames "template/frameset-wrapper.chtml" 
                                        (asdf:system-source-directory :asteroid))))
     (clip:process-to-string 
      (plump:parse (alexandria:read-file-into-string template-path))
@@ -549,7 +549,7 @@
 ;; Content frame - front page content without player
 (define-page front-page-content #@"/content" ()
   "Front page content (displayed in content frame)"
-  (let ((template-path (merge-pathnames "template/front-page-content.ctml" 
+  (let ((template-path (merge-pathnames "template/front-page-content.chtml" 
                                        (asdf:system-source-directory :asteroid))))
     (clip:process-to-string 
      (plump:parse (alexandria:read-file-into-string template-path))
@@ -567,7 +567,7 @@
 ;; Persistent audio player frame (bottom frame)
 (define-page audio-player-frame #@"/audio-player-frame" ()
   "Persistent audio player frame (bottom of page)"
-  (let ((template-path (merge-pathnames "template/audio-player-frame.ctml" 
+  (let ((template-path (merge-pathnames "template/audio-player-frame.chtml" 
                                        (asdf:system-source-directory :asteroid))))
     (clip:process-to-string 
      (plump:parse (alexandria:read-file-into-string template-path))
@@ -606,7 +606,7 @@
 (define-page admin #@"/admin" ()
   "Admin dashboard"
   (require-authentication)
-  (let ((template-path (merge-pathnames "template/admin.ctml" 
+  (let ((template-path (merge-pathnames "template/admin.chtml" 
                                        (asdf:system-source-directory :asteroid)))
         (track-count (handler-case 
                        (length (db:select "tracks" (db:query :all)))
@@ -629,7 +629,7 @@
 (define-page users-management #@"/admin/user" ()
   "User Management dashboard"
   (require-authentication)
-  (let ((template-path (merge-pathnames "template/users.ctml"
+  (let ((template-path (merge-pathnames "template/users.chtml"
                                        (asdf:system-source-directory :asteroid))))
     (clip:process-to-string 
      (plump:parse (alexandria:read-file-into-string template-path))
@@ -639,7 +639,7 @@
 (define-page user-profile #@"/profile" ()
   "User profile page"
   (require-authentication)
-  (let ((template-path (merge-pathnames "template/profile.ctml"
+  (let ((template-path (merge-pathnames "template/profile.chtml"
                                        (asdf:system-source-directory :asteroid))))
     (clip:process-to-string 
      (plump:parse (alexandria:read-file-into-string template-path))
@@ -710,7 +710,7 @@
   (require-authentication)
   (let* ((current-user (auth:current-user))
          (username (gethash "username" current-user))
-         (template-path (merge-pathnames "template/profile.ctml"
+         (template-path (merge-pathnames "template/profile.chtml"
                                         (asdf:system-source-directory :asteroid))))
     (clip:process-to-string 
      (plump:parse (alexandria:read-file-into-string template-path))
@@ -862,7 +862,7 @@
          :success-message ""))))
 
 (define-page player #@"/player" ()
-  (let ((template-path (merge-pathnames "template/player.ctml" 
+  (let ((template-path (merge-pathnames "template/player.chtml" 
                                        (asdf:system-source-directory :asteroid))))
     (clip:process-to-string 
      (plump:parse (alexandria:read-file-into-string template-path))
@@ -878,7 +878,7 @@
 ;; Player content frame (for frameset mode)
 (define-page player-content #@"/player-content" ()
   "Player page content (displayed in content frame)"
-  (let ((template-path (merge-pathnames "template/player-content.ctml" 
+  (let ((template-path (merge-pathnames "template/player-content.chtml" 
                                        (asdf:system-source-directory :asteroid))))
     (clip:process-to-string 
      (plump:parse (alexandria:read-file-into-string template-path))
@@ -889,7 +889,7 @@
 
 (define-page popout-player #@"/popout-player" ()
   "Pop-out player window"
-  (let ((template-path (merge-pathnames "template/popout-player.ctml" 
+  (let ((template-path (merge-pathnames "template/popout-player.chtml" 
                                        (asdf:system-source-directory :asteroid))))
     (clip:process-to-string 
      (plump:parse (alexandria:read-file-into-string template-path))

docs/API-ENDPOINTS.org

@@ -1,6 +1,6 @@
 #+TITLE: Asteroid Radio - API Endpoints Reference
 #+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2025-10-26
+#+DATE: 2025-10-10
 
 * Overview
 
@@ -423,6 +423,51 @@ curl -X POST http://localhost:8080/api/asteroid/playlists/create \
 
 When =browser=true= is passed, endpoints will redirect to appropriate pages instead of returning JSON.
 
+* Integration Examples
+
+** JavaScript/Fetch API
+
+#+BEGIN_SRC javascript
+// Get tracks
+fetch('/api/asteroid/tracks')
+  .then(response => response.json())
+  .then(data => {
+    console.log('Tracks:', data.tracks);
+  });
+
+// Play a track
+fetch('/api/asteroid/player/play', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/x-www-form-urlencoded',
+  },
+  body: 'track-id=123'
+})
+  .then(response => response.json())
+  .then(data => {
+    console.log('Now playing:', data.player.currentTrack);
+  });
+#+END_SRC
+
+** Python
+
+#+BEGIN_SRC python
+import requests
+
+# Get server status
+response = requests.get('http://localhost:8080/api/asteroid/status')
+print(response.json())
+
+# Create playlist (with session)
+session = requests.Session()
+# ... login first ...
+response = session.post(
+    'http://localhost:8080/api/asteroid/playlists/create',
+    data={'name': 'My Playlist', 'description': 'Test'}
+)
+print(response.json())
+#+END_SRC
+
 * Rate Limiting
 
 API endpoints implement rate limiting to prevent abuse. Excessive requests may result in temporary blocking.

docs/API-REFERENCE.org

@@ -1,6 +1,6 @@
-#+TITLE: Asteroid Radio - API Reference
+#+TITLE: Asteroid Radio - Interface Reference
 #+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2025-10-26
+#+DATE: 2025-10-10
 
 * Current Interfaces
 

docs/DEVELOPMENT.org

@@ -1,13 +1,9 @@
 #+TITLE: Asteroid Radio - Development Guide
 #+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2025-10-26
+#+DATE: 2025-10-10
 
 * Development Setup
 
-#+BEGIN_QUOTE
-*Note on Package Managers*: Examples use =apt= (Debian/Ubuntu). Replace with your distribution's package manager (=dnf=, =pacman=, =zypper=, =apk=, etc.).
-#+END_QUOTE
-
 ** Prerequisites
 
 *** System Dependencies
@@ -72,7 +68,7 @@ sbcl --load quicklisp.lisp --eval "(quicklisp-quickstart:install)" --quit
 
 *** Clone Repository
 #+BEGIN_SRC bash
-git clone https://github.com/fade/asteroid.git
+git clone <repository-url>
 cd asteroid
 #+END_SRC
 
@@ -129,9 +125,9 @@ sbcl --eval "(ql:quickload :asteroid)" --eval "(asteroid:start-server)"
 ** Music Library Management
 
 *** Directory Structure
-The music directory is located directly under the asteroid root directory:
+The music directory structure is:
 #+BEGIN_SRC
-asteroid/music/                 # Music directory (can be symlink)
+asteroid/docker/music/          # Host directory (mounted to containers)
 ├── artist1/
 │   ├── album1/
 │   │   ├── track1.mp3
@@ -142,11 +138,6 @@ asteroid/music/                 # Music directory (can be symlink)
     └── single.wav
 #+END_SRC
 
-The =music/= directory can be:
-- A regular directory with music files
-- A symlink to your actual music collection
-- Multiple subdirectories or symlinks within it
-
 *** Recursive Scanning Capabilities
 The Asteroid application includes built-in recursive directory scanning:
 - *Function*: =scan-music-library= in =stream-media.lisp=
@@ -158,21 +149,16 @@ The Asteroid application includes built-in recursive directory scanning:
 *** Adding Music to Development Environment
 #+BEGIN_SRC bash
 # Option 1: Copy music files directly
-cp -r /path/to/your/music/* music/
+cp -r /path/to/your/music/* docker/music/
 
-# Option 2: Symlink entire music directory
-ln -s /path/to/existing/music music
-
-# Option 3: Symlink subdirectories within music/
-mkdir -p music
-ln -s /path/to/collection1 music/collection1
-ln -s /path/to/collection2 music/collection2
-
-# Option 4: Mount remote directory (for large collections)
+# Option 2: Mount remote directory (for large collections)
 # Edit docker-compose.yml to change volume mount:
 # volumes:
 #   - /mnt/remote-music:/app/music:ro
 
+# Option 3: Symlink to existing collection
+ln -s /path/to/existing/music docker/music/collection
+
 # Trigger library scan via API
 curl -X POST http://localhost:8080/api/asteroid/admin/scan-library
 #+END_SRC

docs/DOCKER-STREAMING.org

@@ -1,15 +1,11 @@
 #+TITLE: Asteroid Radio - Docker Streaming Setup
-#+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2025-10-26
+#+AUTHOR: Docker Team
+#+DATE: 2025-10-03
 
 * Docker Streaming Overview
 
 This guide covers the complete Docker-based streaming setup for Asteroid Radio using Icecast2 and Liquidsoap containers. This approach provides a containerized, portable streaming infrastructure that's easy to deploy and maintain.
 
-#+BEGIN_QUOTE
-*Note on Package Managers*: Examples use =apt= (Debian/Ubuntu). Replace with your distribution's package manager (=dnf=, =pacman=, =zypper=, =apk=, etc.).
-#+END_QUOTE
-
 * Architecture
 
 ** Container Stack
@@ -41,7 +37,7 @@ sudo usermod -a -G docker $USER
 ** One-Command Setup
 #+BEGIN_SRC bash
 # Clone and start
-git clone https://github.com/fade/asteroid asteroid-radio
+git clone <repository-url> asteroid-radio
 cd asteroid-radio/docker
 docker compose up -d
 #+END_SRC

docs/INSTALLATION.org

@@ -1,19 +1,11 @@
 #+TITLE: Asteroid Radio - Installation Guide
-#+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2025-10-26
+#+AUTHOR: Installation Team
+#+DATE: 2025-10-03
 
 * Installation Overview
 
 This guide covers the complete installation and deployment of Asteroid Radio. The **recommended approach** is Docker-based installation for easy deployment and consistency. Native installation is also available for development or custom deployments.
 
-#+BEGIN_QUOTE
-*Note on Package Managers*: Examples in this guide use =apt= (Debian/Ubuntu). Replace with your distribution's package manager:
-- Fedora/RHEL: =dnf= or =yum=
-- Arch Linux: =pacman=
-- openSUSE: =zypper=
-- Alpine: =apk=
-#+END_QUOTE
-
 * Quick Start (Docker - Recommended)
 
 ** Prerequisites Check
@@ -26,8 +18,8 @@ docker info
 
 ** One-Command Setup
 #+BEGIN_SRC bash
-# Clone and setup
-git clone https://github.com/fade/asteroid.git asteroid-radio
+# Clone and setup (replace with actual repository URL)
+git clone <repository-url> asteroid-radio
 cd asteroid-radio/docker
 docker compose up -d
 #+END_SRC
@@ -209,8 +201,8 @@ sbcl --load quicklisp.lisp --eval "(quicklisp-quickstart:install)" --eval "(ql:a
 
 *** Step 5: Clone and Setup Project
 #+BEGIN_SRC bash
-# Clone repository
-git clone https://github.com/fade/asteroid /opt/asteroid-radio
+# Clone repository (replace with actual URL)
+git clone <repository-url> /opt/asteroid-radio
 cd /opt/asteroid-radio
 
 # Create required directories
@@ -580,7 +572,7 @@ chmod +x ~/asteroid-radio/health-check.sh
 - Test stream connectivity from different networks
 
 ** Getting Support
-- Check project documentation
+- Check project documentation and FAQ
 - Review system logs for error messages
 - Submit issues with detailed system information
 - Join our IRC chat room: **#asteroid.music** on **irc.libera.chat**

docs/PLAYLIST-SYSTEM.org

@@ -1,6 +1,6 @@
 #+TITLE: Playlist System - Complete (MVP)
 #+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2025-10-26
+#+DATE: 2025-10-04
 
 * Overview
 

docs/POSTGRESQL-SETUP.org

@@ -1,6 +1,6 @@
 #+TITLE: PostgreSQL Setup for Asteroid Radio
 #+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2025-10-26
+#+DATE: 2025-10-04
 
 * Overview
 

docs/PROJECT-HISTORY.org

@@ -1,406 +0,0 @@
-#+TITLE: Asteroid Radio - Project Development History
-#+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2025-10-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
-
-* Development Statistics
-
-** Contributors (by commit count)
-1. Glenn Thompson (glenneth/Glenneth) - 135+ commits
-2. Brian O'Reilly (Fade) - 55+ commits
-3. Luis Pereira (easilok) - 23+ commits
-
-** Total Commits: 213+ commits
-
-** Active Development Period
-- Start: August 12, 2025
-- Current: November 1, 2025
-- Duration: ~2.75 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
-
-* Current State (November 2025)
-
-** 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
-- ✅ Complete Docker containerization
-- ✅ Environment variable configuration
-- ✅ Comprehensive documentation overhaul
-- ✅ Cross-distribution package manager support
-- ✅ Streamlined deployment process
-
-** 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 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.
-
-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: 2025-11-01*

docs/PROJECT-OVERVIEW.org

@@ -1,6 +1,6 @@
 #+TITLE: Asteroid Radio - Project Overview
 #+AUTHOR: Glenn Thompson & Brian O'Reilly (Fade)
-#+DATE: 2025-10-26
+#+DATE: 2025-10-03
 
 * 🎯 Mission
 
@@ -38,8 +38,7 @@ Asteroid Radio is a modern, web-based music streaming platform designed for hack
 - **Common Lisp** (SBCL) - Core application language
 - **Radiance Framework** - Web framework and module system
 - **LASS** - CSS preprocessing in Lisp
-- **PostgreSQL** - Database backend (configured, ready for migration)
-- **Radiance DB** - Current database abstraction layer
+- **PostgreSQL** - Database backend for user accounts and metadata
 
 **Frontend:**
 - **HTML5** with semantic templates
@@ -76,32 +75,26 @@ Asteroid Radio is a modern, web-based music streaming platform designed for hack
 ## 🚀 Features
 
 ### Current Features
-- ✅ **User Authentication** - Registration, login, profiles, role-based access (Admin/DJ/Listener)
+- ✅ **User Authentication** - Registration, login, profiles, role-based access
 - ✅ **User Management** - Admin interface for user administration
-- ✅ **Music Library** - Track management with pagination, search, and filtering
+- ✅ **Music Library** - Track management with pagination and search
 - ✅ **User Playlists** - Create, manage, and play personal music collections
-- ✅ **Multiple Player Modes** - Inline, pop-out, and persistent frameset players
-- ✅ **Stream Queue Control** - Admin control over broadcast stream queue (M3U-based)
+- ✅ **Web Player** - Browser-based player with queue management
 - ✅ **REST API** - Comprehensive JSON API with 15+ endpoints
-- ✅ **Music Streaming** - Multiple quality formats (128k MP3, 96k AAC, 64k MP3)
+- ✅ **Music Streaming** - Multiple quality formats (MP3, AAC)
 - ✅ **Rate Limiting** - Anti-abuse protection
 - ✅ **Docker Integration** - Icecast2/Liquidsoap streaming infrastructure
-- ✅ **PostgreSQL Database** - Configured and ready for migration
+- ✅ **PostgreSQL Database** - Persistent data storage
 - ✅ **Liquidsoap DJ Controls** - Telnet interface for live control
-- ✅ **Dynamic Stream URLs** - Automatic host detection for multi-environment support
-- ✅ **ReplayGain Normalization** - Consistent audio volume across tracks
 - ✅ **Responsive Design** - Works on desktop and mobile
 - ✅ **Automated Testing** - Comprehensive test suite
 
 ### Planned Features
-- 🔄 **PostgreSQL Migration** - Full migration from Radiance DB to PostgreSQL
-- 🔄 **Enhanced Playlist Management** - Full CRUD operations with PostgreSQL
 - 🔄 **Social Features** - Playlist sharing and discovery
 - 🔄 **Advanced Search** - Full-text search and filtering
 - 🔄 **Mobile App** - Native mobile applications
 - 🔄 **WebSocket Support** - Real-time updates
 - 🔄 **Analytics** - Listening statistics and insights
-- 🔄 **Scheduled Programming** - Time-based queue switching
 
 
 ## 🔮 Vision

docs/README.org

@@ -1,6 +1,6 @@
 #+TITLE: Asteroid Radio - Documentation Index
 #+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2025-10-26
+#+DATE: 2025-10-10
 
 * Welcome to Asteroid Radio Documentation
 
@@ -19,9 +19,6 @@ For immediate setup, see:
 *** [[file:PROJECT-OVERVIEW.org][Project Overview]]
 Complete overview of Asteroid Radio's architecture, technology stack, and vision. Start here to understand what Asteroid Radio is and how it works.
 
-*** [[file:PROJECT-HISTORY.org][Project History]]
-Comprehensive development history from inception to present, including timeline, milestones, and contributor information.
-
 *** [[file:INSTALLATION.org][Installation Guide]]  
 Comprehensive installation instructions for multiple operating systems, including system requirements, dependencies, and production deployment considerations.
 
@@ -61,19 +58,16 @@ Pagination system for efficient browsing of large music libraries.
 ** What's Working Now
 - **Web Application**: Full-featured web interface with authentication
 - **REST API**: JSON API with 15+ endpoints for programmatic access
-- **User Management**: Registration, login, roles (Admin/DJ/Listener), and profiles
-- **Music Library**: Track management with pagination, search, and filtering
+- **User Management**: Registration, login, roles, and profiles
+- **Music Library**: Track management with pagination and search
 - **Playlists**: User playlists with creation and playback
-- **Multiple Player Modes**: Inline, pop-out, and persistent frameset players
-- **Stream Queue Control**: Admin control over broadcast stream queue
+- **Web Player**: Browser-based audio player with queue management
 - **Docker Streaming Infrastructure**: Icecast2 + Liquidsoap containers
 - **Three Quality Streams**: 128kbps MP3, 96kbps AAC, 64kbps MP3  
 - **Admin Interface**: Icecast web admin at http://localhost:8000/admin/
 - **Liquidsoap DJ Controls**: Telnet control via localhost:1234
-- **Professional Features**: Crossfading, ReplayGain normalization, metadata support
-- **PostgreSQL Database**: Configured and ready for migration
-- **Dynamic Stream URLs**: Automatic host detection for multi-environment support
-- **Responsive Design**: Works on desktop and mobile devices
+- **Professional Features**: Crossfading, normalization, metadata support
+- **PostgreSQL Database**: Persistent data storage with full CRUD operations
 
 ** Stream URLs (when running)
 - **High Quality MP3**: http://localhost:8000/asteroid.mp3 (128kbps)
@@ -131,15 +125,15 @@ Asteroid Radio uses a modern, containerized architecture:
 ┌─────────────────────────────────────────────────────────────┐
 │                    Asteroid Radio Platform                  │
 ├─────────────────────────────────────────────────────────────┤
-│  Streaming Infrastructure (Docker)                          │
-│  ├── Icecast2 (HTTP Streaming Server)                       │
-│  ├── Liquidsoap (Audio Processing Pipeline)                 │
-│  └── Multiple Format Support (AAC, MP3)                     │
+│  Streaming Infrastructure (Docker)                         │
+│  ├── Icecast2 (HTTP Streaming Server)                     │
+│  ├── Liquidsoap (Audio Processing Pipeline)               │
+│  └── Multiple Format Support (AAC, MP3)                   │
 ├─────────────────────────────────────────────────────────────┤
-│  Control Interfaces                                         │
-│  ├── Icecast Admin Web Interface                            │
-│  ├── Liquidsoap Telnet Control                              │
-│  └── Docker Container Management                            │
+│  Control Interfaces                                        │
+│  ├── Icecast Admin Web Interface                          │
+│  ├── Liquidsoap Telnet Control                            │
+│  └── Docker Container Management                          │
 └─────────────────────────────────────────────────────────────┘
 #+END_EXAMPLE
 
@@ -147,5 +141,5 @@ For detailed technical information, see the **[[file:PROJECT-OVERVIEW.org][Proje
 
 ---
 
-*Last Updated: 2025-10-26*
-*Documentation Version: 3.0*
+*Last Updated: 2025-10-10*
+*Documentation Version: 2.0*

docs/STREAM-CONTROL.org

@@ -1,6 +1,6 @@
 #+TITLE: Stream Queue Control System
-#+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2025-10-26
+#+AUTHOR: Asteroid Radio Team
+#+DATE: 2025-10-14
 
 * Overview
 
@@ -140,7 +140,7 @@ If you're working directly in the Lisp REPL:
 
 * File Locations
 
-- *Stream Queue File*: =stream-queue.m3u= (in project root)
+- *Stream Queue File*: =/home/glenn/Projects/Code/asteroid/stream-queue.m3u=
 - *Docker Mount*: =/app/stream-queue.m3u= (inside Liquidsoap container)
 - *Liquidsoap Config*: =docker/asteroid-radio-docker.liq=
 

docs/TESTING.org

@@ -1,15 +1,11 @@
 #+TITLE: Asteroid Radio Testing Guide
 #+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2025-10-26
+#+DATE: 2025-10-08
 
 * Overview
 
 This document describes the automated testing system for Asteroid Radio.
 
-#+BEGIN_QUOTE
-*Note on Package Managers*: Examples use =apt= (Debian/Ubuntu). Replace with your distribution's package manager (=dnf=, =pacman=, =zypper=, =apk=, etc.).
-#+END_QUOTE
-
 * Test Script
 
 The =test-server.sh= script provides comprehensive testing of all server endpoints and functionality.

docs/TRACK-PAGINATION-SYSTEM.org

@@ -1,6 +1,6 @@
 #+TITLE: Track Pagination System - Complete
 #+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2025-10-26
+#+DATE: 2025-10-04
 
 * Overview
 

docs/USER-MANAGEMENT-SYSTEM.org

@@ -1,6 +1,6 @@
 #+TITLE: User Management System - Complete
 #+AUTHOR: Asteroid Radio Development Team
-#+DATE: 2025-10-26
+#+DATE: 2025-10-04
 
 * Overview
 

frontend-partials.lisp

@@ -33,7 +33,7 @@
   "Get Partial HTML with live status from Icecast server"
   (handler-case
     (let ((now-playing-stats (icecast-now-playing *stream-base-url*))
-          (template-path (merge-pathnames "template/partial/now-playing.ctml"
+          (template-path (merge-pathnames "template/partial/now-playing.chtml"
                                           (asdf:system-source-directory :asteroid))))
       (if now-playing-stats
           (progn

template-utils.lisp

@@ -11,7 +11,7 @@
   "Load and cache a template file"
   (or (gethash template-name *template-cache*)
       (let* ((template-path (merge-pathnames 
-                             (format nil "template/~a.ctml" template-name)
+                             (format nil "template/~a.chtml" template-name)
                              (asdf:system-source-directory :asteroid)))
              (parsed (plump:parse (alexandria:read-file-into-string template-path))))
         (setf (gethash template-name *template-cache*) parsed)