# lc-lly/ai-hot architecture

> Architecture diagram of the GitHub repository lc-lly/ai-hot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lc-lly/ai-hot
- Repository: https://github.com/lc-lly/ai-hot

## Overview

ai-hot aggregates public AI-related feeds, filters and scores items, triages them with a budgeted multi-stage AI layer, clusters related coverage, and matches configured monitoring topics for notifications. The primary user workflow is a dashboard request or scheduled/manual collection through source adapters and ingestion, followed by AI triage and topic matching; results appear in the feed and realtime updates. The README documents several subsystem relationships not visible in sampled implementation excerpts, so those edges cite the README; uncertain internal calls are omitted.

Main entry points: [`server/src/jobs/scheduler.ts`](https://github.com/lc-lly/ai-hot/blob/main/server/src/jobs/scheduler.ts) (Job scheduler), [`web/src/state/useDashboard.ts`](https://github.com/lc-lly/ai-hot/blob/main/web/src/state/useDashboard.ts) (Dashboard state), [`server/src/pipeline/ingest.ts`](https://github.com/lc-lly/ai-hot/blob/main/server/src/pipeline/ingest.ts) (Ingestion pipeline), [`server/src/db.ts`](https://github.com/lc-lly/ai-hot/blob/main/server/src/db.ts) (SQLite database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection and analysis"]
  node_source_adapters["Source adapters"]
  node_ingestion["Ingestion pipeline<br/>[ingest.ts]"]
  node_scoring["Heat and importance"]
  node_clustering["Hotspot clustering"]
end

subgraph group_ai["AI triage"]
  node_ai_triage["Layered AI triage"]
  node_ai_client["AI client and budget<br/>[client.ts]"]
end

subgraph group_jobs["Scheduled work"]
  node_jobs["Job scheduler<br/>[scheduler.ts]"]
  node_discover["Domain discovery"]
end

subgraph group_backend["Backend services"]
  node_http_api["HTTP routes"]
  node_database[("SQLite database<br/>[db.ts]")]
  node_topic_matching["Topic matching"]
  node_notifications["Notifications"]
  node_search["External search<br/>[search.ts]"]
  node_realtime_server["WebSocket broadcast<br/>[server.ts]"]
end

subgraph group_web["Dashboard"]
  node_dashboard["Dashboard app<br/>[App.tsx]"]
  node_dashboard_state["Dashboard state<br/>[useDashboard.ts]"]
  node_feed_state["Feed state<br/>[useFeed.ts]"]
  node_api_client["HTTP client<br/>[api.ts]"]
  node_realtime_client["Realtime client<br/>[useRealtime.ts]"]
  node_feed_views["Feed and controls"]
end

node_user(("User"))
node_mail_service["Email and Web Push"]

node_user -->|"uses"| node_dashboard
node_dashboard -->|"composes"| node_dashboard_state
node_dashboard -->|"renders"| node_feed_views
node_dashboard_state -->|"uses"| node_feed_state
node_dashboard_state -->|"requests"| node_api_client
node_feed_state -->|"fetches"| node_api_client
node_dashboard_state -->|"handles updates"| node_realtime_client
node_api_client -->|"calls"| node_http_api
node_http_api -.->|"reads and writes"| node_database
node_jobs -->|"collects from"| node_source_adapters
node_source_adapters -->|"supplies items"| node_ingestion
node_ingestion -->|"calculates scores"| node_scoring
node_ingestion -->|"persists items"| node_database
node_jobs -->|"runs collection"| node_ingestion
node_jobs -->|"runs triage"| node_ai_triage
node_ai_triage -.->|"requests model"| node_ai_client
node_ai_client -->|"caches results"| node_database
node_ai_triage -.->|"evaluates items"| node_topic_matching
node_topic_matching -->|"triggers alerts"| node_notifications
node_notifications -->|"sends through"| node_mail_service
node_jobs -->|"runs discovery"| node_discover
node_http_api -->|"routes search"| node_search
node_realtime_server -->|"streams updates"| node_dashboard_state
node_jobs -.->|"clusters coverage"| node_clustering
node_clustering -.->|"stores clusters"| node_database

click node_dashboard "https://github.com/lc-lly/ai-hot/blob/main/web/src/App.tsx"
click node_dashboard_state "https://github.com/lc-lly/ai-hot/blob/main/web/src/state/useDashboard.ts"
click node_feed_state "https://github.com/lc-lly/ai-hot/blob/main/web/src/state/useFeed.ts"
click node_api_client "https://github.com/lc-lly/ai-hot/blob/main/web/src/net/api.ts"
click node_realtime_client "https://github.com/lc-lly/ai-hot/blob/main/web/src/net/useRealtime.ts"
click node_feed_views "https://github.com/lc-lly/ai-hot/tree/main/web/src/components"
click node_http_api "https://github.com/lc-lly/ai-hot/tree/main/server/src/routes"
click node_database "https://github.com/lc-lly/ai-hot/blob/main/server/src/db.ts"
click node_source_adapters "https://github.com/lc-lly/ai-hot/tree/main/server/src/sources"
click node_ingestion "https://github.com/lc-lly/ai-hot/blob/main/server/src/pipeline/ingest.ts"
click node_scoring "https://github.com/lc-lly/ai-hot/tree/main/server/src/score"
click node_clustering "https://github.com/lc-lly/ai-hot/tree/main/server/src/cluster"
click node_ai_triage "https://github.com/lc-lly/ai-hot/tree/main/server/src/ai"
click node_ai_client "https://github.com/lc-lly/ai-hot/blob/main/server/src/ai/client.ts"
click node_topic_matching "https://github.com/lc-lly/ai-hot/tree/main/server/src/triage"
click node_notifications "https://github.com/lc-lly/ai-hot/tree/main/server/src/notify"
click node_jobs "https://github.com/lc-lly/ai-hot/blob/main/server/src/jobs/scheduler.ts"
click node_discover "https://github.com/lc-lly/ai-hot/tree/main/server/src/discover"
click node_search "https://github.com/lc-lly/ai-hot/blob/main/server/src/routes/search.ts"
click node_realtime_server "https://github.com/lc-lly/ai-hot/blob/main/server/src/realtime/server.ts"

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_source_adapters,node_ingestion,node_scoring,node_clustering,node_user toneBlue
class node_ai_triage,node_ai_client toneAmber
class node_jobs,node_discover toneMint
class node_http_api,node_database,node_topic_matching,node_notifications,node_search,node_realtime_server toneRose
class node_dashboard,node_dashboard_state,node_feed_state,node_api_client,node_realtime_client,node_feed_views,node_mail_service toneIndigo
```

## Components

### Collection and analysis

- [Source adapters](https://github.com/lc-lly/ai-hot/tree/main/server/src/sources): `server/src/sources`
- [Ingestion pipeline](https://github.com/lc-lly/ai-hot/blob/main/server/src/pipeline/ingest.ts): `server/src/pipeline/ingest.ts`
- [Heat and importance](https://github.com/lc-lly/ai-hot/tree/main/server/src/score): `server/src/score`
- [Hotspot clustering](https://github.com/lc-lly/ai-hot/tree/main/server/src/cluster): `server/src/cluster`

### AI triage

- [Layered AI triage](https://github.com/lc-lly/ai-hot/tree/main/server/src/ai): `server/src/ai`
- [AI client and budget](https://github.com/lc-lly/ai-hot/blob/main/server/src/ai/client.ts): `server/src/ai/client.ts`

### Scheduled work

- [Job scheduler](https://github.com/lc-lly/ai-hot/blob/main/server/src/jobs/scheduler.ts): `server/src/jobs/scheduler.ts`
- [Domain discovery](https://github.com/lc-lly/ai-hot/tree/main/server/src/discover): `server/src/discover`

### Backend services

- [HTTP routes](https://github.com/lc-lly/ai-hot/tree/main/server/src/routes): `server/src/routes`
- [SQLite database](https://github.com/lc-lly/ai-hot/blob/main/server/src/db.ts): `server/src/db.ts`
- [Topic matching](https://github.com/lc-lly/ai-hot/tree/main/server/src/triage): `server/src/triage`
- [Notifications](https://github.com/lc-lly/ai-hot/tree/main/server/src/notify): `server/src/notify`
- [External search](https://github.com/lc-lly/ai-hot/blob/main/server/src/routes/search.ts): `server/src/routes/search.ts`
- [WebSocket broadcast](https://github.com/lc-lly/ai-hot/blob/main/server/src/realtime/server.ts): `server/src/realtime/server.ts`

### Dashboard

- [Dashboard app](https://github.com/lc-lly/ai-hot/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Dashboard state](https://github.com/lc-lly/ai-hot/blob/main/web/src/state/useDashboard.ts): `web/src/state/useDashboard.ts`
- [Feed state](https://github.com/lc-lly/ai-hot/blob/main/web/src/state/useFeed.ts): `web/src/state/useFeed.ts`
- [HTTP client](https://github.com/lc-lly/ai-hot/blob/main/web/src/net/api.ts): `web/src/net/api.ts`
- [Realtime client](https://github.com/lc-lly/ai-hot/blob/main/web/src/net/useRealtime.ts): `web/src/net/useRealtime.ts`
- [Feed and controls](https://github.com/lc-lly/ai-hot/tree/main/web/src/components): `web/src/components`

### Other components

- **User**
- **Email and Web Push**

## Connections

- User → Dashboard app: uses
- Dashboard app → Dashboard state: composes (evidence: `web/src/App.tsx`)
- Dashboard app → Feed and controls: renders (evidence: `web/src/App.tsx`)
- Dashboard state → Feed state: uses (evidence: `web/src/state/useDashboard.ts`)
- Dashboard state → HTTP client: requests (evidence: `web/src/state/useDashboard.ts`)
- Feed state → HTTP client: fetches (evidence: `web/src/state/useFeed.ts`)
- Dashboard state → Realtime client: handles updates (evidence: `web/src/state/useDashboard.ts`)
- HTTP client → HTTP routes: calls
- HTTP routes → SQLite database: reads and writes
- Job scheduler → Source adapters: collects from
- Source adapters → Ingestion pipeline: supplies items (evidence: `server/src/pipeline/ingest.ts`)
- Ingestion pipeline → Heat and importance: calculates scores (evidence: `server/src/pipeline/ingest.ts`)
- Ingestion pipeline → SQLite database: persists items (evidence: `server/src/pipeline/ingest.ts`)
- Job scheduler → Ingestion pipeline: runs collection
- Job scheduler → Layered AI triage: runs triage
- Layered AI triage → AI client and budget: requests model (evidence: `server/src/ai/authenticity.ts`)
- AI client and budget → SQLite database: caches results (evidence: `server/src/ai/client.ts`)
- Layered AI triage → Topic matching: evaluates items
- Topic matching → Notifications: triggers alerts
- Notifications → Email and Web Push: sends through
- Job scheduler → Domain discovery: runs discovery
- HTTP routes → External search: routes search (evidence: `server/src/app.ts`)
- WebSocket broadcast → Dashboard state: streams updates
- Job scheduler → Hotspot clustering: clusters coverage
- Hotspot clustering → SQLite database: stores clusters
