# letuandatt/ai-radar architecture

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

- Interactive diagram: https://gitdiagram.com/letuandatt/ai-radar
- Repository: https://github.com/letuandatt/ai-radar

## Overview

AI-Radar collects AI research and news, turns it into validated knowledge, and serves it through a persistent knowledge base, retrieval, and daily intelligence. The graph also includes the documented web reading experience and Zalo delivery. Several pipeline, digest, and intelligence implementations are unsampled, so those documented capabilities are shown at subsystem level; edges are limited to relationships visible in excerpts, the source index, or README.

Main entry points: [`app/api/v1/routes.py`](https://github.com/letuandatt/ai-radar/blob/main/app/api/v1/routes.py) (Versioned API), [`app/core/application.py`](https://github.com/letuandatt/ai-radar/blob/main/app/core/application.py) (Lifecycle orchestration), [`app/services/retrieval/retrieval_service.py`](https://github.com/letuandatt/ai-radar/blob/main/app/services/retrieval/retrieval_service.py) (Retrieval service), [`web/src/App.tsx`](https://github.com/letuandatt/ai-radar/blob/main/web/src/App.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_main["Application entry<br/>[main.py]"]
  node_lifecycle["Lifecycle orchestration<br/>[application.py]"]
  node_api["Versioned API<br/>[routes.py]"]
end

subgraph group_ingest["Knowledge ingestion"]
  node_fetch["Source fetchers"]
  node_acquisition["Acquisition pipeline<br/>[acquisition.py]"]
  node_processing["Processing pipeline<br/>[processing.py]"]
  node_manual["Manual URL add"]
end

subgraph group_knowledge["Knowledge and retrieval"]
  node_knowledgeobj["Knowledge object"]
  node_appservice["Repository facade<br/>[app_service.py]"]
  node_sqlite[("Knowledge repository<br/>[sqlite_store.py]")]
  node_sync["Vector synchronization<br/>[sync_service.py]"]
  node_qdrant[("Qdrant vectors<br/>[qdrant_store.py]")]
  node_retrieval["Retrieval service"]
  node_bm25[("Keyword index<br/>[bm25_index.py]")]
end

subgraph group_intelligence["Intelligence and delivery"]
  node_digest["Daily digest<br/>[daily_digest.py]"]
  node_analysis["Analysis services"]
  node_zalo["Zalo delivery"]
end

subgraph group_web["Web experience"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_hooks["Web data hooks"]
  node_generated["Generated API client<br/>[generated.ts]"]
end

node_user(("Reader"))

node_user -->|"browses"| node_webapp
node_webapp -->|"uses views"| node_hooks
node_hooks -->|"calls client"| node_generated
node_webapp -.->|"reads stored content"| node_api
node_main -->|"starts"| node_lifecycle
node_lifecycle -->|"schedules"| node_acquisition
node_lifecycle -->|"forwards articles"| node_processing
node_fetch -.->|"provides sources"| node_acquisition
node_acquisition -.->|"supplies articles"| node_processing
node_user -.->|"submits URL"| node_api
node_api -->|"adds knowledge"| node_manual
node_processing -.->|"produces knowledge"| node_knowledgeobj
node_manual -->|"builds object"| node_knowledgeobj
node_appservice -->|"persists records"| node_sqlite
node_appservice -->|"synchronizes vectors"| node_sync
node_sync -->|"upserts vectors"| node_qdrant
node_api -->|"dispatches search"| node_retrieval
node_retrieval -->|"searches keywords"| node_bm25
node_retrieval -.->|"searches vectors"| node_qdrant
node_api -.->|"browses records"| node_sqlite
node_sqlite -.->|"provides knowledge"| node_digest
node_digest -.->|"delivers digest"| node_zalo
node_analysis -.->|"informs intelligence"| node_digest

click node_main "https://github.com/letuandatt/ai-radar/blob/main/app/main.py"
click node_lifecycle "https://github.com/letuandatt/ai-radar/blob/main/app/core/application.py"
click node_api "https://github.com/letuandatt/ai-radar/blob/main/app/api/v1/routes.py"
click node_fetch "https://github.com/letuandatt/ai-radar/tree/main/app/fetchers"
click node_acquisition "https://github.com/letuandatt/ai-radar/blob/main/app/pipelines/acquisition.py"
click node_processing "https://github.com/letuandatt/ai-radar/blob/main/app/pipelines/processing.py"
click node_manual "https://github.com/letuandatt/ai-radar/blob/main/app/services/knowledge/manual_add_service.py"
click node_knowledgeobj "https://github.com/letuandatt/ai-radar/blob/main/app/models/knowledge_object.py"
click node_appservice "https://github.com/letuandatt/ai-radar/blob/main/app/services/app_service.py"
click node_sqlite "https://github.com/letuandatt/ai-radar/blob/main/app/storage/knowledge/sqlite_store.py"
click node_sync "https://github.com/letuandatt/ai-radar/blob/main/app/services/vector/sync_service.py"
click node_qdrant "https://github.com/letuandatt/ai-radar/blob/main/app/storage/vector/qdrant_store.py"
click node_retrieval "https://github.com/letuandatt/ai-radar/blob/main/app/services/retrieval/retrieval_service.py"
click node_bm25 "https://github.com/letuandatt/ai-radar/blob/main/app/storage/search/bm25_index.py"
click node_digest "https://github.com/letuandatt/ai-radar/blob/main/app/pipelines/daily_digest.py"
click node_analysis "https://github.com/letuandatt/ai-radar/tree/main/app/services/analysis"
click node_zalo "https://github.com/letuandatt/ai-radar/tree/main/app/integrations/zalo"
click node_webapp "https://github.com/letuandatt/ai-radar/blob/main/web/src/App.tsx"
click node_hooks "https://github.com/letuandatt/ai-radar/tree/main/web/src/hooks"
click node_generated "https://github.com/letuandatt/ai-radar/blob/main/web/src/api/generated.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_main,node_lifecycle,node_api toneBlue
class node_fetch,node_acquisition,node_processing,node_manual toneAmber
class node_knowledgeobj,node_appservice,node_sqlite,node_sync,node_qdrant,node_retrieval,node_bm25 toneMint
class node_digest,node_analysis,node_zalo toneRose
class node_webapp,node_hooks,node_generated,node_user toneIndigo
```

## Components

### Application runtime

- [Application entry](https://github.com/letuandatt/ai-radar/blob/main/app/main.py): `app/main.py`
- [Lifecycle orchestration](https://github.com/letuandatt/ai-radar/blob/main/app/core/application.py): `app/core/application.py`
- [Versioned API](https://github.com/letuandatt/ai-radar/blob/main/app/api/v1/routes.py): `app/api/v1/routes.py`

### Knowledge ingestion

- [Source fetchers](https://github.com/letuandatt/ai-radar/tree/main/app/fetchers): `app/fetchers`
- [Acquisition pipeline](https://github.com/letuandatt/ai-radar/blob/main/app/pipelines/acquisition.py): `app/pipelines/acquisition.py`
- [Processing pipeline](https://github.com/letuandatt/ai-radar/blob/main/app/pipelines/processing.py): `app/pipelines/processing.py`
- [Manual URL add](https://github.com/letuandatt/ai-radar/blob/main/app/services/knowledge/manual_add_service.py): `app/services/knowledge/manual_add_service.py`

### Knowledge and retrieval

- [Knowledge object](https://github.com/letuandatt/ai-radar/blob/main/app/models/knowledge_object.py): `app/models/knowledge_object.py`
- [Repository facade](https://github.com/letuandatt/ai-radar/blob/main/app/services/app_service.py): `app/services/app_service.py`
- [Knowledge repository](https://github.com/letuandatt/ai-radar/blob/main/app/storage/knowledge/sqlite_store.py): `app/storage/knowledge/sqlite_store.py`
- [Vector synchronization](https://github.com/letuandatt/ai-radar/blob/main/app/services/vector/sync_service.py): `app/services/vector/sync_service.py`
- [Qdrant vectors](https://github.com/letuandatt/ai-radar/blob/main/app/storage/vector/qdrant_store.py): `app/storage/vector/qdrant_store.py`
- [Retrieval service](https://github.com/letuandatt/ai-radar/blob/main/app/services/retrieval/retrieval_service.py): `app/services/retrieval/retrieval_service.py`
- [Keyword index](https://github.com/letuandatt/ai-radar/blob/main/app/storage/search/bm25_index.py): `app/storage/search/bm25_index.py`

### Intelligence and delivery

- [Daily digest](https://github.com/letuandatt/ai-radar/blob/main/app/pipelines/daily_digest.py): `app/pipelines/daily_digest.py`
- [Analysis services](https://github.com/letuandatt/ai-radar/tree/main/app/services/analysis): `app/services/analysis`
- [Zalo delivery](https://github.com/letuandatt/ai-radar/tree/main/app/integrations/zalo): `app/integrations/zalo`

### Web experience

- [Web application](https://github.com/letuandatt/ai-radar/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Web data hooks](https://github.com/letuandatt/ai-radar/tree/main/web/src/hooks): `web/src/hooks`
- [Generated API client](https://github.com/letuandatt/ai-radar/blob/main/web/src/api/generated.ts): `web/src/api/generated.ts`

### Other components

- **Reader**

## Connections

- Reader → Web application: browses
- Web application → Web data hooks: uses views (evidence: `web/src/App.tsx`)
- Web data hooks → Generated API client: calls client (evidence: `web/src/hooks/useKnowledge.ts`)
- Web application → Versioned API: reads stored content
- Application entry → Lifecycle orchestration: starts (evidence: `app/main.py`)
- Lifecycle orchestration → Acquisition pipeline: schedules (evidence: `app/core/application.py`)
- Lifecycle orchestration → Processing pipeline: forwards articles (evidence: `app/core/application.py`)
- Source fetchers → Acquisition pipeline: provides sources
- Acquisition pipeline → Processing pipeline: supplies articles
- Reader → Versioned API: submits URL
- Versioned API → Manual URL add: adds knowledge
- Processing pipeline → Knowledge object: produces knowledge
- Manual URL add → Knowledge object: builds object (evidence: `app/services/knowledge/manual_add_service.py`)
- Repository facade → Knowledge repository: persists records (evidence: `app/services/app_service.py`)
- Repository facade → Vector synchronization: synchronizes vectors (evidence: `app/services/app_service.py`)
- Vector synchronization → Qdrant vectors: upserts vectors (evidence: `app/services/vector/sync_service.py`)
- Versioned API → Retrieval service: dispatches search (evidence: `app/api/v1/routes.py`)
- Retrieval service → Keyword index: searches keywords (evidence: `app/services/retrieval/retrieval_service.py`)
- Retrieval service → Qdrant vectors: searches vectors
- Versioned API → Knowledge repository: browses records
- Knowledge repository → Daily digest: provides knowledge
- Daily digest → Zalo delivery: delivers digest
- Analysis services → Daily digest: informs intelligence
