git-archeologist

Inspiration

As codebases grow, some files become harder to maintain because they're constantly being changed by different developers. But looking at lines of code or complexity alone doesn't always tell the full story.

I wanted to explore whether a project's Git history could reveal where development friction actually happens. That idea led to GitArchaeologist, a tool that helps developers identify potential architectural problems by looking at how their code changes over time.

What it does

GitArchaeologist analyzes public GitHub repositories and identifies files that may be becoming difficult to maintain.

• Architectural Debt Matrix: Ranks files using commit frequency, contributor diversity, and file size.
• Volatility Timeline: Shows recent commit activity and helps developers understand which files are changing together.
• AI Inspector: Uses Google Gemini to explain potential problem areas and suggest practical refactoring steps.
• Interactive Dashboard: Lets developers filter, sort, and explore hotspots across a repository.
• Reliable Demo Mode: Includes preloaded repository snapshots and a fallback diagnostic engine when the AI service is unavailable.

How we built it

We built the backend with FastAPI and Python to clone repositories, parse Git history, calculate file-level scores, and expose the results through REST APIs.

The frontend uses React, TypeScript, and Tailwind CSS to present the analysis in an interactive dashboard. Google Gemini powers the architectural diagnoses, while a deterministic fallback keeps the core experience working without an API key.

We also added shallow cloning, temporary directory cleanup, error handling, and preloaded datasets to make repository analysis faster and demonstrations more reliable.

Challenges we ran into

The biggest challenge was turning raw Git activity into meaningful insights. A file being modified frequently doesn't necessarily mean it's poorly designed, so we combined several metrics to get a more useful picture.

Handling real-world edge cases was another challenge. Repositories can fail to clone, files can be renamed or deleted, and AI APIs can hit rate limits. We addressed these situations with error handling, resource cleanup, and a fallback diagnostic system.

We also had to balance useful analysis with fast response times, particularly when working with larger repositories.

Accomplishments that we're proud of

We're proud of turning an idea about developer friction into a working, interactive analysis tool rather than another dashboard filled with basic code statistics.

The combination of Git telemetry, an architectural debt matrix, a commit timeline, and AI-generated refactoring suggestions gives developers a way to move from identifying a potential problem to understanding what they might do about it.

We're also proud of making the demo resilient with preloaded repository snapshots and a fallback engine.

What I learned

I learned that a repository's history can reveal patterns that aren't immediately obvious from reading its source code. I also gained practical experience with Git subprocesses, API integration, frontend-backend communication, and incorporating LLMs into a developer-focused application.

Most importantly, I learned that metrics should be treated as signals, not absolute truths. AI can help explain those signals, but the quality of its recommendations depends on the evidence available.

What's next for GitArchaeologist

The next step is to validate the scoring formula against real-world maintenance issues and reduce false positives. I also want to distinguish routine changes, such as dependency updates, from changes that may indicate deeper architectural problems.

Future improvements could include code ownership analysis, test coverage, change coupling, and comparisons between repositories over time.

The long-term goal is to help developers understand not just which files change most often, but why those files might be difficult to maintain and where refactoring would have the greatest impact.

Built With

• https://github.com/m-wajeeh/git-archaeologist