# bambadiagne/github-user-stats architecture

> Architecture diagram of the GitHub repository bambadiagne/github-user-stats, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bambadiagne/github-user-stats
- Repository: https://github.com/bambadiagne/github-user-stats

## Overview

##### Main components
- API Server: Represented by the Flask application (app.py). This server handles incoming HTTP requests, processes GraphQL queries, and returns data.
- Data Query/Processing Module: The query.py script (or similar modules) likely encapsulates logic for interacting with GitHub’s APIs and processing the fetched data.
- Data Store: The users.json file acts as the local storage for the user statistics that the API returns.
- Cron Job Scheduler: GitHub Actions workflows (in .github/workflows/ - deploy.yaml and update_data.yml) are used to invoke periodic updates of user data by triggering the query.py or related scripts.
- Containerization Infrastructure: The Dockerfile indicates that the API is containerized for deployment.
- External Clients: Consumers (e.g., web or mobile applications, or even command-line tools) that issue GET requests to endpoints like /users/contributions/senegal, /users/search, and /users/:username.
- Environment & Configuration: Environment variables such as GITHUB_TOKEN and FLASK_DEBUG play key roles in the setup and production/development behavior.

##### Relationships and Interactions
- The Client makes HTTP requests to the API server running the Flask application.
- When a client request is received, the API server uses its GraphQL layer to process the request. In some cases, it may pull or update data from the local users.json file.
- Independently, GitHub Actions (triggered by cron jobs) periodically execute update procedures (likely encapsulated in query.py) to fetch fresh statistics from GitHub’s API. This process uses the provided GitHub token for authentication and updates the users.json file.
- The Docker container wraps the entire application, making it easy to deploy across environments.
- External GitHub endpoints (the actual GitHub API) are accessed during data fetch operations.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The system divides responsibilities among the API server, data update processes, and the external integrations.
- Containerization: Docker ensures an isolated, consistent deployment environment.
- Event-Driven Updates: The use of GitHub Actions for scheduled cron jobs adds a reactive element to data updates.
- API Layer Abstraction: Using Flask with GraphQL abstracts the client interface from direct data-access complexities.

##### Relevant Technologies
- Flask for the API server.
- GraphQL for querying user data.
- Docker for containerization.
- GitHub Actions (cron jobs) for scheduling periodic updates.
- Python as the primary development language.
- Environment variables for configuration management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client("Client (HTTP Client)"):::client
    Env("Environment & Configuration"):::env

    %% Docker Container Subgraph
    subgraph "Docker Container"
        ContainerInfra("Containerization (Dockerfile)"):::container
        API("Flask API Server"):::server
        Query("Data Query/Processing Module"):::module
        Store("Users JSON Data Store"):::store
    end

    %% GitHub Actions Cron Jobs Subgraph
    subgraph "GitHub Actions Cron Jobs"
        CronDeploy("Cron Job: deploy.yaml"):::cron
        CronUpdate("Cron Job: update_data.yml"):::cron
    end

    %% External Service
    GitHub("GitHub API"):::external

    %% Connections
    Client -->|"HTTP_Request"| API
    Env -->|"Configures"| API
    CronDeploy -->|"Triggers_update"| Query
    CronUpdate -->|"Triggers_update"| Query
    API <-->|"ReadWrite"| Store
    Query -->|"Fetches_data"| GitHub
    Query -->|"Updates_store"| Store

    %% Click Events
    click API "https://github.com/bambadiagne/github-user-stats/blob/master/app.py"
    click Query "https://github.com/bambadiagne/github-user-stats/blob/master/query.py"
    click Store "https://github.com/bambadiagne/github-user-stats/blob/master/users.json"
    click CronDeploy "https://github.com/bambadiagne/github-user-stats/blob/master/.github/workflows/deploy.yaml"
    click CronUpdate "https://github.com/bambadiagne/github-user-stats/blob/master/.github/workflows/update_data.yml"
    click ContainerInfra "https://github.com/bambadiagne/github-user-stats/tree/master/Dockerfile"
    click Env "https://github.com/bambadiagne/github-user-stats/blob/master/README.md"

    %% Styles
    classDef client fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef server fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef module fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef store fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef cron fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef container fill:#D6EAF8,stroke:#2980B9,stroke-width:2px;
    classDef env fill:#E8F8F5,stroke:#16A085,stroke-width:2px;
```
