# nubplayz/github_auto_updater architecture

> Architecture diagram of the GitHub repository nubplayz/github_auto_updater, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nubplayz/github_auto_updater
- Repository: https://github.com/nubplayz/github_auto_updater

## Overview

##### What this project is (type + purpose)
From the README (“manage your outdated github repositories and exe”) and the file tree, this is a **small Python application** (likely a CLI or lightweight service) that:
- Tracks a set of “nodes” (repositories and/or executables) defined in **`nodes.json`**
- **Checks** whether they’re outdated (e.g., repo behind remote, exe version behind latest release)
- **Updates** them (pull repo, download newer exe, etc.)
- Persists or manages this inventory via a small storage layer (`nodes_store.py`)

There’s no evidence of a separate frontend/backend; the architecture is best represented as a **single-process Python app** integrating with **external services** (GitHub) and **local system resources** (filesystem, git, downloaded executables).

##### Core runtime / entrypoint
- **`app.py`**
- reading node definitions
- triggering checks
- triggering updates
- writing results / reporting

##### Domain logic
- **`checker.py`**
“Outdated detection” logic. This probably:
- inspects local repo state (git status, commit hash)
- calls GitHub to compare latest release/tag/commit
- inspects exe version vs latest available

- **`updater.py`**
“Apply updates” logic. This probably:
- runs `git pull` or equivalent for repos
- downloads artifacts (exe) from GitHub Releases
- replaces local binaries safely

##### Data / persistence / configuration
- **`nodes.json`**

- **`nodes_store.py`**

##### Supporting utility
- **`requirements.txt`**

- **`.devcontainer/devcontainer.json`**

##### External systems implied by the purpose

- **GitHub (API)**
For repo metadata, latest commits/tags, releases, assets.
- **Local Git (CLI) / Git working copy**
If repository updates are done via local git commands, show “Local Git CLI” as a dependency.
- **Local Filesystem**
For:
- storing `nodes.json`
- cloning repos / repo directories
- downloading and replacing exe files

If the code uses `subprocess` for git, model it as `updater.py -> Git CLI -> filesystem/repo dir`.

Because the app’s purpose is “outdated management”, the important flows are:

##### `checker.py` iterates nodes
- For repo nodes: compare local state ↔ GitHub state
- For exe nodes: compare local version ↔ latest GitHub release asset/version
##### Results returned to `app.py`
4. Optional: `nodes_store.py` persists last-known versions/status back to `nodes.json` (only if implemented)

##### `updater.py` performs update
- repos: `git pull` (or clone) into filesystem
- exe: download release asset → replace local exe
##### `app.py` records outcome (and optionally writes updated state)

- “Node list”
- “Version metadata”
- “Release asset binary”
- “Update result/status”

##### Architectural patterns to highlight (based on structure)

- **Orchestration layer**: `app.py`
- **Storage/Repository layer**: `nodes_store.py` + `nodes.json`
- **Domain services**:
- `checker.py` = “Read-only evaluation service”
- `updater.py` = “Side-effecting command service”
- **Infrastructure dependencies**: GitHub API, filesystem, git

This pattern is important to show because it clarifies:
- what is “pure logic” vs “I/O and side effects”
- where to mock for tests (even if tests aren’t present)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =======================
    %% External Actor / Systems
    %% =======================
    U["User (Operator/Developer)"]:::actor

    GH["GitHub (REST API / Releases)"]:::external
    GIT["Local Git CLI"]:::tool
    FS["Local Filesystem\n- Repo directories\n- Executable install paths"]:::infra

    %% =======================
    %% Application (Single Process)
    %% =======================
    subgraph "Python Application (Single Process Runtime)"
        APP["app.py\nApplication / Controller\n(Orchestrates check + update)"]:::app

        subgraph "Domain Services"
            CHK["checker.py\nOutdated Detection Engine\n(Read-only evaluation)"]:::domain
            UPD["updater.py\nUpdate Execution Engine\n(Side-effecting updates)"]:::sideeffect
        end

        subgraph "Storage Layer"
            STORE["nodes_store.py\nNodes Store / DAO\n(Load + persist node inventory/status)"]:::storage
            NODES[("nodes.json\nNode Inventory Datastore\n(Tracked nodes configuration)")]:::datastore
        end
    end

    %% =======================
    %% Dev / Build Environment (Non-runtime)
    %% =======================
    subgraph "Dev / Build Environment (Non-runtime)"
        REQ["requirements.txt\nPython dependencies"]:::dev
        DEV[".devcontainer/devcontainer.json\nDev container config"]:::dev
        DOC["README.md\nProject documentation"]:::dev
    end

    %% =======================
    %% Flows (Check + Update)
    %% =======================
    U -->|"run_check/update"| APP

    %% Inventory / persistence
    APP -->|"loads_nodes"| STORE
    STORE -->|"read/write"| NODES
    STORE -->|"node_list"| APP

    %% Check flow
    APP -->|"check(nodes)"| CHK
    CHK -->|"fetch_version_metadata"| GH
    CHK -->|"read_local_versions"| FS
    CHK -->|"check_results/status"| APP

    %% Optional persistence of status
    APP -->|"persist_status (optional)"| STORE

    %% Update flow
    APP -->|"update(outdated_nodes)"| UPD
    UPD -->|"download_release_asset"| GH
    UPD -->|"replace_binary"| FS
    UPD -->|"execute_git_pull/clone"| GIT
    GIT -->|"mutate_working_copy"| FS
    UPD -->|"update_results"| APP

    %% =======================
    %% Click Events (from component_mapping)
    %% =======================
    click APP "https://github.com/nubplayz/github_auto_updater/blob/main/app.py"
    click CHK "https://github.com/nubplayz/github_auto_updater/blob/main/checker.py"
    click UPD "https://github.com/nubplayz/github_auto_updater/blob/main/updater.py"
    click STORE "https://github.com/nubplayz/github_auto_updater/blob/main/nodes_store.py"
    click NODES "https://github.com/nubplayz/github_auto_updater/blob/main/nodes.json"
    click REQ "https://github.com/nubplayz/github_auto_updater/blob/main/requirements.txt"
    click DEV "https://github.com/nubplayz/github_auto_updater/blob/main/.devcontainer/devcontainer.json"
    click DOC "https://github.com/nubplayz/github_auto_updater/blob/main/README.md"

    %% =======================
    %% Styles
    %% =======================
    classDef actor fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#e2e8f0
    classDef app fill:#1e3a8a,stroke:#93c5fd,stroke-width:2px,color:#ffffff
    classDef domain fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#ecfdf5
    classDef sideeffect fill:#7c2d12,stroke:#fb923c,stroke-width:2px,color:#fff7ed
    classDef storage fill:#312e81,stroke:#a5b4fc,stroke-width:2px,color:#eef2ff
    classDef datastore fill:#111827,stroke:#f59e0b,stroke-width:2px,color:#fffbeb
    classDef external fill:#0b3a53,stroke:#22d3ee,stroke-width:2px,color:#ecfeff
    classDef infra fill:#1f2937,stroke:#cbd5e1,stroke-width:2px,color:#f8fafc
    classDef tool fill:#3f1d6b,stroke:#d8b4fe,stroke-width:2px,color:#faf5ff
    classDef dev fill:#3b3b3b,stroke:#a3a3a3,stroke-width:1.5px,color:#f5f5f5
```
