# minjun069/news-tls-agent architecture

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

- Interactive diagram: https://gitdiagram.com/minjun069/news-tls-agent
- Repository: https://github.com/minjun069/news-tls-agent

## Overview

NewsTrace organizes archived news into evidence-backed issue timelines, then supports browsing, chat, article graphs, and PDF/Notion export. The main workflow runs from Vue issue-generation requests through FastAPI and its stdio MCP client to the timeline pipeline, which searches and validates candidate articles before storing an issue; users can then retrieve and explore that result. The README documents MCP as the data-access boundary, with MS-SQL for article and issue records and Qdrant for search. Route and tool wiring is only partly sampled, so uncertain internal calls are omitted.

Main entry points: [`backend/api/routes`](https://github.com/minjun069/news-tls-agent/tree/main/backend/api/routes) (API routes), [`backend/infra/repository.py`](https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/repository.py) (SQL repository), [`backend/mcp_server/tools`](https://github.com/minjun069/news-tls-agent/tree/main/backend/mcp_server/tools) (MCP tools), [`backend/app/exporting.py`](https://github.com/minjun069/news-tls-agent/blob/main/backend/app/exporting.py) (Briefing export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Vue application<br/>[App.vue]"]
  node_client["API client<br/>[client.ts]"]
end

subgraph group_api["API and MCP"]
  node_apiapp["FastAPI app<br/>[main.py]"]
  node_routes["API routes"]
  node_mcpclient["MCP tool client<br/>[mcp_client.py]"]
  node_mcpserver["MCP server<br/>[server.py]"]
  node_tools["MCP tools"]
end

subgraph group_domain["Timeline and discovery"]
  node_pipeline["Timeline pipeline<br/>[pipeline.py]"]
  node_search["Article search<br/>[search.py]"]
  node_agent["Chat agent<br/>[agent.py]"]
  node_graph["Article graph<br/>[graph.py]"]
  node_export["Briefing export<br/>[exporting.py]"]
end

subgraph group_storage["Persistence and integrations"]
  node_repository["SQL repository<br/>[repository.py]"]
  node_sql[("MS-SQL<br/>[db.py]")]
  node_vectors[("Qdrant vectors<br/>[qdrant.py]")]
  node_embedding["Embedding provider<br/>[embedding.py]"]
  node_gemini["Gemini service<br/>[gemini.py]"]
  node_pdf["PDF renderer<br/>[pdf.py]"]
  node_notion["Notion publisher<br/>[notion.py]"]
end

node_reader(("News reader"))
node_browser(("Web browser"))

node_reader -->|"uses"| node_webapp
node_webapp -->|"requests"| node_client
node_client -->|"REST / SSE"| node_apiapp
node_apiapp -->|"dispatches"| node_routes
node_routes -->|"generates timeline"| node_pipeline
node_routes -->|"calls tools"| node_mcpclient
node_mcpclient -->|"stdio MCP"| node_mcpserver
node_mcpserver -->|"registers"| node_tools
node_tools -->|"searches"| node_search
node_tools -->|"reads / writes"| node_repository
node_tools -->|"exports"| node_export
node_pipeline -->|"finds candidates"| node_search
node_pipeline -->|"loads / saves"| node_repository
node_search -->|"embeds query"| node_embedding
node_search -->|"searches vectors"| node_vectors
node_embedding -.->|"embeds remotely"| node_gemini
node_repository -->|"reads / writes"| node_sql
node_export -->|"loads issue"| node_repository
node_export -->|"renders PDF"| node_pdf
node_export -.->|"publishes"| node_notion
node_routes -->|"streams chat"| node_agent
node_routes -->|"builds graph"| node_graph
node_agent -->|"uses tools"| node_mcpclient
node_graph -->|"reads graph data"| node_repository
node_routes -->|"reads issues / articles"| node_repository
node_apiapp -->|"serves downloads"| node_browser

click node_webapp "https://github.com/minjun069/news-tls-agent/blob/main/web/src/App.vue"
click node_client "https://github.com/minjun069/news-tls-agent/blob/main/web/src/api/client.ts"
click node_apiapp "https://github.com/minjun069/news-tls-agent/blob/main/backend/api/main.py"
click node_routes "https://github.com/minjun069/news-tls-agent/tree/main/backend/api/routes"
click node_mcpclient "https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/mcp_client.py"
click node_mcpserver "https://github.com/minjun069/news-tls-agent/blob/main/backend/mcp_server/server.py"
click node_tools "https://github.com/minjun069/news-tls-agent/tree/main/backend/mcp_server/tools"
click node_pipeline "https://github.com/minjun069/news-tls-agent/blob/main/backend/app/pipeline.py"
click node_search "https://github.com/minjun069/news-tls-agent/blob/main/backend/app/search.py"
click node_agent "https://github.com/minjun069/news-tls-agent/blob/main/backend/app/agent.py"
click node_graph "https://github.com/minjun069/news-tls-agent/blob/main/backend/app/graph.py"
click node_export "https://github.com/minjun069/news-tls-agent/blob/main/backend/app/exporting.py"
click node_repository "https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/repository.py"
click node_sql "https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/db.py"
click node_vectors "https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/qdrant.py"
click node_embedding "https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/embedding.py"
click node_gemini "https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/gemini.py"
click node_pdf "https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/pdf.py"
click node_notion "https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/notion.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_webapp,node_client,node_browser toneBlue
class node_apiapp,node_routes,node_mcpclient,node_mcpserver,node_tools toneAmber
class node_pipeline,node_search,node_agent,node_graph,node_export toneMint
class node_repository,node_sql,node_vectors,node_embedding,node_gemini,node_pdf,node_notion toneRose
class node_reader toneIndigo
```

## Components

### Web experience

- [Vue application](https://github.com/minjun069/news-tls-agent/blob/main/web/src/App.vue): `web/src/App.vue`
- [API client](https://github.com/minjun069/news-tls-agent/blob/main/web/src/api/client.ts): `web/src/api/client.ts`

### API and MCP

- [FastAPI app](https://github.com/minjun069/news-tls-agent/blob/main/backend/api/main.py): `backend/api/main.py`
- [API routes](https://github.com/minjun069/news-tls-agent/tree/main/backend/api/routes): `backend/api/routes`
- [MCP tool client](https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/mcp_client.py): `backend/infra/mcp_client.py`
- [MCP server](https://github.com/minjun069/news-tls-agent/blob/main/backend/mcp_server/server.py): `backend/mcp_server/server.py`
- [MCP tools](https://github.com/minjun069/news-tls-agent/tree/main/backend/mcp_server/tools): `backend/mcp_server/tools`

### Timeline and discovery

- [Timeline pipeline](https://github.com/minjun069/news-tls-agent/blob/main/backend/app/pipeline.py): `backend/app/pipeline.py`
- [Article search](https://github.com/minjun069/news-tls-agent/blob/main/backend/app/search.py): `backend/app/search.py`
- [Chat agent](https://github.com/minjun069/news-tls-agent/blob/main/backend/app/agent.py): `backend/app/agent.py`
- [Article graph](https://github.com/minjun069/news-tls-agent/blob/main/backend/app/graph.py): `backend/app/graph.py`
- [Briefing export](https://github.com/minjun069/news-tls-agent/blob/main/backend/app/exporting.py): `backend/app/exporting.py`

### Persistence and integrations

- [SQL repository](https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/repository.py): `backend/infra/repository.py`
- [MS-SQL](https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/db.py): `backend/infra/db.py`
- [Qdrant vectors](https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/qdrant.py): `backend/infra/qdrant.py`
- [Embedding provider](https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/embedding.py): `backend/infra/embedding.py`
- [Gemini service](https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/gemini.py): `backend/infra/gemini.py`
- [PDF renderer](https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/pdf.py): `backend/infra/pdf.py`
- [Notion publisher](https://github.com/minjun069/news-tls-agent/blob/main/backend/infra/notion.py): `backend/infra/notion.py`

### Other components

- **News reader**
- **Web browser**

## Connections

- News reader → Vue application: uses
- Vue application → API client: requests
- API client → FastAPI app: REST / SSE
- FastAPI app → API routes: dispatches
- API routes → Timeline pipeline: generates timeline
- API routes → MCP tool client: calls tools
- MCP tool client → MCP server: stdio MCP
- MCP server → MCP tools: registers
- MCP tools → Article search: searches
- MCP tools → SQL repository: reads / writes
- MCP tools → Briefing export: exports
- Timeline pipeline → Article search: finds candidates
- Timeline pipeline → SQL repository: loads / saves
- Article search → Embedding provider: embeds query
- Article search → Qdrant vectors: searches vectors
- Embedding provider → Gemini service: embeds remotely
- SQL repository → MS-SQL: reads / writes
- Briefing export → SQL repository: loads issue
- Briefing export → PDF renderer: renders PDF
- Briefing export → Notion publisher: publishes
- API routes → Chat agent: streams chat
- API routes → Article graph: builds graph
- Chat agent → MCP tool client: uses tools
- Article graph → SQL repository: reads graph data
- API routes → SQL repository: reads issues / articles
- FastAPI app → Web browser: serves downloads