# rmncldyo/github-stats-checker architecture

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

- Interactive diagram: https://gitdiagram.com/rmncldyo/github-stats-checker
- Repository: https://github.com/rmncldyo/github-stats-checker

## Overview

##### Project Type and Purpose
- This is an open-source Python command-line tool (“GitHub Stats Checker”) that fetches and analyzes GitHub user profile and repository statistics via the GitHub REST API. It is not a web app or microservices platform, but a layered CLI utility with clear separation of concerns.

##### File-Structure Analysis
- Top-level
- example.py: entry-point demo script
- config.yaml: default behavior settings
- example.env: sample environment for GITHUB_ACCESS_TOKEN
- README.md, LICENSE, requirements.txt
- Package “github/”
- core/: orchestration (main.py, run.py)
- api/: thin GitHub API client (github_client.py)
- http/: HTTP layer (client.py, exceptions.py)
- services/: business-logic layer (auth_service, user_service, repository_service)
- utils/: config loader (config.py), URL parsing (url_parser.py)
- GitHub-related CI/CD and governance files under .github/

##### Key Insights from README
- Usage: import github; github.crawl()
- Optional authentication via environment or .env for private repos
- Behavior customization via config.yaml (repo_limit, include_private_repos, etc.)
- Error types: TokenError, ConfigError, RateLimitError, NetworkError, ValidationError

##### Components
a. Main Components
- CLI Interface (example.py or direct module import)
- Core Orchestrator (github/core/main.py & run.py)
- Configuration Loader (github/utils/config.py + config.yaml + environment variables)
- Services Layer
– AuthService: manages token injection, authentication errors
– UserService: fetches user profile stats
– RepositoryService: fetches repo stats
- API Client Layer (github/api/github_client.py)
- HTTP Client (github/http/client.py + exceptions)
- External System: GitHub REST API
b. Relationships & Data Flow
1. CLI triggers Core.run()
2. Core loads configuration via ConfigLoader
3. Core calls Services (AuthService → UserService & RepositoryService)
4. Each Service uses API Client
5. API Client delegates HTTP calls to HTTP Client
6. HTTP Client performs REST calls to GitHub API and returns JSON
7. Services process JSON and return domain objects or stats back to Core
8. Core aggregates results, applies formatting, and outputs to user
c. Architectural Patterns/Principles
- Layered architecture: separate config, orchestration, service logic, API client, transport
- Single responsibility per module
- Dependency inversion: services depend on interfaces of API client, not on HTTP layer directly
- Config-driven behavior for flexibility
d. Technologies/Frameworks
- Python 3.x
- requests (HTTP client dependency in requirements.txt)
- PyYAML (for config.yaml parsing)
- python-dotenv (optional, for .env support)
- GitHub REST API v3

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Interface\nexample.py"]:::cli
    end

    %% Core Layer
    subgraph "Core Layer"
        PackageInit["Package Init\ngithub/__init__.py"]:::core
        CoreMain["Core Orchestrator\nmain.py"]:::core
        CoreRun["Core Orchestrator\nrun.py"]:::core
    end

    %% Services Layer
    subgraph "Services Layer"
        AuthService["AuthService\nauth_service.py"]:::services
        UserService["UserService\nuser_service.py"]:::services
        RepoService["RepositoryService\nrepository_service.py"]:::services
    end

    %% API Layer
    subgraph "API Layer"
        APIClient["API Client\ngithub_client.py"]:::api
    end

    %% HTTP Layer
    subgraph "HTTP Layer"
        HTTPClient["HTTP Client\nclient.py"]:::http
        HTTPExceptions["HTTP Exceptions\nexceptions.py"]:::http
    end

    %% Utils Layer
    subgraph "Utils Layer"
        ConfigLoader["Configuration Loader\nconfig.py"]:::utils
        URLParser["URL Parsing Utility\nurl_parser.py"]:::utils
        ConfigFile["Default Config\nconfig.yaml"]:::utils
        EnvFile["Env Sample\nexample.env"]:::utils
    end

    %% External Systems
    subgraph "External Systems"
        ExternalAPI["GitHub REST API"]:::external
    end

    %% Connections
    CLI -->|triggers| CoreMain
    CoreMain -->|calls| CoreRun
    CoreRun -->|loads config| ConfigLoader
    ConfigFile -.->|provides defaults| ConfigLoader
    EnvFile -.->|provides token| ConfigLoader
    ConfigLoader -->|parses URLs| URLParser

    CoreRun -->|auth flow| AuthService
    CoreRun -->|user stats| UserService
    CoreRun -->|repo stats| RepoService

    AuthService -->|uses| APIClient
    UserService -->|uses| APIClient
    RepoService -->|uses| APIClient

    APIClient -->|delegates| HTTPClient
    HTTPClient -->|calls| ExternalAPI
    HTTPClient -->|raises| HTTPExceptions
    HTTPExceptions -.->|error handling| CoreRun

    %% Click Events
    click CLI "https://github.com/rmncldyo/github-stats-checker/blob/main/example.py"
    click PackageInit "https://github.com/rmncldyo/github-stats-checker/blob/main/github/__init__.py"
    click CoreMain "https://github.com/rmncldyo/github-stats-checker/blob/main/github/core/main.py"
    click CoreRun "https://github.com/rmncldyo/github-stats-checker/blob/main/github/core/run.py"
    click ConfigLoader "https://github.com/rmncldyo/github-stats-checker/blob/main/github/utils/config.py"
    click ConfigFile "https://github.com/rmncldyo/github-stats-checker/blob/main/config.yaml"
    click EnvFile "https://github.com/rmncldyo/github-stats-checker/blob/main/example.env"
    click APIClient "https://github.com/rmncldyo/github-stats-checker/blob/main/github/api/github_client.py"
    click HTTPClient "https://github.com/rmncldyo/github-stats-checker/blob/main/github/http/client.py"
    click HTTPExceptions "https://github.com/rmncldyo/github-stats-checker/blob/main/github/http/exceptions.py"
    click AuthService "https://github.com/rmncldyo/github-stats-checker/blob/main/github/services/auth_service.py"
    click UserService "https://github.com/rmncldyo/github-stats-checker/blob/main/github/services/user_service.py"
    click RepoService "https://github.com/rmncldyo/github-stats-checker/blob/main/github/services/repository_service.py"
    click URLParser "https://github.com/rmncldyo/github-stats-checker/blob/main/github/utils/url_parser.py"

    %% Styles
    classDef cli fill:#e3f2fd,stroke:#2196f3,color:#0d47a1
    classDef core fill:#bbdefb,stroke:#1565c0,color:#0d47a1
    classDef services fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef api fill:#ffe0b2,stroke:#f57c00,color:#e65100
    classDef http fill:#ffccbc,stroke:#d84315,color:#bf360c
    classDef utils fill:#d1c4e9,stroke:#7e57c2,color:#4a148c
    classDef external fill:#f0f4c3,stroke:#afb42b,color:#827717
```
