# weaiw/trove-ai architecture

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

- Interactive diagram: https://gitdiagram.com/weaiw/trove-ai
- Repository: https://github.com/weaiw/trove-ai

## Overview

Trove AI is a self-hosted personal knowledge-management agent. Users capture web content or files into a private library, then read, search, connect, and reuse it through AI answers, research, concepts, and learning paths. The web app and WeChat/Feishu bot interfaces share that library; review digests and Obsidian export extend the workflow. The graph emphasizes documented product capabilities and sampled service behavior; some feature wiring is represented at subsystem level because its implementation was not sampled.

Main entry points: [`backend/app/main.py`](https://github.com/weaiw/trove-ai/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/database.py`](https://github.com/weaiw/trove-ai/blob/main/backend/app/database.py) (PostgreSQL library), [`frontend/src/app`](https://github.com/weaiw/trove-ai/tree/main/frontend/src/app) (Web app), [`backend/app/routers/articles.py`](https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/articles.py) (Article capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web app"]
  node_authui["Auth context<br/>[AuthContext.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_capture_ui["Capture and edit"]
  node_reader_ui["Reader and library<br/>[page.tsx]"]
  node_knowledge_ui["Knowledge views<br/>[page.tsx]"]
  node_review_ui["Review settings<br/>[ReviewSettings.tsx]"]
end

subgraph group_api["Application API"]
  node_app["FastAPI app<br/>[main.py]"]
  node_article_api["Article capture<br/>[articles.py]"]
  node_assistant_api["Assistant API<br/>[assistant.py]"]
  node_research_api["Research API<br/>[research.py]"]
  node_concept_api["Concept API<br/>[concepts.py]"]
  node_learning_api["Learning paths<br/>[learning.py]"]
  node_review_api["Review schedule<br/>[review.py]"]
  node_auth_api["Auth and users<br/>[auth.py]"]
end

subgraph group_knowledge["Knowledge services"]
  node_parser["Content extraction<br/>[parser_service.py]"]
  node_ai["AI processing<br/>[ai_service.py]"]
  node_retrieval["Search and RAG<br/>[graph_retrieval.py]"]
  node_graph["Knowledge graph<br/>[graph_service.py]"]
  node_concepts["Concept synthesis<br/>[concept_service.py]"]
  node_research["Research agent<br/>[research_agent.py]"]
  node_review["Digest generation<br/>[review_service.py]"]
end

subgraph group_integrations["Channels and integrations"]
  node_channels["Bot interfaces<br/>[wechat.py]"]
  node_mcp["MCP access<br/>[mcp.py]"]
  node_obsidian["Obsidian export<br/>[obsidian_writer.py]"]
  node_lark["Feishu integration<br/>[lark_service.py]"]
end

subgraph group_state["Identity and data"]
  node_db[("PostgreSQL library<br/>[database.py]")]
  node_models["Domain models"]
  node_config["Runtime configuration<br/>[config_manager.py]"]
end

node_user(("Reader"))
node_external_ai{{"LLM provider"}}
node_wechat_service{{"WeChat service"}}

node_user -->|"uses"| node_webapp
node_webapp -->|"captures content"| node_capture_ui
node_webapp -->|"reads articles"| node_reader_ui
node_webapp -->|"explores knowledge"| node_knowledge_ui
node_webapp -->|"sets reviews"| node_review_ui
node_authui -->|"authenticates"| node_auth_api
node_capture_ui -->|"submits content"| node_api_client
node_reader_ui -->|"requests articles"| node_api_client
node_knowledge_ui -->|"requests views"| node_api_client
node_review_ui -->|"manages schedule"| node_api_client
node_api_client -->|"calls API"| node_app
node_app -->|"dispatches"| node_article_api
node_app -->|"dispatches"| node_assistant_api
node_app -->|"dispatches"| node_research_api
node_app -->|"dispatches"| node_concept_api
node_app -->|"dispatches"| node_learning_api
node_app -->|"dispatches"| node_review_api
node_app -->|"dispatches"| node_auth_api
node_article_api -->|"extracts content"| node_parser
node_article_api -->|"analyzes content"| node_ai
node_article_api -->|"stores articles"| node_db
node_assistant_api -->|"retrieves context"| node_retrieval
node_assistant_api -->|"generates answers"| node_ai
node_research_api -->|"runs research"| node_research
node_research -->|"finds sources"| node_retrieval
node_concept_api -->|"synthesizes pages"| node_concepts
node_learning_api -->|"orders curriculum"| node_ai
node_review_api -->|"previews digest"| node_review
node_app -->|"starts scheduler"| node_review
node_review -->|"reads saved articles"| node_db
node_review -->|"requests digest"| node_external_ai
node_review -->|"pushes digest"| node_wechat_service
node_channels -->|"submits captures"| node_article_api
node_channels -->|"queries library"| node_assistant_api
node_mcp -->|"accesses library"| node_db
node_obsidian -->|"reads library"| node_db
node_lark -.->|"shares library"| node_db
node_retrieval -->|"searches articles"| node_db
node_graph -->|"reads relationships"| node_db
node_concepts -->|"reads sources"| node_db
node_ai -->|"calls model"| node_external_ai
node_models -->|"maps records"| node_db
node_config -->|"supplies settings"| node_ai

click node_webapp "https://github.com/weaiw/trove-ai/tree/main/frontend/src/app"
click node_authui "https://github.com/weaiw/trove-ai/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_api_client "https://github.com/weaiw/trove-ai/blob/main/frontend/src/lib/api.ts"
click node_capture_ui "https://github.com/weaiw/trove-ai/blob/main/frontend/src/components/AddContentModal.tsx"
click node_reader_ui "https://github.com/weaiw/trove-ai/blob/main/frontend/src/app/read/%5Bid%5D/page.tsx"
click node_knowledge_ui "https://github.com/weaiw/trove-ai/blob/main/frontend/src/app/graph/page.tsx"
click node_review_ui "https://github.com/weaiw/trove-ai/blob/main/frontend/src/components/ReviewSettings.tsx"
click node_app "https://github.com/weaiw/trove-ai/blob/main/backend/app/main.py"
click node_article_api "https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/articles.py"
click node_assistant_api "https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/assistant.py"
click node_research_api "https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/research.py"
click node_concept_api "https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/concepts.py"
click node_learning_api "https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/learning.py"
click node_review_api "https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/review.py"
click node_auth_api "https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/auth.py"
click node_parser "https://github.com/weaiw/trove-ai/blob/main/backend/app/services/parser_service.py"
click node_ai "https://github.com/weaiw/trove-ai/blob/main/backend/app/services/ai_service.py"
click node_retrieval "https://github.com/weaiw/trove-ai/blob/main/backend/app/services/graph_retrieval.py"
click node_graph "https://github.com/weaiw/trove-ai/blob/main/backend/app/services/graph_service.py"
click node_concepts "https://github.com/weaiw/trove-ai/blob/main/backend/app/services/concept_service.py"
click node_research "https://github.com/weaiw/trove-ai/blob/main/backend/app/services/research_agent.py"
click node_review "https://github.com/weaiw/trove-ai/blob/main/backend/app/services/review_service.py"
click node_channels "https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/wechat.py"
click node_mcp "https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/mcp.py"
click node_obsidian "https://github.com/weaiw/trove-ai/blob/main/backend/app/services/obsidian_writer.py"
click node_lark "https://github.com/weaiw/trove-ai/blob/main/backend/app/services/lark_service.py"
click node_db "https://github.com/weaiw/trove-ai/blob/main/backend/app/database.py"
click node_models "https://github.com/weaiw/trove-ai/tree/main/backend/app/models"
click node_config "https://github.com/weaiw/trove-ai/blob/main/backend/app/config_manager.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_authui,node_api_client,node_capture_ui,node_reader_ui,node_knowledge_ui,node_review_ui toneBlue
class node_app,node_article_api,node_assistant_api,node_research_api,node_concept_api,node_learning_api,node_review_api,node_auth_api toneAmber
class node_parser,node_ai,node_retrieval,node_graph,node_concepts,node_research,node_review toneMint
class node_channels,node_mcp,node_obsidian,node_lark toneRose
class node_db,node_models,node_config,node_user,node_external_ai,node_wechat_service toneIndigo
```

## Components

### Web experience

- [Web app](https://github.com/weaiw/trove-ai/tree/main/frontend/src/app): `frontend/src/app`
- [Auth context](https://github.com/weaiw/trove-ai/blob/main/frontend/src/contexts/AuthContext.tsx): `frontend/src/contexts/AuthContext.tsx`
- [API client](https://github.com/weaiw/trove-ai/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Capture and edit](https://github.com/weaiw/trove-ai/blob/main/frontend/src/components/AddContentModal.tsx): `frontend/src/components/AddContentModal.tsx`
- [Reader and library](https://github.com/weaiw/trove-ai/blob/main/frontend/src/app/read/%5Bid%5D/page.tsx): `frontend/src/app/read/[id]/page.tsx`
- [Knowledge views](https://github.com/weaiw/trove-ai/blob/main/frontend/src/app/graph/page.tsx): `frontend/src/app/graph/page.tsx`
- [Review settings](https://github.com/weaiw/trove-ai/blob/main/frontend/src/components/ReviewSettings.tsx): `frontend/src/components/ReviewSettings.tsx`

### Application API

- [FastAPI app](https://github.com/weaiw/trove-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Article capture](https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/articles.py): `backend/app/routers/articles.py`
- [Assistant API](https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/assistant.py): `backend/app/routers/assistant.py`
- [Research API](https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/research.py): `backend/app/routers/research.py`
- [Concept API](https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/concepts.py): `backend/app/routers/concepts.py`
- [Learning paths](https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/learning.py): `backend/app/routers/learning.py`
- [Review schedule](https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/review.py): `backend/app/routers/review.py`
- [Auth and users](https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`

### Knowledge services

- [Content extraction](https://github.com/weaiw/trove-ai/blob/main/backend/app/services/parser_service.py): `backend/app/services/parser_service.py`
- [AI processing](https://github.com/weaiw/trove-ai/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [Search and RAG](https://github.com/weaiw/trove-ai/blob/main/backend/app/services/graph_retrieval.py): `backend/app/services/graph_retrieval.py`
- [Knowledge graph](https://github.com/weaiw/trove-ai/blob/main/backend/app/services/graph_service.py): `backend/app/services/graph_service.py`
- [Concept synthesis](https://github.com/weaiw/trove-ai/blob/main/backend/app/services/concept_service.py): `backend/app/services/concept_service.py`
- [Research agent](https://github.com/weaiw/trove-ai/blob/main/backend/app/services/research_agent.py): `backend/app/services/research_agent.py`
- [Digest generation](https://github.com/weaiw/trove-ai/blob/main/backend/app/services/review_service.py): `backend/app/services/review_service.py`

### Channels and integrations

- [Bot interfaces](https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/wechat.py): `backend/app/routers/wechat.py`
- [MCP access](https://github.com/weaiw/trove-ai/blob/main/backend/app/routers/mcp.py): `backend/app/routers/mcp.py`
- [Obsidian export](https://github.com/weaiw/trove-ai/blob/main/backend/app/services/obsidian_writer.py): `backend/app/services/obsidian_writer.py`
- [Feishu integration](https://github.com/weaiw/trove-ai/blob/main/backend/app/services/lark_service.py): `backend/app/services/lark_service.py`

### Identity and data

- [PostgreSQL library](https://github.com/weaiw/trove-ai/blob/main/backend/app/database.py): `backend/app/database.py`
- [Domain models](https://github.com/weaiw/trove-ai/tree/main/backend/app/models): `backend/app/models`
- [Runtime configuration](https://github.com/weaiw/trove-ai/blob/main/backend/app/config_manager.py): `backend/app/config_manager.py`

### Other components

- **Reader**
- **LLM provider**
- **WeChat service**

## Connections

- Reader → Web app: uses
- Web app → Capture and edit: captures content
- Web app → Reader and library: reads articles
- Web app → Knowledge views: explores knowledge
- Web app → Review settings: sets reviews
- Auth context → Auth and users: authenticates
- Capture and edit → API client: submits content
- Reader and library → API client: requests articles
- Knowledge views → API client: requests views
- Review settings → API client: manages schedule
- API client → FastAPI app: calls API
- FastAPI app → Article capture: dispatches
- FastAPI app → Assistant API: dispatches
- FastAPI app → Research API: dispatches
- FastAPI app → Concept API: dispatches
- FastAPI app → Learning paths: dispatches
- FastAPI app → Review schedule: dispatches
- FastAPI app → Auth and users: dispatches
- Article capture → Content extraction: extracts content
- Article capture → AI processing: analyzes content
- Article capture → PostgreSQL library: stores articles
- Assistant API → Search and RAG: retrieves context
- Assistant API → AI processing: generates answers
- Research API → Research agent: runs research
- Research agent → Search and RAG: finds sources
- Concept API → Concept synthesis: synthesizes pages
- Learning paths → AI processing: orders curriculum
- Review schedule → Digest generation: previews digest
- FastAPI app → Digest generation: starts scheduler
- Digest generation → PostgreSQL library: reads saved articles
- Digest generation → LLM provider: requests digest
- Digest generation → WeChat service: pushes digest
- Bot interfaces → Article capture: submits captures
- Bot interfaces → Assistant API: queries library
- MCP access → PostgreSQL library: accesses library
- Obsidian export → PostgreSQL library: reads library
- Feishu integration → PostgreSQL library: shares library
- Search and RAG → PostgreSQL library: searches articles
- Knowledge graph → PostgreSQL library: reads relationships
- Concept synthesis → PostgreSQL library: reads sources
- AI processing → LLM provider: calls model
- Domain models → PostgreSQL library: maps records
- Runtime configuration → AI processing: supplies settings