“Commercial traffic shouldn’t be this hard”

ELF (Elfish Log Factory) is a modern, web-based commercial traffic scheduling system designed specifically for broadcast radio stations. It provides comprehensive tools for managing advertisers, campaigns, commercials, and daily schedules with seamless integration to Rivendell Radio Automation.

The project was created to provide small and medium-sized radio stations with a free, professional-grade traffic scheduling solution that can be self-hosted or offered as a cloud-based SaaS service. ELF handles the complete workflow from campaign creation through auto-scheduling to exporting logs in Rivendell-compatible formats.

Key Capabilities:

• Multi-station management with separate configurations
• Advertiser and campaign management
• Intelligent auto-scheduling with rotation and separation rules
• Rivendell cart inventory synchronization
• Export logs in column-aligned ASCII format for Rivendell import
• Daypart-based scheduling (Morning Drive, Midday, etc.)
• Competitive separation rules to prevent conflicts
• RESTful API for all operations

• Free Traffic System: Provide small/medium radio stations with professional traffic scheduling at no cost
• Rivendell Integration: Seamless bi-directional integration with Rivendell automation systems
• Ease of Use: Modern, intuitive web interface requiring minimal training
• Multi-Station Support: Single installation can manage multiple radio stations

• Auto-Scheduling Intelligence: Smart algorithms for optimal commercial placement
• Separation Rules: Automatic enforcement of competitive separation policies
• Hybrid Deployment: Support both self-hosted and cloud-based SaaS models
• Extensibility: Plugin architecture for additional music schedulers and automation systems

• Network Scheduling: Chain-wide campaign management across multiple markets
• Advanced Analytics: Performance reporting and business intelligence
• Music Scheduler Integration: Support for MusicMaster, Selector, and other systems
• Mobile Applications: Native iOS/Android apps for on-the-go management
• AI-Powered Optimization: Machine learning for schedule optimization and recommendations

ELF follows a modern, decoupled three-tier architecture:

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   React     │─────▶│    Django    │─────▶│ PostgreSQL  │
│  Frontend   │ HTTP │  REST API    │ SQL  │  Database   │
│  (Port 5173)│◀─────│  (Port 9000) │◀─────│             │
└─────────────┘ JSON └──────────────┘      └─────────────┘
                            │
                            │ MySQL
                            ▼
                      ┌──────────────┐
                      │  Rivendell   │
                      │   Database   │
                      └──────────────┘
                            │
                            ▼
                      ┌──────────────┐
                      │  Export Logs │
                      │  (ASCII)     │
                      └──────────────┘

Backend:

• Framework: Django 5.0 with Django REST Framework
• Database: PostgreSQL 16 (primary), MySQL client (Rivendell sync)
• Authentication: JWT tokens with session fallback
• Server: Gunicorn (production), Django dev server (development)
• API Documentation: DRF Spectacular (OpenAPI/Swagger)

Frontend:

• Framework: React 18 with Vite build tool
• UI Library: Tailwind CSS for styling
• Routing: React Router DOM
• State Management: TanStack Query (React Query)
• HTTP Client: Axios

Infrastructure:

• Web Server: Nginx (reverse proxy)
• Containerization: Docker & Docker Compose
• OS: Ubuntu 24.04 LTS (primary target)
• Deployment: Rumble Cloud (planned for SaaS)

Core Models:

• Station: Radio station configuration, Rivendell connection settings
• Advertiser: Client/agency information, industry categorization
• Campaign: Flight dates, spot count, contract tracking
• Commercial: Individual spots with cart numbers and lengths
• DayPart: Time segments (Morning Drive, Midday, etc.)
• DailySchedule: Container for each day's schedule
• ScheduledSpot: Individual spot placements with times
• RivendellCart: Synced cart inventory from Rivendell
• SchedulingRule: Auto-scheduling rules (daypart, separation)
• SeparationRule: Competitive separation policies

RESTful Endpoints:

Stations:          /api/stations/
Advertisers:       /api/advertisers/
Campaigns:         /api/campaigns/
Commercials:       /api/commercials/
DayParts:          /api/dayparts/
Daily Schedules:   /api/daily-schedules/
Scheduled Spots:   /api/scheduled-spots/
Rivendell Carts:   /api/rivendell-carts/
Separation Rules:  /api/separation-rules/

Custom Actions:
  POST /api/sync-rivendell/      - Sync cart inventory
  POST /api/export-log/          - Export daily log
  POST /api/auto-schedule/       - Auto-schedule campaign

Cart Synchronization:

• Connects to Rivendell MySQL database
• Reads CART table for commercial inventory
• Syncs cart numbers, titles, lengths, groups
• Can filter by group (e.g., “COMM” for commercials)

Export Format (Column-Aligned ASCII):

HH:MM:SS CCCCCC TITLE_60_CHARS_WIDE                            MM:SS
08:15:00 001234 Joe's Pizza - February Special                 00:30
08:47:00 001235 Smith Auto - Winter Clearance Sale             01:00
09:23:00 001236 Main Street Restaurant - Lunch Special         00:30

