Create Next App

Most teams only discover code quality problems during code review or worse, in production. Every team has a linter. Most run static analysis in CI. And yet, codebases quietly accumulate debt a function that's grown into 400 lines, a module that only one person truly understands, a pull request that sneaks in cyclomatic complexity no one caught. The issue isn't that tools don't exist. It's that they fire too late, or require someone to manually go look. CodeHealth-AI was built to answer one question: what is the actual health of this codebase, right now and where is it headed?

CodeHealth-AI is a developer intelligence platform that connects to your GitHub repositories and continuously monitors their health. It runs deep static analysis on every push and pull request, scores the codebase on a 0–100 health scale, and surfaces AI-generated recommendations in plain English. Think of it as a fitness tracker for your repository not a one-time audit, but a continuous signal you can trend over time.

The overall health score is a weighted composite across four dimensions. Code quality carries 45% of the weight, computed from cyclomatic complexity, Halstead volume, maintainability index, and lines-of-code penalties at the file level. Development activity accounts for 25%, measuring commit velocity, consistency, and activity ratios. Bus factor contributes 15% if one contributor accounts for over 70% of commits in a module, the system flags it as high-risk. Community health (stars, forks, watchers) makes up the remaining 15%, scaled logarithmically to avoid bias toward popular repositories. Scores above 85 are excellent; below 40 means something needs immediate attention.

The architecture was designed around one hard constraint: analysis jobs must never block API requests. The system has four layers. The Next.js frontend on Vercel receives sub-second dashboard updates via Socket.io. An Express API server on Heroku handles GitHub OAuth, webhook ingestion, and WebSocket broadcasting through Redis Pub/Sub. A separate BullMQ worker dyno orchestrates analysis jobs and runs cron tasks hourly activity aggregation, PR velocity calculation, and database cleanup. At the bottom, a FastAPI + Python engine runs Radon and Lizard for static analysis, calculates per-file risk scores, and calls Together AI and Gemini to generate human-readable recommendations.

When a developer pushes to a connected repository, the flow is: GitHub fires a webhook → the API validates the signature and extracts changed files → a BullMQ job is queued with only the modified files (not the full repo) → a worker fetches file contents from the GitHub API and batches them to the Python engine → FastAPI runs Radon to compute cyclomatic complexity and maintainability index → results are persisted, the health score is recalculated, and the alert system checks all active threshold rules → Redis Pub/Sub notifies the API server, which pushes a WebSocket event to connected clients dashboard updates in under a second.

The most interesting engineering decisions were in the backend. Worker isolation means a slow repo scan has zero impact on API response times the queue absorbs spikes. Incremental re-analysis means only changed files are sent to the Python engine on push events, keeping analysis fast for most repos. The health score calculation involves multiple independent queries that run concurrently rather than sequentially, keeping dashboard loads low under traffic. The alert engine evaluates all active threshold rules on every analysis completion and fires email and in-app notifications on breach resolved alerts auto-archive after 7 days. All of this runs across four separately deployed services, coordinated entirely through Redis and BullMQ.