System Overview & Architecture

Pluvira is a modular, high-performance live media aggregator, programme schedule manager, and stream router designed for self-hosted home servers, local edge appliances, and network-attached storage (NAS).

The platform ingests, normalizes, rewrites, and exports multimedia playlists and XMLTV EPG guides through an optimized SQLite relational engine, accessible via a local single-container application and a responsive WebUI.

1. Core Architecture & Data Pipeline

Pluvira decouples playlist ingestion from runtime client presentation to ensure sub-millisecond channel lookups and resilient streaming delivery:

[Remote Feeds & Dynamic Web Streams]
          │
          ▼
 [Update Ingestion Engine] ──► [SQLite WAL Storage]
                                      │
                                      ▼
                             [DataProcessor Pipeline]
                             • Cascading Rewrites
                             • Intelligent EPG Matching
                             • Link Status Tracking
                                      │
                                      ▼
                             [RAM Disk Cache Driver]
                                      │
                 ┌────────────────────┴────────────────────┐
                 ▼                                         ▼
         [Dynamic Exports]                         [Responsive WebUI]
       (/export/m3u, /export/xml)                  (Local / Remote E2EE)

Relational SQLite WAL Engine

Thread-Safe Operations: Employs SQLite in Write-Ahead Logging (WAL) mode with generous busy-timeout configurations, ensuring concurrent reads never block background synchronization.
Separation of Concerns: Distinct relational databases segregate core configuration, EPG schedules, stream reachability metrics, and update history.
Blind License Security: License keys are stored exclusively as irreversible cryptographic hashes on the SaaS layer, keeping cleartext credentials inside local signed tokens.

Zero-I/O In-Memory Caching

RAM Disk Processing (tmpfs): All playlist parsing, gzip decompressions, and temporary operations occur in volatile RAM storage under /dev/shm.
Atomic Serialization: Configuration and playlist states utilize write-then-rename filesystem replacement, protecting physical storage hardware from micro-write wear.

Piggybacked System Bulletins (RFC-2026-CLOUD-BULLETIN-01)

Ad-Blocker Resilient Delivery: Non-intrusive advisories and update notifications travel piggybacked directly inside periodic heartbeat HTTPS responses (POST /api/v1/license/heartbeat), bypassing Pi-hole, AdGuard, and browser content blockers.
Three-Stage Lifecycle & SQLite WAL Persistence: Bulletins transition through received → read → dismissed states. Notifications are cached in SQLite WAL, remaining readable offline during network outages.

Zero-PII In-App Helpdesk (Chatwoot Engine)

Cryptographic Identity Verification: In-app support chat authenticates users via HMAC-SHA256(user_id, CHATWOOT_HMAC_TOKEN), preventing user spoofing while collecting zero email addresses or cleartext IP logs.
Selective Access: Direct embedded helpdesk widget is rendered exclusively for paired instances with a verified Crockford Base32 UID (XXXX-XXXX-XXXX).

2. Business Source License 1.1 (BSL) Model

Pluvira is released under the Business Source License 1.1 (BSL), providing transparent code visibility while establishing clear distinctions between personal self-hosted usage and commercial deployments.

Personal Free Tier Thresholds

For personal, non-commercial self-hosted use, the free tier provides full access to core features within the following local resource thresholds:

Resource Constraint	Free Tier Limit	Pro Tier
Active Inbound M3U Playlists	Maximum 2 sources	Unlimited
Personal Curated Playlists	1 list (`default`)	Unlimited
Total Ingested Channels (DB)	Maximum 2,500 channels	Unlimited
Curated Playlist (“My List”)	Maximum 25 active channels	Unlimited
Failover Stream Slots	Maximum 2 slots (Primary + Backup)	Up to 7 slots (Automated pool)
Concurrent Stream Views	Maximum 2 active IPs	Scalable (3 to 10 IPs)
Native Cluster Optimization	Standard Engine	Native Rust Acceleration
XMLTV Guide Ingestion	Python Streaming (iterparse)	Native Rust Turbo Engine (~3s)
14-Day Free Pro Trial	On-demand (no credit card)	Full capabilities unlocked
Encrypted Remote WebUI	LAN only	End-to-End Encrypted WebRTC

5-Year Open Source Conversion

Each released version under BSL 1.1 automatically converts to the permissive Apache License 2.0 exactly 60 months (5 years) after its initial public release date.