Backend Overview

Status: Active Last Updated: 2025-11-10 Related Docs: EPG Generation Guide, Quick Start Code Location: backend/

Internal tooling for IPTV service management and EPG generation

Overview

The backend/ directory contains the core engineering tools for the EPGOAT platform. These tools handle M3U playlist management, EPG (Electronic Program Guide) generation, provider configuration, and API services.

Directory Structure

backend/
├── config/                    # YAML configuration files
│   ├── sport_emojis.yml      # Sport emoji mappings (89 entries)
│   ├── sport_categories.yml  # XMLTV category mappings (77 entries)
│   └── channel_patterns.yml  # Channel pattern definitions
│
├── epgoat/                    # EPG Generator - Main Package
│   ├── epg_generator.py      # Main EPG generator
│   ├── domain/               # Core business logic
│   │   ├── models.py         # Data models and constants
│   │   ├── config.py         # Configuration loader
│   │   ├── patterns.py       # Pattern matching (100+ patterns)
│   │   ├── parsers.py        # M3U and time parsing
│   │   ├── schedulers.py     # Programme scheduling
│   │   ├── xmltv.py          # XMLTV generation
│   │   └── schemas.py        # Pydantic validation
│   ├── services/             # Business services
│   ├── infrastructure/       # External dependencies
│   ├── application/          # High-level workflows
│   ├── cli/                  # Command-line interfaces
│   ├── tests/                # Test suite (250+ tests)
│   └── utilities/            # Helper scripts
│
└── README.md                 # This file

Key Tools

1. EPG Generator

Location: backend/epgoat/

Purpose: Generates XMLTV-formatted Electronic Program Guides from M3U playlists by parsing channel names and extracting event information.

Key Features: - Pattern-based channel matching for 100+ sport leagues - Intelligent time extraction with timezone conversion - Smart programme scheduling (pre-event, live, post-event blocks) - Schema validation for configuration integrity - Comprehensive test coverage (250+ tests) - Modular design with 6 specialized modules

Quick Start:

cd backend/epgoat
python epg_generator.py --m3u playlist.m3u --tz "America/Chicago"

Full Documentation: EPG Generation Guide

2. Configuration Management

Location: backend/config/

Purpose: Centralized YAML configuration for sport mappings and channel patterns.

Files:

sport_emojis.yml: Maps sport families to emoji icons
89 mappings covering basketball, football, soccer, hockey, etc.
Used for visual event identification in EPG
Required _default key for fallback
sport_categories.yml: Maps sport families to XMLTV categories
77 hierarchical category mappings
Format: Sports / <Sport Type> / <League>
Required _default key for fallback

Schema Validation:

All configuration files are validated using Pydantic schemas to ensure: - Required keys are present (_default) - Emoji values are valid unicode characters - Categories follow hierarchical format - No empty or malformed entries

Architecture

Modular Design

The EPG Generator follows a clean, modular architecture with Domain-Driven Design (DDD):

Input (M3U) → Parser → Pattern Matcher → Time Extractor
                                ↓
                         Schedule Builder
                                ↓
                         XMLTV Generator → Output (XML)

Each module has a single, well-defined responsibility:

Module	Responsibility	Lines	Location
`models.py`	Data structures and constants	72	`domain/`
`config.py`	Configuration loading	90	`domain/`
`patterns.py`	Pattern matching & classification	300	`domain/`
`parsers.py`	M3U parsing & time extraction	374	`domain/`
`schedulers.py`	Programme scheduling	372	`domain/`
`xmltv.py`	XML document generation	115	`domain/`
`schemas.py`	Schema validation	170	`domain/`

Key Technologies

Python 3.11+ with 100% type hints
zoneinfo for timezone handling (Python stdlib)
PyYAML for configuration management
Pydantic for schema validation
pytest for comprehensive testing

Design Patterns

Domain-Driven Design (DDD): Core business logic in domain/
Repository Pattern: Data access in infrastructure/database/
Service Layer: Business services in services/
Dependency Injection: Clean separation of concerns

Common Tasks

Generate EPG for Today

cd backend/epgoat
python epg_generator.py --m3u /path/to/playlist.m3u --tz "America/Chicago"

Generate EPG for Specific Date

python epg_generator.py --m3u playlist.m3u --tz "America/Chicago" --date 2025-11-10

Add New Sport Pattern

Edit backend/config/sport_emojis.yml: yaml new-league: '⚽'
Edit backend/config/sport_categories.yml: yaml new-league: 'Sports / Soccer / New League'
Edit backend/epgoat/domain/patterns.py: python ALLOWED_CHANNEL_PATTERNS = [ # ... existing patterns ... (r'^NEW-LEAGUE\s+\d+\s*:?', 'NEW-LEAGUE'), ]
Add tests to backend/epgoat/tests/test_patterns.py

See EPG Generation Guide for detailed instructions.

Run Tests

cd backend/epgoat

# Run all tests
pytest -v

# Run specific test file
pytest tests/test_patterns.py -v

# Run with coverage
pytest --cov=. --cov-report=html

Development Workflow

Code Style

Python 3.11+ required
Type hints required (100%)
Google-style docstrings for all public functions
Max line length: 100 characters
Use logging instead of print()
Follow Python Standards

Git Workflow

Create feature branch: git checkout -b feature/my-feature
Implement changes with tests
Run full test suite: pytest
Run linting: make lint (from repository root)
Commit with descriptive message (conventional commits format)
Push and create pull request

Testing Requirements

All new features must include: - Unit tests for new functions - Integration tests if applicable - Updated documentation - No regression in existing tests - 80%+ code coverage

Performance

Benchmarks (Approximate)

M3U parsing: ~1000 channels/second
Pattern matching: ~500 channels/second
Schedule building: ~1000 channels/second
XMLTV generation: ~2000 channels/second

Scalability

✅ Tested with playlists up to 5,000 channels
⚠️ For 10,000+ channels, consider multiprocessing
💾 Memory usage: ~1MB per 1000 channels

Troubleshooting

Common Issues

Issue: Module import errors

# Ensure you're in the correct directory
cd backend/epgoat

# Check Python path
python -c "import sys; print(sys.path)"

Issue: Configuration validation fails

# Check config syntax
python -c "from backend.epgoat.domain.config import SPORT_EMOJIS; print(len(SPORT_EMOJIS))"

# Validate manually
python -c "from backend.epgoat.domain.schemas import validate_sport_emojis; from backend.epgoat.domain.config import load_sport_config; validate_sport_emojis(load_sport_config('sport_emojis.yml', validate=False))"

Issue: Timezone errors

# List available timezones
python -c "from zoneinfo import available_timezones; print(sorted(available_timezones())[:10])"

# Common US timezones:
# - America/New_York (ET)
# - America/Chicago (CT)
# - America/Denver (MT)
# - America/Los_Angeles (PT)

See EPG Generation Guide for more troubleshooting tips.

Dependencies

See backend/epgoat/requirements.txt for full list:

pyyaml>=6.0 - YAML configuration parsing
requests>=2.31.0 - HTTP requests for M3U fetching
pydantic>=2.0.0 - Schema validation
pytest>=7.4.0 - Testing framework
pytest-cov>=4.1.0 - Coverage reporting

EPG Generation Guide - Detailed EPG generation documentation
Command Reference - All CLI commands
Quick Start - Getting started guide

Resources

XMLTV Specification - XMLTV format reference
M3U Format - M3U playlist format
TheSportsDB API - Sports data API

Last Updated: 2025-11-10 Version: 3.0.0 (Documentation Migration) Migration: Migrated from backend/README.md in Phase 4.3