Import Process:

1. ELF exports to configured path (e.g., /var/elf/exports/20240208.txt)
2. Rivendell's RDLogManager imports via configured template
3. Merges with music schedule from RDLibrary

System Requirements:

• Ubuntu 24.04 LTS (or similar Linux distribution)
• Python 3.11 or higher
• Node.js 18 or higher
• PostgreSQL 16
• Nginx (for production)
• Git

Optional:

• Docker & Docker Compose (for containerized deployment)
• Rivendell Radio Automation (for testing integration)

Clone and Setup:

# Clone repository
git clone <repository-url>
cd elf-project
 
# Run quick start script
chmod +x quickstart.sh
./quickstart.sh
 
# Start backend (Terminal 1)
cd backend
source venv/bin/activate
python manage.py runserver 0.0.0.0:9000
 
# Start frontend (Terminal 2)
cd frontend
npm run dev

Access Points:

• Frontend: http://localhost:5173
• Backend API: http://localhost:9000/api
• Django Admin: http://localhost:9000/admin
• API Documentation: http://localhost:9000/api/docs

• ELF Detailed Server Install

Backend Setup:

cd backend
 
# Create virtual environment
python3 -m venv venv
source venv/bin/activate
 
# Install dependencies
pip install -r requirements.txt
 
# Configure database
cp .env.example .env
# Edit .env with your settings
 
# Initialize database
python manage.py migrate
python manage.py createsuperuser
python manage.py collectstatic --noinput

Frontend Setup:

cd frontend
 
# Install dependencies
npm install
 
# Configure API endpoint
echo "VITE_API_URL=http://localhost:9000/api" > .env.local
 
# Start development server
npm run dev

elf-project/
├── backend/                    # Django backend
│   ├── config/                 # Django configuration
│   │   ├── settings.py        # Application settings
│   │   ├── urls.py            # URL routing
│   │   └── wsgi.py            # WSGI configuration
│   ├── elf/                   # Main application
│   │   ├── models.py          # Database models
│   │   ├── api/               # REST API layer
│   │   │   ├── serializers.py # Data serialization
│   │   │   └── views.py       # API endpoints
│   │   └── services/          # Business logic
│   │       ├── rivendell_service.py     # Rivendell sync
│   │       ├── export_service.py        # Log export
│   │       └── scheduling_service.py    # Auto-scheduler
│   ├── requirements.txt       # Python dependencies
│   └── manage.py              # Django CLI
├── frontend/                  # React frontend
│   ├── src/
│   │   ├── components/        # Reusable components
│   │   ├── pages/             # Page components
│   │   ├── services/          # API client
│   │   └── App.jsx            # Main application
│   ├── package.json           # Node dependencies
│   └── vite.config.js         # Build configuration
├── docker-compose.yml         # Docker orchestration
├── README.md                  # Project overview
├── SETUP_GUIDE.md            # Installation guide
├── DEVELOPMENT_GUIDE.md      # Developer documentation
└── TODO.md                   # Development roadmap

Python (Backend):

• Follow PEP 8 style guide
• Use type hints for function parameters and returns
• Docstrings for all classes and public methods
• Maximum line length: 100 characters
• Use Django ORM best practices (select_related, prefetch_related)

JavaScript (Frontend):

• ES6+ syntax with modern features
• Functional components with React Hooks
• Descriptive variable names (camelCase)
• Component files use PascalCase
• Use async/await for asynchronous operations

Database:

• Always create migrations for model changes
• Use database indexes for frequently queried fields
• Foreign keys with appropriate on_delete behavior
• Unique constraints where applicable

Backend Tests:

# Run all tests
python manage.py test
 
# Run specific test
python manage.py test elf.tests.test_models
 
# With coverage
coverage run manage.py test
coverage report

Frontend Tests:

# Run tests
npm run test
 
# Run with coverage
npm run test:coverage

Database Management:

# Create migrations
python manage.py makemigrations
 
# Apply migrations
python manage.py migrate
 
# Access database shell
python manage.py dbshell

Rivendell Integration:

# Sync cart inventory
python manage.py sync_rivendell_carts --station 1 --group-name COMM
 
# Export daily log
python manage.py export_log --date 2024-02-08 --station 1

Status: In Progress

• [✓] Core database models (11 models)
• [✓] RESTful API with full CRUD operations
• [✓] Rivendell cart synchronization
• [✓] Log export service (column-aligned ASCII)
• [✓] Basic auto-scheduling algorithm
• [✓] Django admin interface
• [✓] React frontend structure
• [✓] API client and routing
• [ ] Complete UI implementation
• [ ] User authentication system
• [ ] Comprehensive API tests

Status: Planned

Scheduling Enhancements:

• Advanced rotation algorithms
• Hourly spot limits
• Fixed-position spots (ROS vs. fixed time)
• Makegood tracking and automatic rescheduling
• Schedule conflict detection and resolution

User Interface:

• Full CRUD interfaces for all entities
• Drag-and-drop schedule editor
• Calendar-based schedule view
• Real-time validation
• Dashboard analytics

