# mickpletcher/best-of-github architecture

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

- Interactive diagram: https://gitdiagram.com/mickpletcher/best-of-github
- Repository: https://github.com/mickpletcher/best-of-github

## Overview

Best of GitHub is a curated repository catalog with two automated discovery products: a daily random pick and weekly star-ranked reports. Users browse the curated README and generated reports; scheduled GitHub Actions refresh the automated content. The daily updater selects a safe repository and updates both the README block and archive. The weekly updater fetches repositories and writes ranked reports, while a separate validator checks report structure and README freshness. Edges reflect the README and sampled script excerpts; workflow implementation details were not sampled.

Main entry points: [`scripts/update_github_of_the_day.py`](https://github.com/mickpletcher/best-of-github/blob/main/scripts/update_github_of_the_day.py) (Daily Picker), [`scripts/update_weekly_rankings.py`](https://github.com/mickpletcher/best-of-github/blob/main/scripts/update_weekly_rankings.py) (Weekly Generator), [`scripts/validate_weekly_rankings.py`](https://github.com/mickpletcher/best-of-github/blob/main/scripts/validate_weekly_rankings.py) (Report Validator), [`README.md`](https://github.com/mickpletcher/best-of-github/blob/main/README.md) (Curated Picks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Curated Catalog"]
  node_readme["Curated Picks<br/>[README.md]"]
end

subgraph group_daily["Daily Discovery"]
  node_daily_script["Daily Picker"]
  node_archive["Daily Archive"]
end

subgraph group_weekly["Weekly Rankings"]
  node_weekly_script["Weekly Generator"]
  node_weekly100["Top 100 Report"]
  node_weekly250["Top 250 Report"]
end

subgraph group_validation["Report Validation"]
  node_validator["Report Validator"]
end

node_reader(("Catalog Reader"))
node_github_search{{"GitHub Search API"}}

node_reader -->|"browses"| node_readme
node_daily_script -->|"queries"| node_github_search
node_daily_script -->|"updates pick"| node_readme
node_daily_script -->|"appends selection"| node_archive
node_weekly_script -->|"fetches repositories"| node_github_search
node_weekly_script -->|"writes report"| node_weekly100
node_weekly_script -->|"writes report"| node_weekly250
node_validator -->|"validates"| node_weekly100
node_validator -->|"validates"| node_weekly250
node_validator -->|"checks freshness"| node_readme

click node_readme "https://github.com/mickpletcher/best-of-github/blob/main/README.md"
click node_daily_script "https://github.com/mickpletcher/best-of-github/blob/main/scripts/update_github_of_the_day.py"
click node_archive "https://github.com/mickpletcher/best-of-github/blob/main/github-of-the-day-archive.md"
click node_weekly_script "https://github.com/mickpletcher/best-of-github/blob/main/scripts/update_weekly_rankings.py"
click node_weekly100 "https://github.com/mickpletcher/best-of-github/blob/main/weekly-top-100-github-repositories.md"
click node_weekly250 "https://github.com/mickpletcher/best-of-github/blob/main/weekly-top-250-github-repositories.md"
click node_validator "https://github.com/mickpletcher/best-of-github/blob/main/scripts/validate_weekly_rankings.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme toneBlue
class node_daily_script,node_archive toneAmber
class node_weekly_script,node_weekly100,node_weekly250,node_github_search toneMint
class node_validator toneRose
class node_reader toneIndigo
```

## Components

### Curated Catalog

- [Curated Picks](https://github.com/mickpletcher/best-of-github/blob/main/README.md): `README.md`

### Daily Discovery

- [Daily Picker](https://github.com/mickpletcher/best-of-github/blob/main/scripts/update_github_of_the_day.py): `scripts/update_github_of_the_day.py`
- [Daily Archive](https://github.com/mickpletcher/best-of-github/blob/main/github-of-the-day-archive.md): `github-of-the-day-archive.md`

### Weekly Rankings

- [Weekly Generator](https://github.com/mickpletcher/best-of-github/blob/main/scripts/update_weekly_rankings.py): `scripts/update_weekly_rankings.py`
- [Top 100 Report](https://github.com/mickpletcher/best-of-github/blob/main/weekly-top-100-github-repositories.md): `weekly-top-100-github-repositories.md`
- [Top 250 Report](https://github.com/mickpletcher/best-of-github/blob/main/weekly-top-250-github-repositories.md): `weekly-top-250-github-repositories.md`

### Report Validation

- [Report Validator](https://github.com/mickpletcher/best-of-github/blob/main/scripts/validate_weekly_rankings.py): `scripts/validate_weekly_rankings.py`

### Other components

- **Catalog Reader**
- **GitHub Search API**

## Connections

- Catalog Reader → Curated Picks: browses (evidence: `README.md`)
- Daily Picker → GitHub Search API: queries (evidence: `scripts/update_github_of_the_day.py`)
- Daily Picker → Curated Picks: updates pick (evidence: `scripts/update_github_of_the_day.py`)
- Daily Picker → Daily Archive: appends selection (evidence: `scripts/update_github_of_the_day.py`)
- Weekly Generator → GitHub Search API: fetches repositories (evidence: `scripts/update_weekly_rankings.py`)
- Weekly Generator → Top 100 Report: writes report (evidence: `README.md`)
- Weekly Generator → Top 250 Report: writes report (evidence: `README.md`)
- Report Validator → Top 100 Report: validates (evidence: `scripts/validate_weekly_rankings.py`)
- Report Validator → Top 250 Report: validates (evidence: `scripts/validate_weekly_rankings.py`)
- Report Validator → Curated Picks: checks freshness (evidence: `scripts/validate_weekly_rankings.py`)
