Skip to main content

README

BlueFly.io Status Dashboard

Automated real-time status dashboard for BlueFly.io platform using GitLab API.

Features

  • Real-time GitLab data collection (epics, issues, MRs, pipelines)
  • Health score calculation with trends
  • Automated markdown dashboard generation
  • Blocker detection and alerts
  • Scheduled updates (hourly)
  • CLI for manual operations

Installation

cd /Volumes/AgentPlatform/wikis/blueflyio/technical-docs.wiki/tools/status-dashboard

# Install dependencies
npm install

# Build TypeScript
npm run build

Configuration

Create .env file:

GITLAB_TOKEN=your_gitlab_personal_access_token
GITLAB_GROUP=blueflyio
OUTPUT_PATH=../../action-items/status
INTERVAL_MINUTES=60
NOTIFY_ON_BLOCKERS=true

Usage

Generate Dashboard (One-time)

# Generate all dashboards
npm run generate

# Or use tsx directly
tsx src/cli.ts generate --token YOUR_TOKEN

Quick Status Check

tsx src/cli.ts status

Collect Data Only

tsx src/cli.ts collect -o data.json

Calculate Health Metrics

tsx src/cli.ts health -i data.json -o health.json

Run Scheduler (Continuous)

# Run scheduler (updates every hour)
npm run schedule

# Or customize interval
INTERVAL_MINUTES=30 npm run schedule

Output Files

Generated in ../../action-items/status/:

  • LIVE-DASHBOARD.md - Main dashboard with all metrics
  • HEALTH-TRENDS.md - Health trends and recommendations
  • BLOCKER-ALERTS.md - Critical blocker alerts

CLI Commands

status-dashboard generate [options]    # Generate complete dashboard
status-dashboard collect [options]     # Collect GitLab data
status-dashboard health [options]      # Calculate health metrics
status-dashboard status [options]      # Quick status summary

Options

-o, --output <path>    Output directory (default: ../../action-items/status)
-t, --token <token>    GitLab token (or use GITLAB_TOKEN env var)
-g, --group <group>    GitLab group (default: blueflyio)
-i, --input <file>     Input JSON file

Automation

Cron Job (Hourly Updates)

# Add to crontab
0 * * * * cd /Volumes/AgentPlatform/wikis/blueflyio/technical-docs.wiki/tools/status-dashboard && npm run generate

# Or use scheduler (recommended)
# Run as background service with systemd, pm2, or Docker

Docker (TODO)

docker build -t status-dashboard .
docker run -e GITLAB_TOKEN=xxx -v /path/to/output:/output status-dashboard

Health Metrics

Scoring System

  • Epic Progress (25% weight)

    • On track: 100 points
    • At risk: 50 points
    • Blocked: 0 points

  • Issue Velocity (25% weight)

    • Based on close rate vs open rate
    • Higher velocity = higher score

  • MR Health (20% weight)

    • Lower draft ratio = higher score
    • Fewer conflicts = higher score

  • Pipeline Health (20% weight)

    • Success rate directly mapped to score

  • Blockers (10% weight)

    • Critical: -10 points each
    • High: -5 points each
    • Medium: -2 points each

Health Badges

  • 🟢 Healthy (80-100)
  • 🟡 Warning (60-79)
  • 🟠 At Risk (40-59)
  • 🔴 Critical (0-39)

Architecture

┌─────────────────────┐
│  GitLab API         │
│  (blueflyio group)  │
└──────────┬──────────┘
           │
           v
┌─────────────────────┐
│  Data Collector     │
│  - Fetch epics      │
│  - Fetch issues     │
│  - Fetch MRs        │
│  - Fetch pipelines  │
└──────────┬──────────┘
           │
           v
┌─────────────────────┐
│  Health Calculator  │
│  - Epic progress    │
│  - Issue velocity   │
│  - MR health        │
│  - Pipeline health  │
│  - Blocker analysis │
└──────────┬──────────┘
           │
           v
┌─────────────────────┐
│  Dashboard Generator│
│  - LIVE-DASHBOARD   │
│  - HEALTH-TRENDS    │
│  - BLOCKER-ALERTS   │
└──────────┬──────────┘
           │
           v
┌─────────────────────┐
│  Markdown Files     │
│  (action-items/status)│
└─────────────────────┘

Development

# Watch mode
npm run dev

# Build
npm run build

# Run built version
npm start

GitLab Token Permissions

Required scopes:

  • read_api - Read GitLab API data
  • read_repository - Read repository data (optional)

Create token at: https://gitlab.com/-/profile/personal_access_tokens

Troubleshooting

"No data returned"

  • Check GitLab token permissions
  • Verify group name is correct
  • Ensure group has epics/issues

"Permission denied"

  • Token may be expired
  • Token may lack required scopes

"Rate limit exceeded"

  • Reduce update frequency
  • Use GraphQL API (TODO)

Future Enhancements

  • GraphQL API for better performance
  • Slack/email notifications
  • Historical data storage (database)
  • Advanced trend analysis
  • Custom dashboard templates
  • Docker image
  • Web UI dashboard
  • Real-time WebSocket updates

License

MIT