GitFlow

Overview

Most developers have no real visibility into their own commit habits beyond scrolling through git log. GitFlow was built to close that gap — it tracks one or more Git repositories, scrapes commit metadata across all branches, and runs that data through an analytics engine that surfaces daily/weekly/monthly stats, a 0–100 productivity score, coding-pattern detection (peak hours, most active days, hot files), and per-author commit streaks. It's designed to run standalone as a CLI tool, but also ships an optional FastAPI + React dashboard for anyone who wants live charts instead of terminal tables.

The project spans the full stack of a real production tool rather than a script: a persistent SQLite database with Alembic migrations, a background scheduler for automated scraping and digests, rate-limited and authenticated REST/WebSocket endpoints, Docker deployment, and a test suite of 99 tests across 11 files at 85% coverage.

System Architecture

GitFlow is organized into five layers that build on each other:

• Core CLI (Python Click) — the primary interface; wraps the scraper, analytics engine, and reporting into user-facing commands
• Data Processing — a Git repository walker and commit/diff parser feeding an analytics engine that handles pattern detection and anomaly flags
• Database Layer (SQLite + SQLAlchemy) — stores repositories, commits, files, cached daily/weekly/monthly stats, streaks, and optional task/annotation links, versioned through Alembic migrations
• Background Service (APScheduler) — runs hourly commit scraping, midnight stat caching, and an 8 AM digest notification, entirely independent of whether the dashboard is open
• Web Dashboard (optional) — a FastAPI backend exposing REST + WebSocket endpoints, paired with a React + Recharts frontend for real-time visualization

Core Features

• Repository Scanning — auto-discovers tracked repos and pulls commits across every branch, capturing files changed, insertions/deletions, merge status, and branch info
• Productivity Scoring — a weighted 0–100 daily score: commit frequency (30%), message quality (30%, conventional format + length), file diversity (20%), and time consistency (20%)
• Pattern & Streak Detection — identifies peak coding hours, most active weekdays, hot files, and tracks consecutive commit-day streaks per author
• Rich CLI Reporting — daily, weekly, monthly, and pattern reports rendered as formatted, colored terminal tables, plus CSV/JSON/Markdown export
• Interactive Setup Wizard — walks through adding repos, configuring Slack/email notifications, setting analytics thresholds, and choosing a UI theme on first run
• Background Automation — hourly scraping, nightly stat caching, and a morning desktop-notification digest, all scheduler-driven with no manual trigger needed
• Web Dashboard — real-time summary cards, a 30-day commit trend chart, productivity score trend, repository breakdown, and a live pattern panel, updated over WebSocket every 30 seconds
• API Authentication & Rate Limiting — Bearer-token auth for dashboard endpoints plus SlowAPI-based per-endpoint rate limits (10–100 req/min)
• Search & Filtering API — full-text search plus multi-dimensional filtering by author, repo, date range, and language, with pagination
• Health & Readiness Checks — Kubernetes-ready /health, /health/live, and /health/ready endpoints reporting API, database, and scraper status
• Database Migrations — Alembic-backed schema versioning with migration create/upgrade/downgrade/history CLI commands
• Notifications — real Slack webhook and SMTP email digest delivery, not just log output
• Docker Support — containerized deployment via docker-compose, with repo volumes mounted read-only and the background service running by default

CLI Reference (selected)

gitflow add ~/projects/myapp          # track a repository
gitflow scan --since 7days             # scan for new commits
gitflow report daily                    # today's stats + productivity score
gitflow report weekly --weeks 4          # weekly summaries
gitflow report streaks                    # per-author commit streaks
gitflow report patterns --days 30          # peak hours, hot files
gitflow export --format markdown --days 30  # export commit data
gitflow init-service                         # start the background scheduler
gitflow dashboard --port 3000                 # launch the web dashboard
gitflow token generate                         # generate a dashboard API token
gitflow migration upgrade                       # apply pending schema migrations
gitflow status                                   # full component health check

Productivity Score Algorithm

The daily score is a weighted composite rather than a raw commit count, deliberately designed to reward consistency and quality over volume:

Testing & Reliability

The project carries a genuine test suite rather than a token one — 99 unit tests across 11 files (scraper, analytics engine, CLI commands, API hardening, auth, background service, config, health checks, migrations, notifications) at 85% coverage, run via pytest with HTML coverage reporting.

Tech Stack

Python · Click · SQLAlchemy + SQLite · Alembic · APScheduler · FastAPI + WebSocket · Pydantic · SlowAPI · React + Recharts · Docker + docker-compose