Replay Git Explorer

Replay turns GitHub commit history into actionable Python code-health insights- without cloning the repository.

Comment

Replay

Inspiration

Software repositories tell the story of a project's evolution, but traditional Git tools only expose commits and diffs. We wanted to answer a deeper question:

How did the software architecture evolve over time?

Replay was inspired by the idea of making software evolution visible—not just code changes, but how complexity, maintainability, dependencies, and engineering health transformed throughout a repository's lifetime. Our goal was to build a tool that helps developers, maintainers, students, and engineering teams understand why a codebase looks the way it does today, instead of only seeing what changed. :contentReference[oaicite:0]{index=0}

What it does

Replay is an Interactive Software Evolution Explorer that analyzes Git repositories and reconstructs their engineering history.

It supports both:

  • Local Git repositories
  • Public GitHub repositories (without cloning)

For every commit, Replay performs static analysis and builds an architectural snapshot, allowing users to:

  • Explore repository evolution through an interactive timeline
  • Track cyclomatic complexity and maintainability trends
  • Visualize architecture and dependency relationships
  • Detect technical debt hotspots
  • Compare engineering metrics across commits
  • Generate Markdown, JSON, and PDF engineering reports

Unlike conventional Git visualization tools, Replay focuses on how the software itself evolves, not just its commit history. :contentReference[oaicite:1]{index=1}

How we built it

Replay follows a clean client-server architecture.

Frontend

  • React
  • TypeScript
  • Vite
  • TailwindCSS

The frontend is intentionally lightweight, rendering visualizations while keeping business logic on the backend.

Backend

  • FastAPI
  • SQLAlchemy
  • Pydantic
  • GitPython
  • Python AST
  • NetworkX
  • Radon

The backend imports repositories, extracts commit history, performs static code analysis, computes engineering metrics, and persists repository snapshots in SQLite.

One of the key design decisions was analyzing GitHub repositories directly through the GitHub REST API, decoding source blobs entirely in memory instead of cloning repositories locally. Replay stores only the computed engineering metrics, dependency graphs, and metadata, making analysis efficient and lightweight. :contentReference[oaicite:2]{index=2} :contentReference[oaicite:3]{index=3}

Challenges we ran into

Some of the biggest challenges included:

  • Designing a scalable architecture capable of analyzing hundreds of commits while keeping the UI responsive.
  • Performing repository analysis without cloning GitHub repositories, requiring in-memory processing of source blobs.
  • Building immutable architectural snapshots so repository history could be replayed safely without modifying previous analyses.
  • Computing meaningful engineering metrics across an entire commit history while maintaining acceptable performance.
  • Keeping a clear separation between visualization, analysis, persistence, and repository import using Clean Architecture principles. :contentReference[oaicite:4]{index=4}

Accomplishments that we're proud of

We're especially proud that Replay can:

  • Analyze public GitHub repositories without requiring local clones.
  • Reconstruct repository evolution through chronological engineering snapshots.
  • Measure code quality using AST-based static analysis.
  • Track maintainability, complexity, and dependency evolution over time.
  • Generate professional engineering reports in multiple formats.
  • Deliver a clean, modular architecture that can be extended with additional analyses in the future. :contentReference[oaicite:5]{index=5}

What we learned

Building Replay reinforced several important lessons:

  • Software evolution is far richer than commit history alone.
  • Clean Architecture makes it significantly easier to separate analysis, persistence, APIs, and visualization.
  • Python's AST ecosystem enables surprisingly deep static analysis without executing code.
  • Engineering metrics become much more valuable when viewed as historical trends rather than isolated numbers.
  • Designing for extensibility early makes it easier to introduce new analyses and visualizations later.

What's next for Replay

Our roadmap includes:

  • Interactive architecture and dependency graph visualizations using graph canvases.
  • Support for additional programming languages beyond Python.
  • Faster incremental analysis for very large repositories.
  • Branch comparison and merge evolution visualization.
  • Collaboration features for engineering teams.
  • CI/CD integration to monitor engineering health continuously.
  • More advanced hotspot detection and architectural drift analysis powered by historical repository data.

Replay is ultimately aimed at becoming a comprehensive platform for understanding how software systems evolve, helping developers make better architectural decisions by learning from the past. :contentReference[oaicite:6]{index=6} :contentReference[oaicite:7]{index=7}

How Codex helped us build Replay

Codex acted as our AI engineering partner throughout the development process, accelerating implementation while allowing us to focus on architecture and product design.

We used Codex to:

  • Scaffold the initial React and FastAPI project structure.
  • Generate boilerplate API endpoints, models, and service layers.
  • Refactor code to follow Clean Architecture and SOLID principles.
  • Implement repository analysis workflows and backend integrations.
  • Debug runtime errors, resolve build issues, and fix failing tests.
  • Improve code quality by identifying edge cases and suggesting cleaner implementations.
  • Generate and refine project documentation, architecture notes, and the README.
  • Assist in Docker configuration, development environment setup, and validation workflows.

Rather than replacing engineering decisions, Codex served as an intelligent pair programmer. We designed the product vision, architecture, feature set, and engineering workflow, while using Codex to accelerate implementation, iterate faster, and maintain code quality across the project.

Built With

Share this project:

Updates