# nhtlongcs/starlistify architecture

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

- Interactive diagram: https://gitdiagram.com/nhtlongcs/starlistify
- Repository: https://github.com/nhtlongcs/starlistify

## Overview

##### Main Components Identification

a. Core Processing Components:
- Star Fetcher (fetch_gh_stars.py)
- Category Generator (cluster_gh_stars.py)
- Repository Categorizer (categorize_gh_stars.py)
- Updater (update_gh_lists.py)

b. External Services:
- GitHub API
- GenAI Service (for embeddings/LLM)

c. Data Storage:
- CSV Files (intermediate storage)
- Environment Configuration

**[External Services Layer]**

- GitHub API
- GenAI Service

**[Core Application Layer]**

- Star Fetcher
- Category Generator
- Repository Categorizer
- List Updater

**[Data Layer]**

- CSV Storage
- Environment Config

##### Specific Implementation Details

a. Data Collection Flow:
**GitHub API ⇢ Star Fetcher → CSV Storage (starred_repos.csv)**

b. Processing Flow:
**CSV Storage → Category Generator ⇢ GenAI Service → CSV Storage (topics.csv)**
**CSV Storage → Repository Categorizer ⇢ GenAI Service → CSV Storage (star_listified.csv)**

c. Update Flow:
**CSV Storage → List Updater ⇢ GitHub API**

##### Additional Elements

- Input/Output formats between components
- Authentication flow with environment variables
- Error handling paths
- Caching mechanisms (if any)
- Batch processing indicators

##### Technical Details to Highlight

- Python 3.10 runtime environment
- API authentication requirements
- File format specifications
- Model integration points

##### Notes for Implementation

- Clear separation between local and external components
- Where user preferences are injected
- Async operations where applicable

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef external fill:#a8d1f0,stroke:#333
    classDef core fill:#90EE90,stroke:#333
    classDef data fill:#FFE5B4,stroke:#333
    classDef config fill:#D3D3D3,stroke:#333
    
    %% External Services Layer
    subgraph ExternalServices
        GH["GitHub API"]:::external
        GenAI["GenAI Service"]:::external
    end

    %% Core Application Layer
    subgraph CoreApplication
        SF["Star Fetcher"]:::core
        CG["Category Generator"]:::core
        RC["Repository Categorizer"]:::core
        LU["List Updater"]:::core
        CLI["CLI Interface"]:::core
        Utils["Utility Functions"]:::core
    end

    %% Data Layer
    subgraph DataLayer
        CSV["CSV Storage"]:::data
        EnvConfig["Environment Config"]:::config
        PkgConfig["Package Config"]:::config
        Setup["Package Setup"]:::config
        Init["Package Init"]:::config
    end

    %% Relationships
    GH -.-> SF
    SF --> CSV
    CSV --> CG
    GenAI -.-> CG
    CG --> CSV
    CSV --> RC
    GenAI -.-> RC
    RC --> CSV
    CSV --> LU
    LU -.-> GH
    CLI --> SF
    CLI --> CG
    CLI --> RC
    CLI --> LU
    Utils --> SF
    Utils --> CG
    Utils --> RC
    Utils --> LU
    EnvConfig -.-> SF
    EnvConfig -.-> CG
    EnvConfig -.-> RC
    EnvConfig -.-> LU

    %% Click Events
    click SF "https://github.com/nhtlongcs/StarListify/blob/master/starlistify/fetch_gh_stars.py"
    click CG "https://github.com/nhtlongcs/StarListify/blob/master/starlistify/cluster_gh_stars.py"
    click RC "https://github.com/nhtlongcs/StarListify/blob/master/starlistify/categorize_gh_stars.py"
    click LU "https://github.com/nhtlongcs/StarListify/blob/master/starlistify/update_gh_lists.py"
    click EnvConfig "https://github.com/nhtlongcs/StarListify/blob/master/.env.dev"
    click CLI "https://github.com/nhtlongcs/StarListify/blob/master/starlistify/cli.py"
    click Utils "https://github.com/nhtlongcs/StarListify/blob/master/starlistify/utils.py"
    click PkgConfig "https://github.com/nhtlongcs/StarListify/blob/master/pyproject.toml"
    click Setup "https://github.com/nhtlongcs/StarListify/blob/master/setup.py"
    click Init "https://github.com/nhtlongcs/StarListify/blob/master/starlistify/__init__.py"

    %% Legend
    subgraph Legend
        L1["External Services"]:::external
        L2["Core Components"]:::core
        L3["Data Storage"]:::data
        L4["Configuration"]:::config
        L5["--> Data Flow"]
        L6["-.-> API Calls"]
    end
```
