Contributing

Contributing

Thanks for your interest in contributing to DOCSight! Please read this before submitting code.

For the full guide, see CONTRIBUTING.md in the repository.

Before You Start

Open an issue first before working on any new feature or significant change. This lets us discuss the approach and make sure it fits the project direction. PRs without a prior issue may be closed.

Small bugfixes and typo corrections are fine without an issue.

Guidelines

• One PR per feature/fix. Don't bundle unrelated changes.
• Keep changes focused and minimal.
• Add tests for new functionality.
• Maintain all 4 language translations (EN/DE/FR/ES) in app/i18n/*.json.
• Run the full test suite before submitting a PR.
• AI-generated bulk PRs without prior discussion will not be merged.

Development Setup

git clone https://github.com/itsDNNS/docsight.git
cd docsight
pip install -r requirements.txt
pip install pytest
python -m pytest tests/ -v

Docker Dev Environment

docker compose -f docker-compose.dev.yml up -d --build

Dev container runs on port 8766 (production uses 8765).

Project Structure

app/
  main.py            -- Entrypoint, polling loop, thread management
  web.py             -- Flask routes and API endpoints
  analyzer.py        -- DOCSIS channel health analysis
  config.py          -- Configuration management (env + config.json)
  storage.py         -- SQLite snapshot storage
  event_detector.py  -- Signal anomaly detection
  mqtt_publisher.py  -- MQTT Auto-Discovery for Home Assistant
  report.py          -- Incident Report PDF generator (fpdf2)
  speedtest.py       -- Speedtest Tracker API client
  thinkbroadband.py  -- BQM integration
  gaming_index.py    -- Gaming Quality Index scoring
  collectors/        -- Unified collector framework
    base.py          -- BaseCollector with interval/retry logic
    modem.py         -- DOCSIS modem data collector
    speedtest.py     -- Speedtest Tracker collector
    bqm.py           -- ThinkBroadband BQM collector
    demo.py          -- Synthetic data for demo mode
  drivers/           -- Modem driver implementations
    base.py          -- ModemDriver abstract base class
    fritzbox.py      -- AVM FRITZ!Box (data.lua API)
    tc4400.py        -- Technicolor TC4400 (HTTP + HTML scraping)
    ultrahub7.py     -- Vodafone Ultra Hub 7 (AES-CCM + JSON)
    vodafone_station.py -- Vodafone Station CGA/TG (auto-detection)
  i18n/              -- Translation files (EN/DE/FR/ES JSON)
  fonts/             -- Bundled DejaVu fonts for PDF generation
  templates/         -- Jinja2 HTML templates
  static/            -- CSS, JS, icons
tests/               -- pytest test suite

Collector Architecture

DOCSight v2 uses a unified collector framework where each data source (modem, speedtest, BQM) is an independent collector with its own poll interval, retry logic, and failure tracking.

All collectors inherit from BaseCollector and implement collect(). The main polling loop ticks every second and lets each collector decide when it's time to poll via should_poll(). This keeps the orchestrator flat and simple while supporting different intervals per source.

To add a new data source, create a collector in app/collectors/ and register it in app/collectors/__init__.py. See the existing collectors for the pattern.

For adding new modem drivers, see Adding Modem Support.

Building Modules

Since v2026-02-28, DOCSight supports a module system. Modules are self-contained feature packages that can add API endpoints, data collectors, settings panels, and more — without modifying core code.

If your feature is independent from core DOCSIS monitoring, building it as a module is the preferred approach:

• Module System Overview — how modules work, managing installed modules
• Community Module Registry — starter template, manifest reference, contribution types, testing, and submission process
• Study the built-in modules for real-world examples