GitHub Project Health Analyzer

Analyzes any public GitHub repository and produces a health report covering activity, contributors, dependencies, security, code quality, documentation, and AI-generated insights.

Status: Feature-complete per the original roadmap, plus hardening. Every report section computes end-to-end: Overview, Activity (with a 12-week commit timeline), Contributors, Dependencies, Security, Quality, an AI-generated narrative review, and an overall Health Score composing all of the above. GitHub OAuth login is wired in (higher rate limits, seam for future private-repo support), and repeat analyses of the same repo within REPORT_CACHE_TTL_SECONDS are served from cache instead of re-running the whole pipeline.

Stack

• Frontend: React + TypeScript + Vite + Tailwind CSS + React Query + Recharts
• Backend: FastAPI + SQLAlchemy + Alembic + Pydantic + Celery, Clean Architecture layering
• Database: PostgreSQL (JSONB report sections; SQLite used only in tests via a type variant)
• Queue/Cache: Redis (Celery broker/result backend, rate-limit counters, report-freshness cache)
• Auth: GitHub OAuth via Authlib, signed session cookie, tokens encrypted at rest (Fernet)
• GitHub access: PyGithub, behind a GitHubClient interface (user's OAuth token when logged in, server PAT otherwise)
• Dependency parsing: tomli, requirements-parser, packaging, packageurl-python
• Security: PyYAML for GitHub Actions workflow parsing
• AI/Docs: Anthropic SDK behind the swappable LLMProvider interface; markdown-it-py for safely rendering the AI's README suggestions to HTML

See architecture-roadmap.md for the full architecture, API design, database schema, and phased build history.

Report sections

Section	What it computes	Notes
Overview	Stars/forks/watchers, license, language breakdown, topics, age
Activity	Very Active → Dead classification, weighted explainable score, 12-week commit timeline
Contributors	Top contributors, bus factor, new-contributor trend, maintainer responsiveness
Dependencies	Ecosystem detection + outdated/deprecated checks across 7 ecosystems	Unused-dependency detection explicitly out of scope (needs per-language static analysis)
Security	Published advisories, best-effort Dependabot alerts/branch protection, GitHub Actions hygiene, license-conflict heuristic	Permission-gated signals report accessible: false honestly rather than guessing
Quality	Documentation/structure/test/CI/lint/format/build signals	Code complexity explicitly not computed (would require cloning + running per-language tools against untrusted code)
AI Review	Purpose, architecture summary, strengths/weaknesses, recommendations, next steps, README suggestions	One LLM call per report, worker-only (not a preview endpoint)
Health Score	Weighted composite of Activity/Contributors/Dependencies/Security/Quality	The "overall project score"

Running locally (Docker — recommended)

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
# edit backend/.env - at minimum set GITHUB_PAT and ANTHROPIC_API_KEY
# optional: GITHUB_OAUTH_CLIENT_ID/SECRET for login, TOKEN_ENCRYPTION_KEY if you do

docker compose up --build

This starts four services: db, redis, backend (runs migrations, then serves the API), and worker (the Celery worker - waits for backend to report healthy before starting, so migrations are guaranteed to have run).

• Frontend: http://localhost:5173
• Backend docs (Swagger): http://localhost:8000/docs
• Backend health check: http://localhost:8000/api/v1/health
• GitHub connectivity check (confirms your PAT works): http://localhost:8000/api/v1/repos/_ping
• Fast previews (no persistence, still synchronous): /repos/{owner}/{name}/overview, /repos/{owner}/{name}/activity, /repos/{owner}/{name}/contributors, /repos/{owner}/{name}/dependencies, /repos/{owner}/{name}/security, /repos/{owner}/{name}/quality
• Kick off a full async report (all sections, including AI review and health score): POST /repos/analyze with body {"repo_url": "facebook/react"} → returns 202 with a pending report (or an existing cached one, if analyzed recently); poll GET /reports/{id} until it's completed (or failed)
• GitHub login: visit http://localhost:8000/api/v1/auth/github/login (requires GITHUB_OAUTH_CLIENT_ID/SECRET set - create an OAuth App at https://github.com/settings/developers with callback URL http://localhost:8000/api/v1/auth/github/callback)

Running the worker locally (without Docker)

cd backend
celery -A app.core.celery_app.celery_app worker --loglevel=info

Requires Redis running (docker compose up redis) and the same .env as the API process.

Testing

# Backend (135 tests: unit + integration, no live network/DB/Redis/LLM required)
cd backend && pytest app/tests -q

# Backend lint
cd backend && ruff check app alembic

# Frontend build/typecheck
cd frontend && npm run build

Notable testing patterns used throughout:

• Celery runs in eager mode for tests (task_always_eager), so async worker behavior is exercised without a real broker
• GitHub API calls are faked via a FakeGitHubClient/FakeRepository pair with realistic fixture data, never live network calls
• External registry calls (npm, PyPI, crates.io, Go proxy, Packagist, NuGet, Maven Central) are tested against respx-mocked HTTP responses
• The LLM call is tested via MockProvider (garbage response, to verify graceful degradation) and a FakeLLMProvider (valid JSON, to verify the happy path) - never a real Anthropic API call in tests

Known limitations (intentional, documented in code)

• Dependency/monorepo manifests are only scanned at the repo root, not recursively
• Gradle isn't supported for Java dependency parsing (only Maven pom.xml) - no reliable general-purpose parser exists for its Groovy/Kotlin DSL
• "Unused dependency" and "code complexity" indicators are explicitly not computed - both need language-specific static analysis tooling running against untrusted third-party code, which is out of scope
• License-compatibility flags are a heuristic (strong-copyleft-in-permissive-project), not legal advice - the API response says so explicitly
• Dependabot alerts and branch protection status require repo-admin permissions the server PAT typically won't have on third-party repos; these degrade honestly (accessible: false + a reason) rather than reporting false negatives

Running locally (without Docker)

Backend:

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env   # fill in GITHUB_PAT, ANTHROPIC_API_KEY

# Requires Postgres + Redis running locally, or point DATABASE_URL/REDIS_URL
# at Docker-hosted instances via: docker compose up db redis
alembic upgrade head
uvicorn app.main:app --reload

Frontend:

cd frontend
npm install
cp .env.example .env
npm run dev

Database migrations

cd backend
alembic upgrade head                              # apply all migrations
alembic revision --autogenerate -m "add X column"  # generate a new migration after model changes
alembic downgrade -1                               # roll back one migration

Migrations target Postgres specifically (JSONB columns). Tests don't run migrations at all — they use Base.metadata.create_all() against an in-memory SQLite DB, which is why the Report model's JSON columns use .with_variant(JSON(), "sqlite").

Testing

# Backend
cd backend && pytest app/tests -q

# Backend lint
cd backend && ruff check app alembic

# Frontend build/typecheck
cd frontend && npm run build

Project layout

backend/    FastAPI app (Clean Architecture: api / services / domain / infrastructure)
  alembic/  database migrations
frontend/   React + Vite SPA
docker-compose.yml