Amiga-Z Wiki

“Modern tools for old-school communities.”

User Tools

Site Tools

Trace:
projects:trafficelf

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
projects:trafficelf [2026/02/04 14:24] – created freedomotterprojects:trafficelf [2026/02/25 14:44] (current) – [Development Setup] freedomotter
Line 1: Line 1:
-====== Traffic Elf ======+{{:projects:elf_logo_small.png?100|}} 
 +====== ELF - Elfish Log Factory ====== 
 +//**"Commercial traffic shouldn’t be this hard"**//
  
-Traffic Elf is a web-based commercial traffic, client, and campaign management system designed for small to medium radio stations.+===== Overview ===== 
 +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 goal of Traffic Elf is to provide a lightweight, modern, browser-based alternative to legacy radio traffic systems, focusing on: +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.
-  * Client management +
-  * Campaign tracking +
-  * Commercial scheduling (future) +
-  * Simple, grid-based workflows +
-  * Local or self-hosted deployment+
  
-----+**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
  
-===== System Overview =====+===== Status ===== 
 +^ Item ^ Value ^ 
 +| Current Phase | Active Development (MVP Phase 1) | 
 +| Platform | Cross-platform (Linux primary, Ubuntu 24.04 recommended) | 
 +| Backend Language | Python 3.11+ (Django 5.0) | 
 +| Frontend Language | JavaScript (React 18) | 
 +| Database | PostgreSQL 16 | 
 +| License | MIT (intended for open-source release) | 
 +| Version | 1.0.0-alpha | 
 +| Primary Integration | Rivendell Radio Automation |
  
-Traffic Elf is built as a classic web application:+===== Goals =====
  
-  * Frontend: HTML, CSS, JavaScript +==== Primary Goals ==== 
-  * Backend: PHP (API layer) +  * **Free Traffic System**: Provide small/medium radio stations with professional traffic scheduling at no cost 
-  * Database: MySQL +  * **Rivendell Integration**: Seamless bi-directional integration with Rivendell automation systems 
-  * UI Pattern: Sidebar + flyout menus + tabbed grids+  * **Ease of Use**: Modern, intuitive web interface requiring minimal training 
 +  * **Multi-Station Support**: Single installation can manage multiple radio stations
  
-High-level flow:+==== Secondary Goals ==== 
 +  * **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
  
-  UI (Browser) +==== Long-Term Goals ==== 
-      ↓ +  * **Network Scheduling**: Chain-wide campaign management across multiple markets 
-  JavaScript Grid Loader +  * **Advanced Analytics**: Performance reporting and business intelligence 
-      ↓ +  * **Music Scheduler Integration**: Support for MusicMaster, Selector, and other systems 
-  PHP API Endpoints +  * **Mobile Applications**: Native iOS/Android apps for on-the-go management 
-      ↓ +  * **AI-Powered Optimization**: Machine learning for schedule optimization and recommendations
-  MySQL Database+
  
-----+===== Architecture =====
  
-===== Current Features =====+==== System Design ==== 
 +ELF follows a modern, decoupled three-tier architecture:
  
-  * Sidebar-based navigation +<code> 
-  * Flyout menu system +┌─────────────┐      ┌──────────────┐      ┌─────────────┐ 
-  * Grid views for Clients and Campaigns +│   React     │─────▶│    Django    │─────▶│ PostgreSQL  │ 
-  * Multiple grids open simultaneously (tabbed interface) +│  Frontend   │ HTTP │  REST API    │ SQL  │  Database   │ 
-  * MySQL-backed data storage+│  (Port 5173)│◀─────│  (Port 9000) │◀─────│             │ 
 +└─────────────┘ JSON └──────────────┘      └─────────────┘ 
 +                            │ 
 +                            │ MySQL 
 +                            ▼ 
 +                      ┌──────────────┐ 
 +                      │  Rivendell   │ 
 +                      │   Database   │ 
 +                      └──────────────┘ 
 +                            │ 
 +                            ▼ 
 +                      ┌──────────────┐ 
 +                      │  Export Logs │ 
 +                      │  (ASCII)     │ 
 +                      └──────────────┘ 
 +</code>
  
-----+==== Technology Stack ====
  
-===== Documentation =====+**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)
  
-  * [[trafficelf:database|Database Schema & SQL Setup]] +**Frontend:** 
-  * [[trafficelf:development|Development Environment]] +  * **Framework**: React 18 with Vite build tool 
-  * [[trafficelf:ui|User Interface & Grid System]] +  * **UI Library**: Tailwind CSS for styling 
-  * [[trafficelf:api|API Design]] +  * **Routing**: React Router DOM 
-  * [[trafficelf:roadmap|Roadmap & Future Features]]+  * **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)
 +
 +==== Database Schema ====
 +
 +**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
 +
 +==== API Structure ====
 +
 +**RESTful Endpoints:**
 +<code>
 +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
 +</code>
 +
 +==== Rivendell Integration ====
 +
 +**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):**
 +<code>
 +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
 +</code>
 +
 +**Import Process:**
 +  - ELF exports to configured path (e.g., /var/elf/exports/20240208.txt)
 +  - Rivendell's RDLogManager imports via configured template
 +  - Merges with music schedule from RDLibrary
 +
 +===== Development =====
 +
 +==== Prerequisites ====
 +
 +**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)
 +
 +==== Quick Start ====
 +
 +**Clone and Setup:**
 +<code bash>
 +# 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
 +</code>
 +
 +**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
 +
 +==== Development Setup ====
 +
 +  * [[trafficelf:detail_install|ELF Detailed Server Install]]
 +
 +**Backend Setup:**
 +<code bash>
 +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
 +</code>
 +
 +**Frontend Setup:**
 +<code bash>
 +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
 +</code>
 +
 +==== Project Structure ====
 +
 +<code>
 +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
 +</code>
 +
 +==== Coding Standards ====
 +
 +**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
 +
 +==== Testing ====
 +
 +**Backend Tests:**
 +<code bash>
 +# 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
 +</code>
 +
 +**Frontend Tests:**
 +<code bash>
 +# Run tests
 +npm run test
 +
 +# Run with coverage
 +npm run test:coverage
 +</code>
 +
 +==== Common Commands ====
 +
 +**Database Management:**
 +<code bash>
 +# Create migrations
 +python manage.py makemigrations
 +
 +# Apply migrations
 +python manage.py migrate
 +
 +# Access database shell
 +python manage.py dbshell
 +</code>
 +
 +**Rivendell Integration:**
 +<code bash>
 +# 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
 +</code>
 +
 +===== Roadmap =====
 +
 +==== Phase 1: MVP Foundation (Current) ====
 +**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
 +
 +==== Phase 2: Core Features (Next 2 Months) ====
 +**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
 +
 +==== Phase 3: Advanced Features (Months 3-6) ====
 +**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
 +
 +==== Phase 4: Cloud & SaaS (Months 6-12) ====
 +**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
 +
 +==== Future Enhancements ====
 +
 +**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
 +
 +===== Notes =====
 +
 +==== Design Decisions ====
 +
 +**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
 +
 +==== Technical Constraints ====
 +
 +**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)
 +
 +==== Historical Context ====
 +
 +**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
 +
 +==== Known Issues ====
 +
 +**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
 +
 +==== Contributing ====
 +
 +**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
 +
 +==== Contact & Support ====
 +
 +**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/
 +
 +==== References ====
 +
 +**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//
projects/trafficelf.1770215074.txt.gz · Last modified: by freedomotter
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki