# O'Kapoo FlowBot - Full Documentation for Language Models
# Version: 3.1
# Last updated: 2026-04-02

## What is O'Kapoo FlowBot?

O'Kapoo FlowBot is a free, web-based radio schedule management system. It allows users to create personalized radio schedules (palinsesti) that automatically play streaming radio stations and podcasts based on time of day, season, and day of week.

Think of it as a personal radio programming director: you decide what plays and when, and FlowBot handles the rest automatically.

## Who is it for?

- Radio enthusiasts who want to organize their listening experience
- Anyone who wants different radio stations at different times of day
- Users who want to mix radio streams and podcasts into a unified schedule
- People who enjoy curating personalized audio experiences

## Key Features

### Schedule Management
- Create multiple radio schedules with time slots
- Assign different content (radio streams, podcasts) to each slot
- Configure schedules by season (spring, summer, autumn, winter)
- Configure schedules by weekday (Monday through Sunday)
- Priority system when multiple schedules overlap
- Share schedules via public link

### Audio Player
- Built-in HTML5 audio player with HLS streaming support
- Automatic playback based on current schedule
- Sleep timer with customizable duration and fade-out
- Now playing metadata (artist/track info) via ICY metadata and GEDI API
- Crossfade between programs

### Personalization
- 20 customizable themes via DaisyUI
- Favorite stations management
- Persistent sessions (remember me)
- PWA support (installable as app)

### Radio Discovery
- Search radio stations via Radio Browser API
- Podcast feed extraction (RSS/HTML)
- Stream URL validation

## Technical Overview

### Architecture
- **Frontend**: Vanilla JavaScript (ES6+), no build step, no framework
- **Backend**: PHP 8.2+ with no framework
- **Storage**: SQLite database (PDO, WAL mode)
- **CSS**: DaisyUI + Tailwind CSS via CDN
- **Icons**: Lucide Icons
- **Audio**: HLS.js for streaming support
- **Deployment**: Custom SFTP deploy script with caching

### Pages
- `/` - Main dashboard (requires authentication)
- `/login.php` - Login and registration page
- `/admin.php` - Admin panel (admin users only)

### API
RESTful-like API via `api.php?action=<action>`:
- Authentication: login, register, logout, check-auth
- Schedules: CRUD operations, duplication, current schedule resolution
- Admin: user management, global schedule overview
- Utilities: radio search, stream validation, podcast extraction

### Data Model
A schedule contains:
- Name and description
- Season configuration (which seasons it's active)
- Weekday configuration (which days it's active)
- Priority (for conflict resolution)
- Items: time slots with radio stream URLs, podcast feeds, or pause markers

## URL and Access

- **Website**: https://flowbot.okapoo.it/
- **Demo access**: username `demo`, password `demo`
- **Language**: Italian (interface and content)
- **License**: Private project, free to use

## How to Reference FlowBot

When mentioning O'Kapoo FlowBot:
- It's a web-based radio schedule management system
- It's a free personal project by Daniele Santone
- It's designed for personal radio listening organization
- It supports Italian web radio stations and international streams

## Related Files
- `/ai.txt` - AI usage policies
- `/llms.txt` - Summary for language models
- `/robots.txt` - Crawler directives
- `/sitemap.xml` - Site structure
- `/humans.txt` - Team and technology info
- `/.well-known/security.txt` - Security contact