# edwardaiyw/literature-agent architecture

> Architecture diagram of the GitHub repository edwardaiyw/literature-agent, 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/edwardaiyw/literature-agent
- Repository: https://github.com/edwardaiyw/literature-agent

## Overview

Literature Agent is a local-first literature discovery and daily email assistant. The main workflow is: configure sources and a model, submit a research task, plan queries, retrieve and deduplicate papers, screen and summarize them, optionally review evidence, then save results for the user. Subscriptions schedule that workflow and deliver digests. The graph preserves README-documented capabilities such as source diagnostics, paper labels, backups, prompt management, and Jev decisions. Some links are omitted or marked unverified because excerpts do not show all API routing and runtime wiring.

Main entry points: [`backend/src/literature_agent/graph.py`](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/graph.py) (Query planning), [`backend/src/literature_agent/db.py`](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/db.py) (Local research store), [`backend/src/literature_agent/api.py`](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/api.py) (HTTP API), [`backend/src/literature_agent/runner.py`](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/runner.py) (Run orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_webapp["Web workspace<br/>[App.tsx]"]
  node_api["HTTP API<br/>[api.py]"]
  node_schemas["Request schemas<br/>[schemas.py]"]
end

subgraph group_workflow["Research workflow"]
  node_runner["Run orchestrator<br/>[runner.py]"]
  node_worker["Local worker<br/>[worker.py]"]
  node_planner["Query planning<br/>[graph.py]"]
  node_retrieval["Source retrieval<br/>[sources.py]"]
  node_dedup["Deduplication<br/>[graph.py]"]
  node_screening["Relevance screening<br/>[graph.py]"]
  node_summaries["Paper summaries<br/>[graph.py]"]
  node_evidence["Evidence review<br/>[graph.py]"]
  node_decisions["Jev decisions<br/>[decisions.py]"]
  node_prompts["Prompt library<br/>[prompts.py]"]
end

subgraph group_operations["Local operations"]
  node_database[("Local research store<br/>[db.py]")]
  node_config["Settings and secrets<br/>[config.py]"]
  node_daily["Daily scheduler<br/>[daily.py]"]
  node_launcher["Local service launcher<br/>[launcher.py]"]
  node_email["Digest delivery<br/>[email.py]"]
end

subgraph group_integrations["External services"]
  node_academic["Academic sources"]
  node_model["Model provider"]
  node_jevservice["LocalJev service"]
  node_smtp["SMTP service"]
end

node_user(("Researcher"))

node_user -->|"uses"| node_webapp
node_webapp -.->|"requests"| node_api
node_api -->|"validates"| node_schemas
node_api -->|"reads and writes"| node_database
node_api -->|"submits runs"| node_worker
node_worker -->|"dispatches"| node_runner
node_runner -->|"loads and saves"| node_database
node_runner -->|"invokes graph"| node_planner
node_planner -->|"searches"| node_retrieval
node_retrieval -->|"queries"| node_academic
node_planner -->|"canonicalizes"| node_dedup
node_planner -->|"screens"| node_screening
node_planner -->|"summarizes"| node_summaries
node_planner -->|"reviews optionally"| node_evidence
node_planner -->|"requests decisions"| node_model
node_planner -->|"consults"| node_decisions
node_decisions -.->|"calls optionally"| node_jevservice
node_planner -->|"uses prompts"| node_prompts
node_planner -->|"stores results"| node_database
node_runner -->|"renders digest"| node_email
node_email -->|"sends message"| node_smtp
node_email -->|"records delivery"| node_database
node_daily -->|"runs subscriptions"| node_runner
node_daily -->|"checks subscriptions"| node_database
node_launcher -->|"starts scheduler"| node_daily
node_api -->|"updates settings"| node_config
node_user -->|"configures subscriptions"| node_daily
node_user -->|"manages backups and labels"| node_database

click node_webapp "https://github.com/edwardaiyw/literature-agent/blob/main/frontend/src/App.tsx"
click node_api "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/api.py"
click node_schemas "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/schemas.py"
click node_runner "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/runner.py"
click node_worker "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/worker.py"
click node_planner "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/graph.py"
click node_retrieval "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/sources.py"
click node_dedup "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/graph.py"
click node_screening "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/graph.py"
click node_summaries "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/graph.py"
click node_evidence "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/graph.py"
click node_decisions "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/decisions.py"
click node_prompts "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/prompts.py"
click node_database "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/db.py"
click node_config "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/config.py"
click node_daily "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/daily.py"
click node_launcher "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/launcher.py"
click node_email "https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/email.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_api,node_schemas toneBlue
class node_runner,node_worker,node_planner,node_retrieval,node_dedup,node_screening,node_summaries,node_evidence,node_decisions,node_prompts toneAmber
class node_database,node_config,node_daily,node_launcher,node_email toneMint
class node_academic,node_model,node_jevservice,node_smtp toneRose
class node_user toneIndigo
```

## Components

### User interface

- [Web workspace](https://github.com/edwardaiyw/literature-agent/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [HTTP API](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/api.py): `backend/src/literature_agent/api.py`
- [Request schemas](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/schemas.py): `backend/src/literature_agent/schemas.py`

### Research workflow

- [Run orchestrator](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/runner.py): `backend/src/literature_agent/runner.py`
- [Local worker](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/worker.py): `backend/src/literature_agent/worker.py`
- [Query planning](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/graph.py): `backend/src/literature_agent/graph.py`
- [Source retrieval](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/sources.py): `backend/src/literature_agent/sources.py`
- [Deduplication](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/graph.py): `backend/src/literature_agent/graph.py`
- [Relevance screening](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/graph.py): `backend/src/literature_agent/graph.py`
- [Paper summaries](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/graph.py): `backend/src/literature_agent/graph.py`
- [Evidence review](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/graph.py): `backend/src/literature_agent/graph.py`
- [Jev decisions](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/decisions.py): `backend/src/literature_agent/decisions.py`
- [Prompt library](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/prompts.py): `backend/src/literature_agent/prompts.py`

### Local operations

- [Local research store](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/db.py): `backend/src/literature_agent/db.py`
- [Settings and secrets](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/config.py): `backend/src/literature_agent/config.py`
- [Daily scheduler](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/daily.py): `backend/src/literature_agent/daily.py`
- [Local service launcher](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/launcher.py): `backend/src/literature_agent/launcher.py`
- [Digest delivery](https://github.com/edwardaiyw/literature-agent/blob/main/backend/src/literature_agent/email.py): `backend/src/literature_agent/email.py`

### External services

- **Academic sources**
- **Model provider**
- **LocalJev service**
- **SMTP service**

### Other components

- **Researcher**

## Connections

- Researcher → Web workspace: uses (evidence: `README.md`)
- Web workspace → HTTP API: requests
- HTTP API → Request schemas: validates (evidence: `backend/src/literature_agent/api.py`)
- HTTP API → Local research store: reads and writes (evidence: `backend/src/literature_agent/api.py`)
- HTTP API → Local worker: submits runs (evidence: `backend/src/literature_agent/api.py`)
- Local worker → Run orchestrator: dispatches (evidence: `backend/src/literature_agent/worker.py`)
- Run orchestrator → Local research store: loads and saves (evidence: `backend/src/literature_agent/runner.py`)
- Run orchestrator → Query planning: invokes graph (evidence: `backend/src/literature_agent/runner.py`)
- Query planning → Source retrieval: searches (evidence: `backend/src/literature_agent/graph.py`)
- Source retrieval → Academic sources: queries (evidence: `README.md`)
- Query planning → Deduplication: canonicalizes (evidence: `backend/src/literature_agent/graph.py`)
- Query planning → Relevance screening: screens (evidence: `backend/src/literature_agent/graph.py`)
- Query planning → Paper summaries: summarizes (evidence: `backend/src/literature_agent/graph.py`)
- Query planning → Evidence review: reviews optionally (evidence: `README.md`)
- Query planning → Model provider: requests decisions (evidence: `README.md`)
- Query planning → Jev decisions: consults (evidence: `backend/src/literature_agent/graph.py`)
- Jev decisions → LocalJev service: calls optionally (evidence: `README.md`)
- Query planning → Prompt library: uses prompts (evidence: `backend/src/literature_agent/graph.py`)
- Query planning → Local research store: stores results (evidence: `backend/src/literature_agent/graph.py`)
- Run orchestrator → Digest delivery: renders digest (evidence: `backend/src/literature_agent/runner.py`)
- Digest delivery → SMTP service: sends message (evidence: `backend/src/literature_agent/email.py`)
- Digest delivery → Local research store: records delivery (evidence: `backend/src/literature_agent/runner.py`)
- Daily scheduler → Run orchestrator: runs subscriptions (evidence: `backend/src/literature_agent/daily.py`)
- Daily scheduler → Local research store: checks subscriptions (evidence: `backend/src/literature_agent/daily.py`)
- Local service launcher → Daily scheduler: starts scheduler (evidence: `backend/src/literature_agent/launcher.py`)
- HTTP API → Settings and secrets: updates settings (evidence: `backend/src/literature_agent/api.py`)
- Researcher → Daily scheduler: configures subscriptions (evidence: `README.md`)
- Researcher → Local research store: manages backups and labels (evidence: `README.md`)