# nubisub/remun-notifier architecture

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

- Interactive diagram: https://gitdiagram.com/nubisub/remun-notifier
- Repository: https://github.com/nubisub/remun-notifier

## Overview

##### Project type and purpose
- This is an open‑source “remuneration notifier” tool, implemented as a Python script that maintains a list of PDF files (Perpres) and a JSON index (number.json), automatically updates README.md, and uses GitHub Pages to publish the list as a static site.

##### File structure
- Top level:
- .github/workflows/python-app.yml – CI workflow that runs the Python script
- .github/workflows/pages/pages-build-deployment – CI workflow for GitHub Pages
- main.py – core update script
- number.json – keeps track of the current list state
- File/… – directory of PDF documents
- README.md – the generated list, rendered on GitHub or Pages
- requirements.txt – Python dependencies
- Patterns: single‑service script with data folder and two CI pipelines (update + deploy).

##### README for architectural clues
- README is regenerated by main.py based on number.json and File/ directory contents.
- CI triggers on schedule or push, runs main.py, commits back updates, then triggers Pages deploy.

a. Main components
1. GitHub Repository (source of truth for code, data, docs)
2. GitHub Actions Runner (hosted CI environment)
– Python‑app workflow
– Pages build workflow
3. Python Update Service (main.py)
4. Data Store
– number.json (index)
– File/ directory (PDF assets)
5. GitHub Pages (static site hosting)
6. End User’s Browser (visitor of the static site)
b. Relationships & interactions
- A scheduled or push event in the Repo → triggers Python‑app workflow → spins up Actions Runner → installs dependencies → runs main.py
- main.py reads number.json & File/ → regenerates README.md (Table of Perpres) → git commit & push back to Repo
- Push to main branch → triggers Pages build workflow → builds static site from README.md → publishes to GitHub Pages
- End user’s browser fetches the published site on GitHub Pages
c. Architectural patterns & design principles
- Single‑responsibility script (main.py) handles state detection and readme generation
- CI/CD pipelines decouple update logic and deployment logic
- Data‑as‑code: PDFs and JSON live in the git repo, enabling versioned tracking
- Static hosting for low‑maintenance, scalable delivery
d. Key technologies & libraries
- GitHub Actions (CI/CD orchestration)
- Python 3 (main.py)
- PyYAML / JSON modules (state management)
- Markdown (README generation)
- Git (version control)
- GitHub Pages (hosting)

##### Final reminders
- Every major element (Repo, CI, script, data, hosting, user)
- Clear separation of concerns: update vs. deploy

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Events
    Repo["GitHub Repository\n(source code, data)"]:::external
    Schedule["Schedule / Push Event"]:::external
    Repo -->|triggers| Schedule

    %% Update Pipeline
    subgraph "Update Pipeline" 
        direction TB
        PythonAppWorkflow["GitHub Actions Runner\nPython-app Workflow"]:::pipeline
        Dependencies["Install Dependencies\n(requirements.txt)"]:::pipeline
        PythonUpdateService["main.py\n(Python Update Service)"]:::script
        JSONDataStore["number.json\n(JSON Data Store)"]:::datastore
        PDFAssets["File/\n(PDF Assets)"]:::datastore
        Readme["README.md\n(Markdown Output)"]:::datastore
        CommitPush["Git Commit & Push Updates"]:::pipeline
    end

    Schedule --> PythonAppWorkflow
    PythonAppWorkflow -->|runs| Dependencies
    Dependencies -->|installs| PythonUpdateService
    PythonUpdateService -->|reads| JSONDataStore
    PythonUpdateService -->|reads| PDFAssets
    PythonUpdateService -->|generates| Readme
    Readme --> CommitPush
    CommitPush --> Repo

    %% Deploy Pipeline
    subgraph "Deploy Pipeline"
        direction TB
        PagesWorkflow["GitHub Actions Runner\nPages Build Workflow"]:::pipeline
        GitHubPages["GitHub Pages\n(Static Site Hosting)"]:::hosting
    end

    Repo -->|push triggers| PagesWorkflow
    PagesWorkflow -->|builds from README.md| GitHubPages

    %% End User
    Browser["End User Browser\n(Visitor)"]:::external
    GitHubPages -->|serves site| Browser

    %% Click Events
    click PythonAppWorkflow "https://github.com/nubisub/remun-notifier/blob/main/.github/workflows/python-app.yml"
    click PythonUpdateService "https://github.com/nubisub/remun-notifier/blob/main/main.py"
    click JSONDataStore "https://github.com/nubisub/remun-notifier/blob/main/number.json"
    click PDFAssets "https://github.com/nubisub/remun-notifier/tree/main/File/"
    click Readme "https://github.com/nubisub/remun-notifier/blob/main/README.md"
    click Dependencies "https://github.com/nubisub/remun-notifier/blob/main/requirements.txt"

    %% Styles
    classDef pipeline fill:#D6E9FF,stroke:#31708F,stroke-width:1px;
    classDef script fill:#FCF8E3,stroke:#8A6D3B,stroke-width:1px;
    classDef datastore fill:#DFF0D8,stroke:#3C763D,stroke-width:1px;
    classDef hosting fill:#F2DEDE,stroke:#A94442,stroke-width:1px;
    classDef external fill:#D9EDF7,stroke:#31708F,stroke-width:1px;
```
