API Documentation
Technical reference for Ahoy Indie Media platform endpoints and structure
25
Routes
40+
Endpoints
8
Data Models
Flask
Framework
Documentation Sections
System architecture, API endpoints, data models, and implementation details
Route Definitions
Flask application routes with HTTP methods, templates, and functionality
Main Application Routes
GET
/
home.html
Renders home.html template with Now Playing feed
data from /api/now-playing
Alpine.js
Components
API Integration
Weather API
Dynamic Content
GET
/music
music.html
Renders music.html template with data from
/api/music endpoint
Grid/List Toggle
Search Filter
Bookmark API
Playlist API
GET
/shows
shows.html
Renders shows.html template with data from
/api/shows endpoint
Video Player
Category Filter
Thumbnail Display
Bookmark API
GET
/artists
artists.html
Renders artists.html template with data from
/api/artists endpoint
Profile Display
Type Filter
Genre Search
Social Links
GET
/performances
performances.html
Renders performances.html template with data from
/api/performances endpoint
Event List
Date Filter
Artist Links
User Pages
GET
/my-saves
my_saves.html
User's saved content including tracks, shows,
artists, and playlists
Saved Tracks
Saved Shows
Playlists
Export/Sync
GET
/account
account.html
User profile management and account settings
Profile Settings
Avatar Upload
Statistics
Data Migration
GET
/settings
settings.html
Application preferences and user settings
Dark Mode
Auto-play
Notifications
Privacy
Utility Pages
GET
/player
player.html
Full-screen media player for music and video content
Audio Player
Video Player
Playlist Queue
Controls
GET
/search
search.html
Universal search across all content types
Multi-type Search
Filter Results
Search History
GET
/auth
auth.html
User login and registration interface
Login Form
Registration
Guest Mode
GET
/debug
debug.html
Development and debugging tools (admin only)
System Status
User Management
Data Viewer
Test Tools
Individual Content Pages
Artist Profiles (/artist/<name>)
Individual artist pages with detailed information and content
Bio & Info
Discography
Shows
Social Links
Legal Pages
Privacy Policy
(/privacy)
Privacy policy and data handling information
Security Policy
(/security)
Security practices and user safety information
Terms of Service
(/terms)
Terms of service and usage guidelines
API Endpoints
Content APIs
GET /api/music
Retrieve all music tracks with metadata
GET
static/data/music.json
GET /api/shows
Retrieve all show/video content
GET
static/data/shows.json
GET /api/artists
Retrieve artist directory
GET
static/data/artists.json
GET /api/artist/<name>
Get specific artist profile data
GET
static/data/artists.json
GET /api/now-playing
Curated now playing feed with randomized content
GET
Aggregated from all
content sources
GET /api/daily-playlist
Generate seeded daily playlist based on date
GET
Algorithm-generated from
music.json
User Management APIs
POST /api/auth/login
User authentication and session creation
POST
No Auth
data/users.json
POST /api/auth/register
User registration and account creation
POST
No Auth
data/users.json
GET /api/user/profile
Get user profile information
GET
Auth Required
data/users.json
PUT /api/user/profile
Update user profile information
PUT
Auth Required
data/users.json
Save & Like APIs
POST /api/saves/save
Save content (works for guests and users)
POST
Guest/User
Session/User data
POST /api/saves/unsave
Remove saved content
POST
Guest/User
Session/User data
GET /api/saves/<type>
Get saved content by type
GET
Guest/User
Session/User data
POST /api/likes/like
Like content
POST
Auth Required
data/users.json
Playlist Management APIs
GET/POST /api/playlists
Get all playlists or create new playlist
GET
POST
Guest/User
Session/User data
GET/PUT/DELETE
/api/playlists/<id>
Manage specific playlist
GET
PUT
DELETE
Guest/User
POST /api/playlists/<id>/add
Add content to playlist
POST
Guest/User
Utility APIs
GET /api/search
Universal search across all content
GET
All JSON data
sources
GET /api/weather
Weather information for user location
GET
External weather
API
GET /api/agenda
Daily agenda and events
GET
Generated algorithm
Data Structure
Static Content Data
static/data/music.json
Music tracks database with metadata
id - Unique track identifier
title - Track title
artist - Artist name
album - Album name (optional)
genre - Music genre
duration - Track duration
cover_art - Album cover URL
preview_url - 30s preview URL
added_date - Date added to library
static/data/shows.json
Shows and video content database
id - Unique show identifier
title - Show title
host - Host/creator name
type - Content type (episode, clip,
music_video, broadcast)
description - Show description
thumbnail - Video thumbnail URL
duration - Video duration
publish_date - Publication date
static/data/artists.json
Artist directory and profiles
id - Unique artist identifier
name - Artist name
type - Artist type (musician, host,
producer)
genres - Array of genres
description - Artist bio
image - Artist profile image
social_links - Social media links
location - Geographic location
User Data
data/users.json
User accounts and profiles
username - Unique username
email - User email
password_hash - Hashed password
display_name - Display name
avatar - Profile avatar URL
saved_content - User's saved items
playlists - User's playlists
liked_content - Liked items
created_date - Account creation
date
data/user_activity.json
User activity tracking and analytics
user_id - User identifier
activity_type - Type of activity
content_id - Related content ID
timestamp - Activity timestamp
metadata - Additional activity data
Frontend Architecture
JavaScript Modules
static/js/app.js
Main application JavaScript with global functions
Navigation handler
Search functionality
User authentication
Global state
management
static/js/player.js
Media player functionality for audio and video
Audio player
controls
Video player
controls
Playlist queue
Progress tracking
static/js/playlist-manager.js
Playlist creation and management
Create playlists
Add/remove tracks
Reorder items
Share playlists
static/js/unified-hero.js
Unified hero carousel system for subpages
Content carousel
Touch/swipe support
Auto-rotation
Dynamic content
loading
CSS Architecture
static/css/main.css
Main stylesheet with base styles and layout
CSS Variables
Navigation styles
Grid system
Responsive design
static/css/components.css
Component-specific styles and UI elements
Card components
Form elements
Media players
Interactive
elements
Template System
The application uses Jinja2 templating with Flask, featuring:
- base.html - Main template with navigation and layout
- Page templates - Individual page layouts extending base
- Component reuse - Shared UI components across pages
- Alpine.js integration - Reactive components and interactions
Key Features
Music Discovery
- Curated Now Playing feed
- Daily algorithmic playlists
- Genre-based filtering
- Artist recommendations
Video Content
- Live performance videos
- Music video library
- Exclusive content
- Category-based browsing
Artist Profiles
- Detailed artist information
- Discography and shows
- Social media integration
- Follow functionality
Playlist Management
- Create custom playlists
- Save favorite content
- Cross-platform sync
- Share with others
Universal Search
- Search across all content
- Filter by type
- Real-time results
- Search history
Mobile Experience
- Responsive design
- Touch-optimized controls
- Seamless navigation
- Offline functionality
User Management
- Guest mode support
- User accounts
- Data migration
- Privacy controls
Data Persistence
- Session-based storage
- User data sync
- Backup & restore
- Cross-device access
Technology Stack
Backend
Flask
Python web framework
Jinja2
Template engine
JSON
Data storage format
Session Management
User state handling
Frontend
Alpine.js
Reactive framework
CSS3
Modern styling
HTML5
Semantic markup
Font Awesome
Icon library
Deployment
Gunicorn
WSGI server
Docker
Containerization
Render
Cloud hosting
Environment Variables
Configuration management
Development
Python 3.9+
Programming language
Git
Version control
pip
Package management
Virtual Environment
Dependency isolation
Architecture Pattern
The application follows a Model-View-Controller (MVC) pattern:
- Model - JSON data files and user management system
- View - Jinja2 templates with Alpine.js components
- Controller - Flask route handlers and API endpoints
Development Information
Project Structure
📁 ahoy-little-platform/
📄 app.py Main Flask
application
📄 user_manager.py User management
system
📁 templates/ Jinja2 templates
📁 static/ CSS, JS, images,
data
📁 data/ User and activity
data
📁 scripts/ Utility scripts
📄 requirements.txt Python
dependencies
📄 Dockerfile Container
configuration
Getting Started
- Clone the repository
- Install dependencies:
pip install -r requirements.txt - Run the application:
python app.py - Access at
http://localhost:5000