# djangopeng/githubsentinel architecture

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

- Interactive diagram: https://gitdiagram.com/djangopeng/githubsentinel
- Repository: https://github.com/djangopeng/githubsentinel

## Overview

GitHub Sentinel turns subscribed GitHub activity and Hacker News stories into LLM-written reports, with interactive CLI/Gradio and scheduled daemon entry points. The graph preserves subscription management, source retrieval, report generation, model integrations, and email delivery. Edges follow shown calls or README descriptions; the source excerpts do not establish every runtime detail, so unsampled integrations and paths are not inferred.

Main entry points: [`src/command_tool.py`](https://github.com/djangopeng/githubsentinel/blob/main/src/command_tool.py) (Interactive CLI), [`src/gradio_server.py`](https://github.com/djangopeng/githubsentinel/blob/main/src/gradio_server.py) (Gradio interface), [`src/daemon_process.py`](https://github.com/djangopeng/githubsentinel/blob/main/src/daemon_process.py) (Scheduled daemon), [`src/report_generator.py`](https://github.com/djangopeng/githubsentinel/blob/main/src/report_generator.py) (Report generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces and scheduling"]
  node_cli["Interactive CLI<br/>[command_tool.py]"]
  node_commands["Command handler<br/>[command_handler.py]"]
  node_gui["Gradio interface<br/>[gradio_server.py]"]
  node_daemon["Scheduled daemon<br/>[daemon_process.py]"]
end

subgraph group_sources["Subscriptions and source retrieval"]
  node_subscriptions["Subscription manager"]
  node_substore["Subscriptions file<br/>[subscriptions.json]"]
  node_github["GitHub retrieval<br/>[github_client.py]"]
  node_hn["Hacker News retrieval"]
end

subgraph group_reports["Report generation and models"]
  node_reports["Report generation"]
  node_prompts["Report prompts"]
  node_llm["Model adapter<br/>[llm.py]"]
end

subgraph group_delivery["Configuration and delivery"]
  node_config["Configuration<br/>[config.py]"]
  node_configfile["Application config<br/>[config.json]"]
  node_notifier["Email notifier<br/>[notifier.py]"]
end

node_user(("User"))
node_githubapi["GitHub API"]
node_hnsite["Hacker News"]
node_openai["OpenAI API"]
node_ollama["Ollama service"]
node_smtp["SMTP service"]

node_user -->|"enters commands"| node_cli
node_user -->|"uses interface"| node_gui
node_cli -->|"loads"| node_config
node_cli -->|"creates"| node_github
node_cli -->|"creates"| node_llm
node_cli -->|"creates"| node_reports
node_cli -->|"creates"| node_subscriptions
node_cli -->|"dispatches to"| node_commands
node_commands -->|"manages"| node_subscriptions
node_commands -->|"exports updates"| node_github
node_commands -->|"generates report"| node_reports
node_subscriptions -->|"reads and writes"| node_substore
node_github -->|"fetches updates"| node_githubapi
node_hn -->|"fetches stories"| node_hnsite
node_gui -->|"loads"| node_config
node_gui -->|"exports progress"| node_github
node_gui -->|"exports stories"| node_hn
node_gui -->|"creates"| node_llm
node_gui -->|"generates reports"| node_reports
node_gui -->|"lists subscriptions"| node_subscriptions
node_daemon -->|"loads"| node_config
node_daemon -->|"reads subscriptions"| node_subscriptions
node_daemon -->|"exports progress"| node_github
node_daemon -->|"exports stories"| node_hn
node_daemon -->|"generates reports"| node_reports
node_daemon -->|"sends reports"| node_notifier
node_reports -->|"loads prompts"| node_prompts
node_reports -->|"requests generation"| node_llm
node_llm -->|"calls model"| node_openai
node_llm -->|"posts prompt"| node_ollama
node_notifier -->|"sends email"| node_smtp
node_config -->|"reads settings"| node_configfile

click node_cli "https://github.com/djangopeng/githubsentinel/blob/main/src/command_tool.py"
click node_commands "https://github.com/djangopeng/githubsentinel/blob/main/src/command_handler.py"
click node_gui "https://github.com/djangopeng/githubsentinel/blob/main/src/gradio_server.py"
click node_daemon "https://github.com/djangopeng/githubsentinel/blob/main/src/daemon_process.py"
click node_subscriptions "https://github.com/djangopeng/githubsentinel/blob/main/src/subscription_manager.py"
click node_substore "https://github.com/djangopeng/githubsentinel/blob/main/subscriptions.json"
click node_github "https://github.com/djangopeng/githubsentinel/blob/main/src/github_client.py"
click node_hn "https://github.com/djangopeng/githubsentinel/blob/main/src/hacker_news_client.py"
click node_reports "https://github.com/djangopeng/githubsentinel/blob/main/src/report_generator.py"
click node_prompts "https://github.com/djangopeng/githubsentinel/tree/main/prompts"
click node_llm "https://github.com/djangopeng/githubsentinel/blob/main/src/llm.py"
click node_config "https://github.com/djangopeng/githubsentinel/blob/main/src/config.py"
click node_configfile "https://github.com/djangopeng/githubsentinel/blob/main/config.json"
click node_notifier "https://github.com/djangopeng/githubsentinel/blob/main/src/notifier.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_cli,node_commands,node_gui,node_daemon,node_user toneBlue
class node_subscriptions,node_substore,node_github,node_hn toneAmber
class node_reports,node_prompts,node_llm,node_githubapi,node_openai toneMint
class node_config,node_configfile,node_notifier toneRose
class node_hnsite,node_ollama,node_smtp toneIndigo
```

## Components

### User interfaces and scheduling

- [Interactive CLI](https://github.com/djangopeng/githubsentinel/blob/main/src/command_tool.py): `src/command_tool.py`
- [Command handler](https://github.com/djangopeng/githubsentinel/blob/main/src/command_handler.py): `src/command_handler.py`
- [Gradio interface](https://github.com/djangopeng/githubsentinel/blob/main/src/gradio_server.py): `src/gradio_server.py`
- [Scheduled daemon](https://github.com/djangopeng/githubsentinel/blob/main/src/daemon_process.py): `src/daemon_process.py`

### Subscriptions and source retrieval

- [Subscription manager](https://github.com/djangopeng/githubsentinel/blob/main/src/subscription_manager.py): `src/subscription_manager.py`
- [Subscriptions file](https://github.com/djangopeng/githubsentinel/blob/main/subscriptions.json): `subscriptions.json`
- [GitHub retrieval](https://github.com/djangopeng/githubsentinel/blob/main/src/github_client.py): `src/github_client.py`
- [Hacker News retrieval](https://github.com/djangopeng/githubsentinel/blob/main/src/hacker_news_client.py): `src/hacker_news_client.py`

### Report generation and models

- [Report generation](https://github.com/djangopeng/githubsentinel/blob/main/src/report_generator.py): `src/report_generator.py`
- [Report prompts](https://github.com/djangopeng/githubsentinel/tree/main/prompts): `prompts`
- [Model adapter](https://github.com/djangopeng/githubsentinel/blob/main/src/llm.py): `src/llm.py`

### Configuration and delivery

- [Configuration](https://github.com/djangopeng/githubsentinel/blob/main/src/config.py): `src/config.py`
- [Application config](https://github.com/djangopeng/githubsentinel/blob/main/config.json): `config.json`
- [Email notifier](https://github.com/djangopeng/githubsentinel/blob/main/src/notifier.py): `src/notifier.py`

### Other components

- **User**
- **GitHub API**
- **Hacker News**
- **OpenAI API**
- **Ollama service**
- **SMTP service**

## Connections

- User → Interactive CLI: enters commands (evidence: `README.md`)
- User → Gradio interface: uses interface (evidence: `README.md`)
- Interactive CLI → Configuration: loads (evidence: `src/command_tool.py`)
- Interactive CLI → GitHub retrieval: creates (evidence: `src/command_tool.py`)
- Interactive CLI → Model adapter: creates (evidence: `src/command_tool.py`)
- Interactive CLI → Report generation: creates (evidence: `src/command_tool.py`)
- Interactive CLI → Subscription manager: creates (evidence: `src/command_tool.py`)
- Interactive CLI → Command handler: dispatches to (evidence: `src/command_tool.py`)
- Command handler → Subscription manager: manages (evidence: `src/command_handler.py`)
- Command handler → GitHub retrieval: exports updates (evidence: `src/command_handler.py`)
- Command handler → Report generation: generates report (evidence: `src/command_handler.py`)
- Subscription manager → Subscriptions file: reads and writes (evidence: `src/subscription_manager.py`)
- GitHub retrieval → GitHub API: fetches updates (evidence: `src/github_client.py`)
- Hacker News retrieval → Hacker News: fetches stories (evidence: `src/hacker_news_client.py`)
- Gradio interface → Configuration: loads (evidence: `src/gradio_server.py`)
- Gradio interface → GitHub retrieval: exports progress (evidence: `src/gradio_server.py`)
- Gradio interface → Hacker News retrieval: exports stories (evidence: `src/gradio_server.py`)
- Gradio interface → Model adapter: creates (evidence: `src/gradio_server.py`)
- Gradio interface → Report generation: generates reports (evidence: `src/gradio_server.py`)
- Gradio interface → Subscription manager: lists subscriptions (evidence: `src/gradio_server.py`)
- Scheduled daemon → Configuration: loads (evidence: `src/daemon_process.py`)
- Scheduled daemon → Subscription manager: reads subscriptions (evidence: `src/daemon_process.py`)
- Scheduled daemon → GitHub retrieval: exports progress (evidence: `src/daemon_process.py`)
- Scheduled daemon → Hacker News retrieval: exports stories (evidence: `src/daemon_process.py`)
- Scheduled daemon → Report generation: generates reports (evidence: `src/daemon_process.py`)
- Scheduled daemon → Email notifier: sends reports (evidence: `src/daemon_process.py`)
- Report generation → Report prompts: loads prompts (evidence: `src/report_generator.py`)
- Report generation → Model adapter: requests generation (evidence: `src/report_generator.py`)
- Model adapter → OpenAI API: calls model (evidence: `src/llm.py`)
- Model adapter → Ollama service: posts prompt (evidence: `src/llm.py`)
- Email notifier → SMTP service: sends email (evidence: `src/notifier.py`)
- Configuration → Application config: reads settings (evidence: `src/config.py`)