# m-ahmed-elbeskeri/starguard architecture

> Architecture diagram of the GitHub repository m-ahmed-elbeskeri/starguard, 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/m-ahmed-elbeskeri/starguard
- Repository: https://github.com/m-ahmed-elbeskeri/starguard

## Overview

##### Project type and purpose
- StarGuard is an open-source, Python-based CLI tool for automated due-diligence on GitHub repositories. It collects public metadata, runs a series of analyzers and parsers, computes a composite “trust score,” and emits reports (JSON, Markdown, badges, plots).

##### File structure
- Top level:
- `.github/workflows/publish.yml` – CI job to publish to PyPI.
- `pyproject.toml` – build metadata, dependencies, entry point.
- `starguard.py` – the single-file codebase containing:
– CLI argument parsing
– GitHub API/GraphQL client
– Collector modules (stars, forks, issues, traffic)
– Analyzer modules (BurstDetector, UserProfiler)
– Dependency & licence parsers
– Scoring engine (ScoreCombiner)
– Output generators (text, JSON, Markdown, plot, badges)
- `README.md` & `LICENSE`

##### README for architectural insights
GH API → Collectors → Analyzers + Parser → ScoreCombiner → Output
- Key components are described in prose (BurstDetector, UserProfiler, Scoring Engine, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    External["GitHub API/GraphQL Client"]:::external

    subgraph "CLI Layer"
        CLI["CLI Entry Point"]:::core
        Config["Configuration & Environment"]:::core
    end

    subgraph "Collection Layer"
        APIClient["GitHub API Client"]:::core
        Collectors["Collectors\n(stars, forks, issues, traffic)"]:::core
    end

    subgraph "Analysis & Parsing Layer"
        Analyzers["Analyzers\n(BurstDetector, UserProfiler)"]:::core
        Parsers["Parsers\n(Dependency manifests, License)"]:::core
    end

    Scoring["Scoring Engine\n(ScoreCombiner)"]:::core

    subgraph "Output Layer"
        Outputs["Output Renderers\n(Plaintext, JSON, Markdown, Badges, Plots)"]:::output
    end

    subgraph "CI/CD Pipeline"
        CICD["GitHub Actions\nPublish Workflow"]:::ci
        Metadata["Build Metadata & Dependencies\n(pyproject.toml)"]:::ci
        Docs["Project Documentation\n(README.md)"]:::ci
        License["License File\n(LICENSE)"]:::ci
    end

    %% Flow
    CLI -->|"loads config"| Config
    Config -->|"invokes client"| APIClient
    External -->|"fetch data"| APIClient
    APIClient -->|"raw repo data"| Collectors
    Collectors -->|"collector outputs"| Analyzers
    Collectors -->|"collector outputs"| Parsers
    Analyzers -->|"analysis results"| Scoring
    Parsers -->|"parsed data"| Scoring
    Scoring -->|"score object"| Outputs

    %% CI/CD flow
    CLI -.->|codebase triggers| CICD
    Metadata -.->|defines build| CICD
    Docs -.->|includes README| CICD
    License -.->|includes LICENSE| CICD

    %% Click Events
    click CLI "https://github.com/m-ahmed-elbeskeri/starguard/blob/main/starguard.py"
    click Config "https://github.com/m-ahmed-elbeskeri/starguard/blob/main/starguard.py"
    click APIClient "https://github.com/m-ahmed-elbeskeri/starguard/blob/main/starguard.py"
    click Collectors "https://github.com/m-ahmed-elbeskeri/starguard/blob/main/starguard.py"
    click Analyzers "https://github.com/m-ahmed-elbeskeri/starguard/blob/main/starguard.py"
    click Parsers "https://github.com/m-ahmed-elbeskeri/starguard/blob/main/starguard.py"
    click Scoring "https://github.com/m-ahmed-elbeskeri/starguard/blob/main/starguard.py"
    click Outputs "https://github.com/m-ahmed-elbeskeri/starguard/blob/main/starguard.py"
    click CICD "https://github.com/m-ahmed-elbeskeri/starguard/blob/main/.github/workflows/publish.yml"
    click Metadata "https://github.com/m-ahmed-elbeskeri/starguard/blob/main/pyproject.toml"
    click Docs "https://github.com/m-ahmed-elbeskeri/starguard/blob/main/README.md"
    click License "https://github.com/m-ahmed-elbeskeri/starguard/tree/main/LICENSE"

    %% Styles
    classDef external fill:#AED6F1,stroke:#1F618D,color:#1B4F72;
    classDef core fill:#ABEBC6,stroke:#196F3D,color:#145A32;
    classDef output fill:#F9E79F,stroke:#B9770E,color:#7D6608;
    classDef ci fill:#D5DBDB,stroke:#7B7D7D,color:#515A5A;
```
