# kkkkhazix/aihot architecture

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

- Interactive diagram: https://gitdiagram.com/kkkkhazix/aihot
- Repository: https://github.com/kkkkhazix/aihot

## Overview

AIHOT is a configurable AI news site: it collects industry sources, screens and independently scores items, writes localized summaries, clusters related coverage into events, ranks their heat, and publishes reports and feeds. The graph follows the documented workflow and sampled API/worker entry points; several backend stages are represented at their exact enclosing paths because their implementation was not sampled. It also preserves the documented admin, model leaderboard, Codex monitor, and Agent-facing interfaces.

Main entry points: [`packages/backend/src/db.ts`](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/db.ts) (PostgreSQL), [`apps/worker/src/main.ts`](https://github.com/kkkkhazix/aihot/blob/main/apps/worker/src/main.ts) (Worker scheduler), [`packages/backend/src/jobs/content.ts`](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/jobs/content.ts) (Content jobs), [`packages/backend/src/events/group.ts`](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/events/group.ts) (Cluster and rank)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection"]
  node_sources["Source adapters<br/>[collect.ts]"]
  node_push["Push ingestion<br/>[items.ts]"]
  node_ingest_api["Ingest endpoint<br/>[ingest.ts]"]
  node_source_jobs["Collection jobs<br/>[sources.ts]"]
  node_worker["Worker scheduler<br/>[main.ts]"]
end

subgraph group_editorial["Editorial pipeline"]
  node_editorial_jobs["Content jobs<br/>[content.ts]"]
  node_screen["Screen and score<br/>[analyze.ts]"]
  node_write["Translate and write<br/>[writing.ts]"]
  node_llm["Language models<br/>[llm.ts]"]
end

subgraph group_events["Events and publishing"]
  node_events_jobs["Event jobs<br/>[events.ts]"]
  node_grouping["Cluster and rank<br/>[group.ts]"]
  node_embeddings["Vector recall<br/>[embeddings.ts]"]
  node_publication_jobs["Publication jobs<br/>[publication.ts]"]
  node_reports["Report composition<br/>[compose.ts]"]
  node_publication["Public content<br/>[items.ts]"]
end

subgraph group_interfaces["Reader and Agent interfaces"]
  node_web["Website routes<br/>[routes.ts]"]
  node_api["HTTP API<br/>[app.ts]"]
  node_agent["Agent exports<br/>[llms.ts]"]
end

subgraph group_operations["Admin and extensions"]
  node_admin["Admin operations<br/>[content.ts]"]
  node_leaderboard["Model leaderboard<br/>[index.ts]"]
  node_monitor["Reset monitor<br/>[scan.ts]"]
end

node_database[("PostgreSQL<br/>[db.ts]")]
node_source_services(("Configured sources"))
node_push_client(("Push clients"))
node_model_provider(("LLM provider"))
node_embedding_provider(("Embedding provider"))
node_readers(("Readers"))
node_agents(("Agents"))

node_worker -->|"registers"| node_source_jobs
node_source_jobs -->|"collects from"| node_sources
node_source_services -->|"provides items"| node_sources
node_push_client -->|"submits items"| node_ingest_api
node_ingest_api -->|"calls"| node_push
node_worker -->|"registers"| node_editorial_jobs
node_editorial_jobs -->|"processes items"| node_screen
node_screen -->|"scores with"| node_llm
node_llm -->|"requests"| node_model_provider
node_editorial_jobs -->|"processes selected"| node_write
node_write -->|"generates with"| node_llm
node_worker -->|"registers"| node_events_jobs
node_events_jobs -->|"processes events"| node_grouping
node_grouping -->|"recalls candidates"| node_embeddings
node_embeddings -.->|"embeds text"| node_embedding_provider
node_worker -->|"registers"| node_publication_jobs
node_publication_jobs -->|"composes reports"| node_reports
node_publication -->|"reads content"| node_database
node_grouping -->|"reads and writes"| node_database
node_reports -->|"writes reports"| node_database
node_web -->|"serves pages"| node_publication
node_api -->|"serves endpoints"| node_publication
node_agent -->|"checks availability"| node_database
node_api -->|"serves discovery"| node_agent
node_readers -->|"browses"| node_web
node_agents -->|"requests data"| node_api
node_agents -->|"reads discovery"| node_agent
node_admin -->|"manages content"| node_database
node_leaderboard -->|"stores rankings"| node_database
node_monitor -->|"records observations"| node_database

click node_sources "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/sources/collect.ts"
click node_push "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/ingest/items.ts"
click node_ingest_api "https://github.com/kkkkhazix/aihot/blob/main/apps/api/src/routes/ingest.ts"
click node_source_jobs "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/jobs/sources.ts"
click node_worker "https://github.com/kkkkhazix/aihot/blob/main/apps/worker/src/main.ts"
click node_editorial_jobs "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/jobs/content.ts"
click node_screen "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/editorial/analyze.ts"
click node_write "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/editorial/writing.ts"
click node_llm "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/providers/llm.ts"
click node_events_jobs "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/jobs/events.ts"
click node_grouping "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/events/group.ts"
click node_embeddings "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/providers/embeddings.ts"
click node_publication_jobs "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/jobs/publication.ts"
click node_reports "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/reports/compose.ts"
click node_publication "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/publication/items.ts"
click node_web "https://github.com/kkkkhazix/aihot/blob/main/apps/web/app/routes.ts"
click node_api "https://github.com/kkkkhazix/aihot/blob/main/apps/api/src/app.ts"
click node_agent "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/publication/llms.ts"
click node_admin "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/admin/content.ts"
click node_leaderboard "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/leaderboard/fetch/index.ts"
click node_monitor "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/monitor/scan.ts"
click node_database "https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/db.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_sources,node_push,node_ingest_api,node_source_jobs,node_worker,node_push_client toneBlue
class node_editorial_jobs,node_screen,node_write,node_llm,node_database toneAmber
class node_events_jobs,node_grouping,node_embeddings,node_publication_jobs,node_reports,node_publication toneMint
class node_web,node_api,node_agent toneRose
class node_admin,node_leaderboard,node_monitor,node_source_services,node_model_provider,node_embedding_provider,node_readers,node_agents toneIndigo
```

## Components

### Collection

- [Source adapters](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/sources/collect.ts): `packages/backend/src/sources/collect.ts`
- [Push ingestion](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/ingest/items.ts): `packages/backend/src/ingest/items.ts`
- [Ingest endpoint](https://github.com/kkkkhazix/aihot/blob/main/apps/api/src/routes/ingest.ts): `apps/api/src/routes/ingest.ts`
- [Collection jobs](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/jobs/sources.ts): `packages/backend/src/jobs/sources.ts`
- [Worker scheduler](https://github.com/kkkkhazix/aihot/blob/main/apps/worker/src/main.ts): `apps/worker/src/main.ts`

### Editorial pipeline

- [Content jobs](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/jobs/content.ts): `packages/backend/src/jobs/content.ts`
- [Screen and score](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/editorial/analyze.ts): `packages/backend/src/editorial/analyze.ts`
- [Translate and write](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/editorial/writing.ts): `packages/backend/src/editorial/writing.ts`
- [Language models](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/providers/llm.ts): `packages/backend/src/providers/llm.ts`

### Events and publishing

- [Event jobs](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/jobs/events.ts): `packages/backend/src/jobs/events.ts`
- [Cluster and rank](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/events/group.ts): `packages/backend/src/events/group.ts`
- [Vector recall](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/providers/embeddings.ts): `packages/backend/src/providers/embeddings.ts`
- [Publication jobs](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/jobs/publication.ts): `packages/backend/src/jobs/publication.ts`
- [Report composition](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/reports/compose.ts): `packages/backend/src/reports/compose.ts`
- [Public content](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/publication/items.ts): `packages/backend/src/publication/items.ts`

### Reader and Agent interfaces

- [Website routes](https://github.com/kkkkhazix/aihot/blob/main/apps/web/app/routes.ts): `apps/web/app/routes.ts`
- [HTTP API](https://github.com/kkkkhazix/aihot/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Agent exports](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/publication/llms.ts): `packages/backend/src/publication/llms.ts`

### Admin and extensions

- [Admin operations](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/admin/content.ts): `packages/backend/src/admin/content.ts`
- [Model leaderboard](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/leaderboard/fetch/index.ts): `packages/backend/src/leaderboard/fetch/index.ts`
- [Reset monitor](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/monitor/scan.ts): `packages/backend/src/monitor/scan.ts`

### Other components

- [PostgreSQL](https://github.com/kkkkhazix/aihot/blob/main/packages/backend/src/db.ts): `packages/backend/src/db.ts`
- **Configured sources**
- **Push clients**
- **LLM provider**
- **Embedding provider**
- **Readers**
- **Agents**

## Connections

- Worker scheduler → Collection jobs: registers
- Collection jobs → Source adapters: collects from
- Configured sources → Source adapters: provides items
- Push clients → Ingest endpoint: submits items
- Ingest endpoint → Push ingestion: calls
- Worker scheduler → Content jobs: registers
- Content jobs → Screen and score: processes items
- Screen and score → Language models: scores with
- Language models → LLM provider: requests
- Content jobs → Translate and write: processes selected
- Translate and write → Language models: generates with
- Worker scheduler → Event jobs: registers
- Event jobs → Cluster and rank: processes events
- Cluster and rank → Vector recall: recalls candidates
- Vector recall → Embedding provider: embeds text
- Worker scheduler → Publication jobs: registers
- Publication jobs → Report composition: composes reports
- Public content → PostgreSQL: reads content
- Cluster and rank → PostgreSQL: reads and writes
- Report composition → PostgreSQL: writes reports
- Website routes → Public content: serves pages
- HTTP API → Public content: serves endpoints
- Agent exports → PostgreSQL: checks availability
- HTTP API → Agent exports: serves discovery
- Readers → Website routes: browses
- Agents → HTTP API: requests data
- Agents → Agent exports: reads discovery
- Admin operations → PostgreSQL: manages content
- Model leaderboard → PostgreSQL: stores rankings
- Reset monitor → PostgreSQL: records observations