# pl1000100/gitstats architecture

> Architecture diagram of the GitHub repository pl1000100/gitstats, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pl1000100/gitstats
- Repository: https://github.com/pl1000100/gitstats

## Overview

##### Project type and purpose
- From the README and file tree, this is a full‑stack web application called “Gitstats.”
- It consists of a static frontend (index.html) served via its own Docker container and a Go‑based backend API that fetches repository stats from GitHub and codetabs.

##### File structure
Top‑level:
- docker-compose.yml – orchestrates two services: frontend and backend
- frontend/
– Dockerfile, index.html
- backend/
– Dockerfile, main.go, go.mod, go.sum
– internal/github (handles GitHub API calls)
– internal/count_loc (processes code‐loc statistics via codetabs)
– utils (CORS, JSON helpers)
Supporting files:
- .gitignore
- README.md
- img/ (screenshots)

##### Extract architectural insights from the README
- There are three API endpoints under /api/v1:
1. GET /repositories/{user} → retrieves list of repos via GitHub API
2. GET /stats/{user}/{repo} → retrieves LOC stats via codetabs API
3. GET /stats/{user} → aggregates stats for all repos (rate‑limited)
- The backend relies on an environment variable GITHUB_ACCESS_TOKEN.
- The frontend is a single HTML page (likely with JS) that calls these endpoints.

##### Main components and their interactions
a. Frontend Service
- Hosts index.html and any client‑side JS/CSS.
- Sends HTTP requests to the backend API.
b. Backend Service
- Exposes REST endpoints (/api/v1/…).
- Routes requests into two internal modules:
– github package: calls GitHub API to list repositories
– count_loc package: calls codetabs API to gather LOC stats
- Uses utils/cors.go to allow cross‑origin requests from the frontend.
- Uses utils/json.go to serialize/deserialize JSON payloads.
c. External Services
- GitHub REST API (requires GITHUB_ACCESS_TOKEN)
- codetabs API (rate limited)
d. Orchestration
- docker-compose sets up two containers (frontend & backend) on the same Docker network.
- .env supplies the GitHub token to the backend container.

##### Architectural patterns and design principles
- Separation of concerns:
- Frontend UI vs. Backend API vs. External data providers.
- Within the backend: clearly divided packages for external integrations and utilities.
- Stateless microservice: no database, calls external APIs on demand.
- Single‑page or static‑serve model for the UI.
- Dependency injection via environment variables (.env) in Docker Compose.

##### Final checklist
- [ ] Each component clearly labeled
- [ ] Call out Docker Compose orchestration and .env dependency
- [ ] Note key internal packages and their responsibilities

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Browser[/"User's Web Browser"/]:::external
        subgraph FrontendContainer["Frontend Container"]
            Frontend["Static Frontend\nHTML/JS\n(Docker)"]:::ours
        end
    end

    %% Server Layer
    subgraph "Server Layer"
        subgraph BackendContainer["Backend Container"]
            Backend["Go Backend API\nHTTP REST\n(Docker)"]:::ours
            subgraph "Internal Modules"
                GitHubMod["github package"]:::internal
                CountLocMod["count_loc package"]:::internal
                UtilsMod["utils (CORS & JSON)"]:::internal
            end
        end
    end

    %% External Integration Layer
    subgraph "External Integration Layer"
        GitHubAPI[(GitHub REST API)]:::external
        CodeTabsAPI[(codetabs REST API)]:::external
    end

    %% Infrastructure & Documentation
    subgraph "Infrastructure & Docs"
        Compose["docker-compose.yml"]:::infra
        README["README.md"]:::infra
        Gitignore[".gitignore"]:::infra
    end

    %% Data Flows
    Browser -->|"GET index.html"| Frontend
    Frontend -->|"GET /api/v1/*"| Backend
    Backend -->|internal call| GitHubMod
    Backend -->|internal call| CountLocMod
    Backend -->|uses| UtilsMod
    GitHubMod -->|"GitHub API (token)"| GitHubAPI
    CountLocMod -->|"codetabs API (rate‑limited)"| CodeTabsAPI
    GitHubAPI -->|JSON response| GitHubMod
    CodeTabsAPI -->|JSON response| CountLocMod
    Backend -->|"JSON response"| Frontend
    Frontend -->|"renders page"| Browser

    %% Orchestration Links
    Compose -.-> FrontendContainer
    Compose -.-> BackendContainer

    %% Click Events
    click Frontend "https://github.com/pl1000100/gitstats/tree/main/frontend/"
    click Backend "https://github.com/pl1000100/gitstats/tree/main/backend/"
    click GitHubMod "https://github.com/pl1000100/gitstats/tree/main/backend/internal/github/"
    click CountLocMod "https://github.com/pl1000100/gitstats/tree/main/backend/internal/count_loc/"
    click UtilsMod "https://github.com/pl1000100/gitstats/tree/main/backend/utils/"
    click Compose "https://github.com/pl1000100/gitstats/blob/main/docker-compose.yml"
    click README "https://github.com/pl1000100/gitstats/blob/main/README.md"
    click Gitignore "https://github.com/pl1000100/gitstats/blob/main/.gitignore"

    %% Styling
    classDef ours fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef internal fill:#E6D0FF,stroke:#6f42c1,color:#6f42c1
    classDef external fill:#D0FFD6,stroke:#22863a,color:#22863a
    classDef infra fill:#FFE6CC,stroke:#d15700,color:#d15700
```
