Documentation

Get started in three simple steps:

1. Find a public Git repository you want to analyze (GitHub, GitLab, Bitbucket, Gitea, or Codeberg)
2. Paste the repository URL into the form on the home page and click "Analyze"
3. Wait for the analysis to complete, then view your interactive visualization

Code Evolution Analyzer is a web service that visualizes how your code has evolved over time. It analyzes a Git repository's commit history and shows you:

• Lines of code growth - Watch your codebase expand commit-by-commit
• Language composition - See which programming languages make up your project and how they change
• Code vs. comments ratio - Track your documentation efforts over time
• Historical trends - Identify major development phases and refactoring events

The tool uses scc (Succinct Code Counter) or cloc (Count Lines of Code) to analyze each commit and generates an interactive Canvas visualization that lets you explore your repository's history.

The Analysis Process

What Gets Counted?

For each commit, we count:

• Code - Actual lines of programming code
• Comments - Documentation and inline comments
• Blank lines - Empty lines for readability

The tool recognizes over 250 programming languages and automatically detects which ones are present in your repository.

Code Evolution Analyzer runs on a scalable cloud infrastructure designed for reliability and performance. Here's how the system is organized:

Infrastructure Overview

The service is deployed on a Kubernetes cluster with automatic scaling, fault tolerance, and encrypted communications at every layer.

flowchart TB
    subgraph Internet["Internet"]
        User["👤 User Browser"]
    end

    subgraph Edge["Edge / Load Balancing"]
        LB["TLS Load Balancer
HTTPS Termination"]
    end

    subgraph K8s["Kubernetes Cluster"]
        Ingress["Ingress Controller
L7 Routing & Rate Limiting"]

        subgraph APILayer["API Layer"]
            API1["API Pod"]
            API2["API Pod"]
        end

        subgraph WorkerLayer["Worker Pool (Auto-scaled)"]
            W1["Worker Pod"]
            W2["Worker Pod"]
            W3["Worker Pod"]
            WN["Worker Pod N"]
        end

        subgraph Messaging["Message Bus"]
            MQ["Pub/Sub Queue
Durable Job Queue"]
        end

        subgraph Data["Data Services"]
            DB[("Relational DB
Job State")]
            Cache[("In-Memory Cache
Sessions & Stats")]
        end

        subgraph Storage["Distributed Storage"]
            CephFS[("Shared Storage
Analysis Results")]
        end

        HPA["Horizontal Pod Autoscaler"]
    end

    User -->|"HTTPS"| LB
    LB -->|"TLS"| Ingress
    Ingress --> API1 & API2
    API1 & API2 -->|"Publish Jobs"| MQ
    API1 & API2 --> DB
    API1 & API2 --> Cache
    MQ -->|"Consume Jobs"| W1 & W2 & W3 & WN
    W1 & W2 & W3 & WN --> DB
    W1 & W2 & W3 & WN -->|"Store Results"| CephFS
    W1 & W2 & W3 & WN -->|"Progress Events"| MQ
    MQ -->|"Stream to Client"| API1 & API2
    HPA -.->|"Scale Workers"| WorkerLayer
          

Request Lifecycle

When you submit a repository for analysis, here's what happens behind the scenes:

sequenceDiagram
    participant Browser
    participant LoadBalancer as TLS Load Balancer
    participant API as API Service
    participant Queue as Message Queue
    participant Worker
    participant Storage as Distributed Storage

    Browser->>+LoadBalancer: POST /api/analyze (HTTPS)
    LoadBalancer->>+API: Route Request
    API->>API: Validate URL & Rate Limit
    API->>Queue: Publish Job
    API-->>-Browser: 202 Accepted (Job ID)

    Browser->>LoadBalancer: WebSocket Connect
    LoadBalancer->>API: Upgrade to WS

    Queue->>+Worker: Deliver Job
    Worker->>Worker: Clone Repository

    loop For Each Commit
        Worker->>Worker: Analyze Commit
        Worker->>Queue: Progress Event
        Queue->>API: Forward Progress
        API-->>Browser: Progress Update (WS)
    end

    Worker->>Storage: Store Results
    Worker->>Queue: Complete Event
    Queue->>API: Forward Complete
    API-->>Browser: Analysis Complete (WS)

    Browser->>LoadBalancer: GET /results
    LoadBalancer->>API: Route Request
    API->>Storage: Fetch Results
    API-->>Browser: Visualization HTML
          

Automatic Scaling

Workers automatically scale based on demand to handle varying loads efficiently:

flowchart LR
    subgraph Monitoring["Resource Monitoring"]
        HPA["Horizontal Pod Autoscaler"]
        Metrics["CPU & Memory Metrics"]
    end

    subgraph LowLoad["Low Load"]
        L1["Worker"]
        L2["Worker"]
    end

    subgraph NormalLoad["Normal Load"]
        N1["Worker"]
        N2["Worker"]
        N3["Worker"]
    end

    subgraph HighLoad["High Load"]
        H1["Worker"]
        H2["Worker"]
        H3["Worker"]
        H4["Worker"]
        H5["Worker"]
        H6["Worker"]
    end

    Metrics --> HPA
    HPA -->|"Scale Up"| NormalLoad
    HPA -->|"Scale Up"| HighLoad
    HPA -->|"Scale Down"| LowLoad
          

Key Design Principles

• Encryption Everywhere: All traffic is encrypted with TLS, including internal cluster communication
• Horizontal Scaling: Workers scale from 2 to 6 pods automatically based on CPU utilization
• Fault Tolerance: Job queue ensures at-least-once delivery; failed jobs are automatically retried
• Shared Storage: Distributed filesystem allows any API pod to serve results from any worker
• Rate Limiting: Multi-layer rate limiting protects against abuse at ingress and application levels
• Graceful Degradation: Service continues operating if optional components (like caching) are unavailable

The Visualization Page

Once analysis is complete, you'll see an interactive page with several features:

Line Chart

The main chart shows lines of code over time. Each point represents a commit. Hover over points to see details like commit date, hash, and exact line counts.

Playback Controls

Use the play button and slider to animate through your repository's history. Watch how your codebase evolved commit-by-commit.

Language Breakdown

A pie chart or bar chart shows which programming languages make up your project and how their proportions change over time.

Statistics Panel

View summary statistics including:

• Total commits analyzed
• Current lines of code
• Number of languages detected
• Date range of the analysis

Interpreting Trends

What Repositories Can Be Analyzed?

Analysis Time

Processing time varies depending on:

• Number of commits available to analyze
• Repository size and complexity
• Current server load

Rate Limits

To ensure fair access, we limit submissions to 10 analyses per 15 minutes per IP address. If you hit this limit, please wait before submitting additional jobs.

Data Retention

Results are stored temporarily and may be removed. Saved links reopen results while they remain available. Use Download JSON on the completed job's status page to keep a copy.

My job is stuck at "Queued"

Multiple workers process jobs from the shared queue. Each worker handles one job at a time, so your job waits until a worker is available. You can follow its progress on the status page.

My job failed during cloning

Ensure:

• The repository URL is correct and complete
• The repository is public (not private)
• The repository still exists and wasn't deleted
• The repository size is under 1GB

The visualization won't load

Try:

• Refreshing the page (Ctrl+F5 or Cmd+Shift+R)
• Clearing your browser cache
• Trying a different browser
• Checking your internet connection

If the problem persists, the results may have expired and been deleted.

Getting "Rate Limit Exceeded"

You've submitted more than 10 analyses in 15 minutes. Wait 15 minutes before submitting additional jobs. This limit prevents system abuse and ensures fair access for all users.

For more information about the project:

• About the author: slepp.ca