Integration:

• Multiple Rivendell import format support
• Two-way sync (import as-played data)
• Music scheduler integration prep

Status: Planned

Business Features:

• Multi-user roles and permissions
• Agency portal access
• Rate card management
• Automated billing integration
• Contract and proposal generation

Reporting:

• Affidavits (proof of performance)
• Performance analytics
• Advertiser dashboards
• Comparative analysis reports
• Custom report builder

Scheduling Intelligence:

• Multi-station scheduling from single campaign
• Network-wide campaign management
• Inventory forecasting
• AI-powered optimization suggestions

Status: Future

Infrastructure:

• Multi-tenancy architecture
• Rumble Cloud deployment
• Auto-scaling configuration
• Comprehensive monitoring (Prometheus/Grafana)
• Automated backup and disaster recovery

SaaS Features:

• Subscription management system
• Payment processing (Stripe integration)
• Usage-based billing
• Station onboarding wizard
• Self-service customer portal
• Support ticketing system

Mobile:

• Progressive Web App (PWA)
• React Native mobile application
• Offline capability
• Push notifications

Additional Integrations:

• MusicMaster scheduler
• Selector scheduler
• NexGen automation
• WideOrbit traffic system
• Accounting software (QuickBooks, etc.)

Advanced Features:

• Voice recognition for commercial detection
• Real-time collaboration features
• Slack/Teams notifications
• API webhooks for third-party integration
• Machine learning for schedule optimization
• Predictive analytics for inventory management

Why Django + React?

• Django: Mature, “batteries included” framework with excellent ORM and admin interface. Strong security features and extensive ecosystem.
• React: Component-based architecture perfect for complex UIs. Large community and extensive library ecosystem.
• Decoupled Architecture: Allows independent scaling and development of frontend/backend. Enables future mobile apps using same API.

Why PostgreSQL?

• Advanced query capabilities for complex scheduling logic
• Better support for concurrent writes than SQLite
• JSON field support for flexible data structures
• Excellent performance for reporting queries
• Industry standard for web applications

Why Column-Aligned ASCII Export?

• Standard format supported by Rivendell and legacy systems
• Human-readable for debugging and verification
• Easy to parse by various import tools
• Compatible with older radio automation systems

Auto-Scheduling Algorithm:

• Current implementation uses weighted random selection with separation rules
• Future versions will implement more sophisticated algorithms:
  • Dynamic programming for optimal placement
  • Machine learning for pattern recognition
  • Genetic algorithms for complex constraint satisfaction

Database Connections:

• Rivendell MySQL connection is read-only by default for safety
• Cart sync runs on-demand, not real-time, to minimize database load
• Connection pooling configured for optimal performance

Port Configuration:

• Backend uses port 9000 (configurable in settings)
• Frontend dev server uses port 5173 (Vite default)
• Avoids conflicts with other common services

File System:

• Export path must be accessible by both ELF and Rivendell
• Recommend shared network mount or direct file system access
• Exports use date-based filenames (YYYYMMDD.txt)

Project Origin:

• Created to address lack of affordable traffic systems for small stations
• Inspired by proprietary systems costing $10,000+ per station
• Designed specifically for Rivendell users (open-source automation)
• Intended for free self-hosted use or affordable SaaS offering

Development Philosophy:

• Open-source community benefit
• User-driven feature development
• Professional quality for zero cost
• Extensible architecture for future growth

Current Limitations:

• Auto-scheduler uses basic algorithm (sophisticated version planned)
• No actual authentication implemented yet (security risk in current state)
• Separation rules partially implemented
• Export path validation needed
• Time zone handling requires additional testing
• No multi-user concurrency protection yet

Workarounds:

• Run behind firewall until authentication completed
• Use Django admin for user management temporarily
• Manual schedule review before export recommended
• Test exports thoroughly before going live

How to Contribute:

• Fork the repository on GitHub
• Create feature branch from main
• Follow coding standards outlined above
• Write tests for new features
• Submit pull request with detailed description
• Update documentation as needed

Priority Areas:

• Frontend UI implementation
• Test coverage improvements
• Documentation and tutorials
• Additional import/export formats
• Mobile-responsive design enhancements

Project Resources:

• Website: https://www.amigaz.org/elf
• Documentation: See SETUP_GUIDE.md and DEVELOPMENT_GUIDE.md
• Issue Tracking: GitHub Issues (when repository public)
• Email: [contact information]

Related Projects:

• Rivendell Radio Automation: https://github.com/ElvishArtisan/rivendell
• Rivendell Wiki: https://rivendellaudio.wiki/

Documentation:

• Django Documentation: https://docs.djangoproject.com/
• Django REST Framework: https://www.django-rest-framework.org/
• React Documentation: https://react.dev/
• Rivendell Operations Guide: https://opsguide.rivendellaudio.org/

Standards:

• PEP 8 - Python Style Guide
• REST API Design Best Practices
• PostgreSQL Best Practices
• React Hooks Best Practices

Last Updated: February 19, 2024 Version: 1.0.0-alpha Maintainer: Rich Lawrence