Vultisignal — Daily Ecosystem Monitoring

Streamlined daily monitoring for the Vultisig ecosystem (43+ repositories)

Overview

Vultisignal is a professional monitoring system that collects daily snapshots of GitHub activity across the Vultisig organization and generates comprehensive dashboards for development teams. Built with historical accuracy, data integrity, and developer experience as core principles.

Key Features

• Accurate daily GitHub data collection with forced fresh data to ensure historical reliability
• Enhanced HTML dashboard with comprehensive analytics and clickable GitHub links
• Cross-platform bug detection across iOS/Android/Windows platforms with smart grouping
• High-priority issue tracking with intelligent detection algorithms
• Stale item monitoring for issues/PRs inactive >14 days
• Development activity analysis with repository hotspots and visual metrics
• Historical trend analysis calculated on-demand from daily JSON snapshots
• Contributor activity tracking across all repositories
• Clean CLI interface with proper error handling and status reporting

Configuration

Vultisignal uses a unified YAML configuration file (config.yaml) for all settings.

Quick Start

1. Create config.yaml in the project root:

github:
  org: vultisig
  repos:    # Optional: restrict to specific repos, or leave blank for all
    - vultisig-ios
    - vultisig-android
    - vultisig-windows
    - vultisig-web
  token: ${GITHUB_TOKEN}   # Read from environment variable

1. Set your GitHub token:

export GITHUB_TOKEN='your_github_token_here'

1. Run collection:

python3 vultisignal.py collect --github

Configuration Options

• github.org: GitHub organization name (default: vultisig)
• github.org_title_pref: Display name for dashboard titles (default: uses the org name)
• github.repos: List of specific repositories to monitor. If empty/omitted, monitors all repos in the organization
• github.token: GitHub personal access token (must be set as environment variable for security)

Security: All tokens and secrets are read from environment variables, never stored in the config file.

Architecture

Clean Deployment Model

Vultisignal uses a professional CI/CD architecture:

• main branch: Source code, scripts, and unified configuration
• gh-pages branch: Generated dashboard and documentation (auto-deployed)
• No automated commits to main: Keeps the repository clean and contributor-friendly

Data Pipeline

config.yaml + env vars → GitHub API → Daily Snapshot → Enhanced Dashboard → gh-pages
         ↓                   ↓              ↓                      ↓
    GITHUB_TOKEN    43+ repositories  exports/github/YYYY-MM-DD.json   docs/index.html
                                                                            ↓
                                                              https://username.github.io/vultisignal

Data Flow Diagram

For a comprehensive visual representation of how data flows through the entire Vultisignal system - from GitHub API collection through processing, template rendering, and final deployment - see DATA_FLOW_DIAGRAM.html. This diagram provides an at-a-glance understanding of the complete architecture and is invaluable for onboarding new contributors and making informed architectural decisions.

File Structure

vultisignal/
├── vultisignal.py                       # Main CLI interface
├── collectors/github.py                 # GitHub data collector
├── processors/summarizer.py            # Summary processor
├── scripts/
│   ├── html_generator.py               # Unified HTML dashboard generator
│   └── generate_docs.py                # Documentation generator
├── templates/                           # Jinja2 templates
│   ├── base.html                       # Base template with styling
│   ├── dashboard.html                  # Enhanced dashboard template
│   └── simple_dashboard.html           # Simple dashboard template
├── assets/
│   └── custom.css                      # Custom styling
├── exports/
│   ├── github/YYYY-MM-DD.json          # Daily GitHub snapshots
│   └── metrics_history.json            # Historical metrics
└── docs/
    ├── index.html                       # Generated HTML dashboard
    └── assets/custom.css                # Deployed CSS assets

Enhanced Dashboard

Vultisignal generates a comprehensive HTML dashboard with advanced analytics:

Dashboard Sections

• Summary Overview - Comprehensive metrics including active repositories, issues, PRs, bugs, and high-priority items
• Cross-Platform Bugs - Issues affecting multiple platforms with smart grouping
• High-Priority Issues - Items requiring immediate attention
• Stale Items - Issues/PRs inactive for 14+ days
• Development Activity - Repository hotspots with visual activity bars
• Contributor Activity - Most active developers across all repos
• Recent Releases - Latest releases with proper links
• Active Pull Requests - Open PRs with author and timing info

Technical Features

• Jinja2 template system with unified HTML generator for enhanced maintainability
• Professional theming with Water.css and responsive design
• Native GitHub JSON processing - no unified schema required
• Smart analytics - cross-platform detection, priority scoring
• Error resilient - handles missing/malformed data gracefully
• Local development support - --local flag copies CSS assets automatically
• Automated deployment - Daily updates deployed to gh-pages automatically

CLI Usage

Vultisignal provides a clean command-line interface for all operations:

Data Collection

# Collect GitHub data for today
python3 vultisignal.py collect --github

# Show collection status
python3 vultisignal.py status

Dashboard Generation

# Generate HTML dashboard (production)
python3 vultisignal.py process --html-dashboard

# Generate dashboard for local development (copies CSS assets)
python3 vultisignal.py process --html-dashboard --local

# Generate dashboard for current day
python3 vultisignal.py process --html-dashboard --current

Historical Analysis

# Show 30 days of historical trends
python3 vultisignal.py history

# Show last 7 days only
python3 vultisignal.py history --days 7

Automation

Vultisignal runs completely automatically via GitHub Actions:

• Daily Schedule: Runs at 00:01 GMT every day
• Manual Trigger: Can be run on-demand from GitHub Actions UI
• Push Triggers: Automatically runs when templates, CSS, or core scripts are modified
• Clean Deployment: Publishes to gh-pages branch only, keeps main clean
• Zero Configuration: Works out-of-the-box with minimal setup

Development Notes

Historical Data: We explored generating historical backfill data but encountered GitHub API limitations that made comprehensive historical analysis impractical. Vultisignal focuses on daily-forward monitoring from your start date.

Documentation

Comprehensive project documentation is available as HTML files:

• CHANGELOG.html - Version history and updates
• DASHBOARD_FEATURES.html - Dashboard technical reference
• DATA_FLOW_DIAGRAM.html - System architecture overview
• PROGRAM_STATUS.html - Current capabilities and what the system does
• ROADMAP.html - Future ideas and development plans

Typical Metrics

Monitoring 43+ repositories with typical daily activity:

• Open Issues: ~99 across active repositories
• Active PRs: ~8 in development
• Bug Issues: ~70 identified across platforms
• High Priority: ~1-3 requiring immediate attention

This project follows FLOSS-first philosophy and prioritizes maintainability, clarity, and reproducibility.