# ayhamjo7/iquantum architecture

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

- Interactive diagram: https://gitdiagram.com/ayhamjo7/iquantum
- Repository: https://github.com/ayhamjo7/iquantum

## Overview

##### Project type and purpose
- This is a static “Awesome Lists” aggregator: a build‐time data‐processing pipeline plus a client‐side web application. It automatically pulls in multiple GitHub “awesome list” repositories, extracts and validates their links, outputs JSON, and hosts a searchable static site on GitHub Pages.

##### Main components
a. Source Repositories
- External GitHub “awesome‑list” repos (vinta/awesome‑python, awesome‑nodejs, etc.)
b. CI/CD / Automation Layer
- GitHub Actions workflow (daily-update.yml)
- Triggers: cron schedule → jobs
c. Data Extraction & Processing
- Python scripts in `scripts/`
– `extract_data.py`: clones each repo, parses README.md, builds raw JSON
– `filter_valid_urls.py`: checks each URL for 200 OK
– `update_awesome_lists.py` & `main.py`: orchestrate extraction + filtering + writing to `data/`
- Input folders: none (scripts clone directly)
- Output files: `data/awesome-lists.json`, `data/metadata.json`
d. Data Storage
- Local JSON files in `data/` committed back into the repo
e. Hosting
- GitHub Pages serves static site from the `main` branch
f. Web Interface (Client)
- `index.html`
- CSS: `css/styles.css`, `css/aurora-title.css`
- JavaScript:
– `js/data-processor.js` (loads JSON, builds DOM)
– `js/main.js` (search orchestration via Fuse.js)
– `js/theme.js`, `js/particles.js`, `js/stars.js` (UI animations)
g. End Users
- Browser clients (mobile & desktop) that fetch the static assets and JSON data

##### Relationships and data flows
- GitHub Actions → invokes Python scripts → clones external repos → outputs JSON → commits JSON back to repo → GitHub Pages rebuilds site
- Browser clients → HTTP GET `index.html`, CSS, JS, JSON data → front-end renders searchable UI
- Development: local dev uses `python scripts/main.py` or `npx serve` to mimic the same pipeline and hosting

##### Architectural patterns & design principles
- ETL pipeline for data ingestion: Extract (clone & parse), Transform (filter/validate), Load (write JSON)
- CI/CD automation: scheduled jobs in GitHub Actions
- Static site generation: precomputed JSON + client rendering for zero‑backend runtime
- Separation of concerns: build (Python scripts + CI) vs. runtime (HTML/CSS/JS)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Repos
    subgraph "External GitHub Repos" 
        direction TB
        ExtRepos["Cloud: Awesome-list Repos"]:::external
    end

    %% CI/CD Layer
    subgraph "CI/CD Automation" 
        direction TB
        GHAction["GitHub Actions Runner<br/>(.github/workflows/daily-update.yml)"]:::ci
        GHAction -->|"cron trigger"| Extract
        subgraph "ETL Scripts" 
            direction TB
            Extract["extract_data.py"]:::processing
            Filter["filter_valid_urls.py"]:::processing
            Update["update_awesome_lists.py"]:::processing
            Main["main.py"]:::processing
        end
        Extract -->|"parsed README"| Filter
        Filter -->|"valid URLs"| Update
        Update -->|"orchestrates ETL"| Main
    end

    %% Data Storage
    Main -->|"write JSON"| DataStore
    DataStore["Cylinder: data/awesome-lists.json<br/>data/metadata.json"]:::storage

    %% Commit & Hosting
    DataStore -->|"git push JSON"| GHPages
    GHPages["GitHub Pages Hosting"]:::hosting

    %% Browser Clients and Front-end
    Browser["Browser Clients"]:::enduser

    subgraph "Front-end Assets" 
        direction TB
        HTML["index.html"]:::frontend
        CSS1["styles.css"]:::frontend
        CSS2["aurora-title.css"]:::frontend
        JS1["data-processor.js"]:::frontend
        JS2["main.js<br/>(Fuse.js search)"]:::frontend
        JS3["theme.js"]:::frontend
        JS4["particles.js"]:::frontend
        JS5["stars.js"]:::frontend
    end

    Browser -->|"HTTP GET index.html"| HTML
    Browser -->|"HTTP GET CSS"| CSS1
    Browser -->|"HTTP GET CSS"| CSS2
    Browser -->|"HTTP GET JS"| JS1
    Browser -->|"HTTP GET JS"| JS2
    Browser -->|"HTTP GET JS"| JS3
    Browser -->|"HTTP GET JS"| JS4
    Browser -->|"HTTP GET JS"| JS5
    Browser -->|"HTTP GET JSON"| DataStore
    JS2 -->|"search DOM via Fuse.js"| Browser

    %% Connections External to CI
    ExtRepos -->|"clone/read"| GHAction

    %% Click Events
    click GHAction "https://github.com/ayhamjo7/iquantum/blob/main/.github/workflows/daily-update.yml"
    click Extract "https://github.com/ayhamjo7/iquantum/blob/main/scripts/extract_data.py"
    click Filter "https://github.com/ayhamjo7/iquantum/blob/main/scripts/filter_valid_urls.py"
    click Update "https://github.com/ayhamjo7/iquantum/blob/main/scripts/update_awesome_lists.py"
    click Main "https://github.com/ayhamjo7/iquantum/blob/main/scripts/main.py"
    click DataStore "https://github.com/ayhamjo7/iquantum/blob/main/data/awesome-lists.json"
    click DataStore "https://github.com/ayhamjo7/iquantum/blob/main/data/metadata.json"
    click HTML "https://github.com/ayhamjo7/iquantum/blob/main/index.html"
    click CSS1 "https://github.com/ayhamjo7/iquantum/blob/main/css/styles.css"
    click CSS2 "https://github.com/ayhamjo7/iquantum/blob/main/css/aurora-title.css"
    click JS1 "https://github.com/ayhamjo7/iquantum/blob/main/js/data-processor.js"
    click JS2 "https://github.com/ayhamjo7/iquantum/blob/main/js/main.js"
    click JS3 "https://github.com/ayhamjo7/iquantum/blob/main/js/theme.js"
    click JS4 "https://github.com/ayhamjo7/iquantum/blob/main/js/particles.js"
    click JS5 "https://github.com/ayhamjo7/iquantum/blob/main/js/stars.js"

    %% Styles
    classDef external fill:#dddddd,stroke:#888888,color:#333333
    classDef ci fill:#cce5ff,stroke:#3399ff,color:#000000
    classDef processing fill:#d4edda,stroke:#28a745,color:#000000
    classDef storage fill:#fff3cd,stroke:#ffcd39,color:#000000
    classDef hosting fill:#e2e3e5,stroke:#6c757d,color:#000000
    classDef frontend fill:#ffe5b4,stroke:#ff8c00,color:#000000
    classDef enduser fill:#f0f0f0,stroke:#888888,color:#000000
```
