# emanuel36/trending-repos-site architecture

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

- Interactive diagram: https://gitdiagram.com/emanuel36/trending-repos-site
- Repository: https://github.com/emanuel36/trending-repos-site

## Overview

This is a daily trending-repository publishing job: its CLI starts the run coordinator, which filters previously seen repositories, gathers two rankings, enriches candidates, queues them, summarizes them with Gemini, then saves and renders daily pages and the history index. The README also documents a systemd schedule and password-protected HTTPS serving. The sampled source supports the job’s internal calls; deployment and serving relationships below rely on README statements rather than inspected deployment-file contents.

Main entry points: [`trending_site/run.py`](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/run.py) (Run coordinator), [`trending_site/render.py`](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/render.py) (HTML renderer), [`trending_site/__main__.py`](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/__main__.py) (CLI entry), [`trending_site/gemini.py`](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/gemini.py) (Gemini client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_job["Job control"]
  node_cli["CLI entry<br/>[__main__.py]"]
  node_coordinator["Run coordinator<br/>[run.py]"]
end

subgraph group_discovery["Repository discovery"]
  node_trendshift["Trendshift ranking<br/>[sources.py]"]
  node_githubtrend["GitHub Trending<br/>[sources.py]"]
  node_enrichment["Repo enrichment<br/>[sources.py]"]
  node_trendshift_service["Trendshift"]
  node_github["GitHub API"]
end

subgraph group_summaries["Summary generation"]
  node_gemini_client["Gemini client<br/>[gemini.py]"]
  node_summary_contract["Summary format<br/>[summary.py]"]
  node_gemini_service["Gemini API"]
end

subgraph group_publication["State and publication"]
  node_state[("Run state<br/>[state.py]")]
  node_atomic_files["Atomic writes<br/>[files.py]"]
  node_renderer["HTML renderer<br/>[render.py]"]
  node_template["Page template<br/>[page.html]"]
end

subgraph group_hosting["Scheduled hosting"]
  node_timer["Daily timer"]
  node_service["Job service"]
  node_published_site["Published pages"]
  node_caddy["HTTPS and login"]
end

node_operator(("Operator"))
node_visitor(("Site visitor"))

node_operator -->|"starts job"| node_cli
node_timer -->|"triggers daily"| node_service
node_service -->|"runs command"| node_cli
node_cli -->|"starts run"| node_coordinator
node_cli -->|"configures client"| node_gemini_client
node_coordinator -->|"fetches ranking"| node_trendshift
node_coordinator -->|"fetches ranking"| node_githubtrend
node_trendshift -->|"reads ranking"| node_trendshift_service
node_githubtrend -->|"reads ranking"| node_github
node_coordinator -->|"enriches repos"| node_enrichment
node_enrichment -->|"reads repo data"| node_github
node_coordinator -->|"loads and saves"| node_state
node_coordinator -->|"requests summaries"| node_gemini_client
node_gemini_client -->|"builds and validates"| node_summary_contract
node_gemini_client -->|"posts requests"| node_gemini_service
node_coordinator -->|"renders pages"| node_renderer
node_renderer -->|"fills template"| node_template
node_state -->|"writes state"| node_atomic_files
node_renderer -->|"writes HTML"| node_atomic_files
node_renderer -->|"publishes files"| node_published_site
node_caddy -->|"serves protected pages"| node_published_site
node_visitor -->|"visits site"| node_caddy

click node_timer "https://github.com/emanuel36/trending-repos-site/blob/master/deploy/trending-site.timer"
click node_service "https://github.com/emanuel36/trending-repos-site/blob/master/deploy/trending-site.service"
click node_cli "https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/__main__.py"
click node_coordinator "https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/run.py"
click node_trendshift "https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/sources.py"
click node_githubtrend "https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/sources.py"
click node_enrichment "https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/sources.py"
click node_gemini_client "https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/gemini.py"
click node_summary_contract "https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/summary.py"
click node_state "https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/state.py"
click node_atomic_files "https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/files.py"
click node_renderer "https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/render.py"
click node_template "https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/assets/page.html"
click node_caddy "https://github.com/emanuel36/trending-repos-site/blob/master/deploy/Caddyfile"

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_cli,node_coordinator toneBlue
class node_trendshift,node_githubtrend,node_enrichment,node_trendshift_service,node_github toneAmber
class node_gemini_client,node_summary_contract,node_gemini_service toneMint
class node_state,node_atomic_files,node_renderer,node_template toneRose
class node_timer,node_service,node_published_site,node_caddy,node_operator,node_visitor toneIndigo
```

## Components

### Job control

- [CLI entry](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/__main__.py): `trending_site/__main__.py`
- [Run coordinator](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/run.py): `trending_site/run.py`

### Repository discovery

- [Trendshift ranking](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/sources.py): `trending_site/sources.py`
- [GitHub Trending](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/sources.py): `trending_site/sources.py`
- [Repo enrichment](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/sources.py): `trending_site/sources.py`
- **Trendshift**
- **GitHub API**

### Summary generation

- [Gemini client](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/gemini.py): `trending_site/gemini.py`
- [Summary format](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/summary.py): `trending_site/summary.py`
- **Gemini API**

### State and publication

- [Run state](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/state.py): `trending_site/state.py`
- [Atomic writes](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/files.py): `trending_site/files.py`
- [HTML renderer](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/render.py): `trending_site/render.py`
- [Page template](https://github.com/emanuel36/trending-repos-site/blob/master/trending_site/assets/page.html): `trending_site/assets/page.html`

### Scheduled hosting

- [Daily timer](https://github.com/emanuel36/trending-repos-site/blob/master/deploy/trending-site.timer): `deploy/trending-site.timer`
- [Job service](https://github.com/emanuel36/trending-repos-site/blob/master/deploy/trending-site.service): `deploy/trending-site.service`
- **Published pages**
- [HTTPS and login](https://github.com/emanuel36/trending-repos-site/blob/master/deploy/Caddyfile): `deploy/Caddyfile`

### Other components

- **Operator**
- **Site visitor**

## Connections

- Operator → CLI entry: starts job (evidence: `README.md`)
- Daily timer → Job service: triggers daily (evidence: `README.md`)
- Job service → CLI entry: runs command (evidence: `README.md`)
- CLI entry → Run coordinator: starts run (evidence: `trending_site/__main__.py`)
- CLI entry → Gemini client: configures client (evidence: `trending_site/__main__.py`)
- Run coordinator → Trendshift ranking: fetches ranking (evidence: `trending_site/run.py`)
- Run coordinator → GitHub Trending: fetches ranking (evidence: `trending_site/run.py`)
- Trendshift ranking → Trendshift: reads ranking (evidence: `trending_site/sources.py`)
- GitHub Trending → GitHub API: reads ranking (evidence: `trending_site/sources.py`)
- Run coordinator → Repo enrichment: enriches repos (evidence: `trending_site/run.py`)
- Repo enrichment → GitHub API: reads repo data (evidence: `trending_site/sources.py`)
- Run coordinator → Run state: loads and saves (evidence: `trending_site/run.py`)
- Run coordinator → Gemini client: requests summaries (evidence: `trending_site/run.py`)
- Gemini client → Summary format: builds and validates (evidence: `trending_site/gemini.py`)
- Gemini client → Gemini API: posts requests (evidence: `trending_site/gemini.py`)
- Run coordinator → HTML renderer: renders pages (evidence: `trending_site/run.py`)
- HTML renderer → Page template: fills template (evidence: `trending_site/render.py`)
- Run state → Atomic writes: writes state (evidence: `trending_site/state.py`)
- HTML renderer → Atomic writes: writes HTML (evidence: `trending_site/render.py`)
- HTML renderer → Published pages: publishes files (evidence: `README.md`)
- HTTPS and login → Published pages: serves protected pages (evidence: `README.md`)
- Site visitor → HTTPS and login: visits site (evidence: `README.md`)