# zzz395/researchweave architecture

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

- Interactive diagram: https://gitdiagram.com/zzz395/researchweave
- Repository: https://github.com/zzz395/researchweave

## Overview

ResearchWeave is a collaborative research workspace. Users authenticate, work in authorized Research Spaces, discover and save arXiv papers, ingest documents for cited Knowledge answers, and optionally run bounded research agents; collaboration includes chat and realtime updates. The graph preserves those distinct workflows and major comparison, summary, membership, and activity features. README documents the system boundaries; some backend wiring is represented at domain level because its service and application source was not sampled.

Main entry points: [`server/app.ts`](https://github.com/zzz395/researchweave/blob/main/server/app.ts) (Express application), [`src/app/router.tsx`](https://github.com/zzz395/researchweave/blob/main/src/app/router.tsx) (React application), [`src/services/api/client.ts`](https://github.com/zzz395/researchweave/blob/main/src/services/api/client.ts) (API client), [`server/db/schema.ts`](https://github.com/zzz395/researchweave/blob/main/server/db/schema.ts) (PostgreSQL + pgvector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web workspace"]
  node_web["React application<br/>[router.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_auth_ui["Authentication UI<br/>[login-page.tsx]"]
  node_spaces_ui["Spaces UI<br/>[spaces-page.tsx]"]
  node_research_ui["Research UI<br/>[research-page.tsx]"]
  node_knowledge_ui["Knowledge UI<br/>[knowledge-page.tsx]"]
  node_agents_ui["Agent UI<br/>[agents-page.tsx]"]
  node_chat_ui["Space chat UI"]
  node_realtime_client["Realtime client"]
end

subgraph group_backend["Application API"]
  node_server["Express application<br/>[app.ts]"]
  node_auth["Authentication<br/>[routes.ts]"]
  node_spaces["Spaces and members<br/>[routes.ts]"]
  node_connections["Connections<br/>[routes.ts]"]
  node_activity["Activity and overview<br/>[routes.ts]"]
  node_chat["Chat API<br/>[routes.ts]"]
  node_gateway["Realtime gateway<br/>[gateway.ts]"]
end

subgraph group_knowledge["Knowledge workflows"]
  node_documents["Document ingestion<br/>[routes.ts]"]
  node_indexing["Indexing pipeline"]
  node_retrieval["Knowledge retrieval<br/>[routes.ts]"]
  node_grounded["Grounded answers<br/>[routes.ts]"]
  node_agent["Bounded Agent runtime<br/>[runtime.ts]"]
  node_agent_worker["Durable Agent worker<br/>[worker.ts]"]
end

subgraph group_research["Research workflows"]
  node_research["Research discovery<br/>[routes.ts]"]
  node_comparison["Paper comparison<br/>[routes.ts]"]
  node_summary["Paper summaries"]
end

subgraph group_runtime["Persistence and integrations"]
  node_arxiv["arXiv service<br/>[client.ts]"]
  node_model["Model providers"]
  node_embedding["Embedding provider"]
  node_storage["Document storage"]
  node_db[("PostgreSQL + pgvector<br/>[schema.ts]")]
end

node_user(("Workspace user"))
node_arxiv_service["arXiv"]
node_provider_service["Configured model service"]
node_filesystem[("Local filesystem")]

node_user -->|"uses"| node_web
node_web -->|"renders"| node_auth_ui
node_web -->|"renders"| node_spaces_ui
node_web -->|"renders"| node_research_ui
node_web -->|"renders"| node_knowledge_ui
node_web -->|"renders"| node_agents_ui
node_web -->|"renders"| node_chat_ui
node_auth_ui -->|"requests"| node_api_client
node_spaces_ui -->|"requests"| node_api_client
node_research_ui -->|"requests"| node_api_client
node_knowledge_ui -->|"requests"| node_api_client
node_agents_ui -->|"requests"| node_api_client
node_chat_ui -->|"requests"| node_api_client
node_api_client -->|"HTTP requests"| node_server
node_realtime_client -->|"WebSocket events"| node_gateway
node_server -->|"dispatches"| node_auth
node_server -->|"dispatches"| node_spaces
node_server -->|"dispatches"| node_connections
node_server -->|"dispatches"| node_activity
node_server -->|"dispatches"| node_documents
node_server -->|"dispatches"| node_retrieval
node_server -->|"dispatches"| node_grounded
node_server -->|"dispatches"| node_agent
node_server -->|"dispatches"| node_research
node_server -->|"dispatches"| node_comparison
node_server -->|"dispatches"| node_chat
node_documents -->|"stores sources"| node_storage
node_documents -->|"queues indexing"| node_indexing
node_indexing -->|"reads sources"| node_storage
node_indexing -->|"generates vectors"| node_embedding
node_indexing -->|"writes indexes"| node_db
node_retrieval -->|"searches authorized chunks"| node_db
node_grounded -->|"retrieves evidence"| node_retrieval
node_grounded -->|"generates answer"| node_model
node_agent -->|"submits execution"| node_agent_worker
node_agent_worker -->|"uses Knowledge tool"| node_retrieval
node_agent_worker -->|"uses arXiv tool"| node_research
node_agent_worker -->|"requests decisions"| node_model
node_agent_worker -->|"persists runs and evidence"| node_db
node_research -->|"searches metadata"| node_arxiv
node_arxiv -->|"queries"| node_arxiv_service
node_comparison -->|"generates comparison"| node_model
node_summary -->|"generates summary"| node_model
node_research -->|"stores papers"| node_db
node_chat -->|"persists messages"| node_db
node_chat -->|"broadcasts updates"| node_gateway
node_gateway -->|"sends events"| node_realtime_client
node_auth -->|"reads and writes sessions"| node_db

click node_web "https://github.com/zzz395/researchweave/blob/main/src/app/router.tsx"
click node_api_client "https://github.com/zzz395/researchweave/blob/main/src/services/api/client.ts"
click node_auth_ui "https://github.com/zzz395/researchweave/blob/main/src/features/auth/pages/login-page.tsx"
click node_spaces_ui "https://github.com/zzz395/researchweave/blob/main/src/features/spaces/pages/spaces-page.tsx"
click node_research_ui "https://github.com/zzz395/researchweave/blob/main/src/features/research/pages/research-page.tsx"
click node_knowledge_ui "https://github.com/zzz395/researchweave/blob/main/src/features/knowledge/pages/knowledge-page.tsx"
click node_agents_ui "https://github.com/zzz395/researchweave/blob/main/src/features/agents/pages/agents-page.tsx"
click node_chat_ui "https://github.com/zzz395/researchweave/blob/main/src/features/chat/pages/space-chat-page.tsx"
click node_realtime_client "https://github.com/zzz395/researchweave/blob/main/src/services/realtime/realtime-provider.tsx"
click node_server "https://github.com/zzz395/researchweave/blob/main/server/app.ts"
click node_auth "https://github.com/zzz395/researchweave/blob/main/server/modules/auth/routes.ts"
click node_spaces "https://github.com/zzz395/researchweave/blob/main/server/modules/spaces/routes.ts"
click node_connections "https://github.com/zzz395/researchweave/blob/main/server/modules/connections/routes.ts"
click node_activity "https://github.com/zzz395/researchweave/blob/main/server/modules/activity/routes.ts"
click node_documents "https://github.com/zzz395/researchweave/blob/main/server/modules/documents/routes.ts"
click node_indexing "https://github.com/zzz395/researchweave/blob/main/server/modules/documents/document-indexing-worker.ts"
click node_retrieval "https://github.com/zzz395/researchweave/blob/main/server/modules/retrieval/routes.ts"
click node_grounded "https://github.com/zzz395/researchweave/blob/main/server/modules/grounded-answer/routes.ts"
click node_agent "https://github.com/zzz395/researchweave/blob/main/server/modules/agents/runtime.ts"
click node_agent_worker "https://github.com/zzz395/researchweave/blob/main/server/modules/agents/worker.ts"
click node_research "https://github.com/zzz395/researchweave/blob/main/server/modules/research/routes.ts"
click node_comparison "https://github.com/zzz395/researchweave/blob/main/server/modules/paper-comparison/routes.ts"
click node_summary "https://github.com/zzz395/researchweave/blob/main/server/modules/research/summary-repository.ts"
click node_chat "https://github.com/zzz395/researchweave/blob/main/server/modules/chat/routes.ts"
click node_gateway "https://github.com/zzz395/researchweave/blob/main/server/realtime/gateway.ts"
click node_arxiv "https://github.com/zzz395/researchweave/blob/main/server/integrations/arxiv/client.ts"
click node_model "https://github.com/zzz395/researchweave/blob/main/server/integrations/grounded-answer/openai-compatible-generator.ts"
click node_embedding "https://github.com/zzz395/researchweave/blob/main/server/integrations/document-embedding/openai-compatible-document-embedding-generator.ts"
click node_storage "https://github.com/zzz395/researchweave/blob/main/server/integrations/document-storage/local-filesystem-storage.ts"
click node_db "https://github.com/zzz395/researchweave/blob/main/server/db/schema.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_web,node_api_client,node_auth_ui,node_spaces_ui,node_research_ui,node_knowledge_ui,node_agents_ui,node_chat_ui,node_realtime_client,node_user toneBlue
class node_server,node_auth,node_spaces,node_connections,node_activity,node_chat,node_gateway,node_filesystem toneAmber
class node_documents,node_indexing,node_retrieval,node_grounded,node_agent,node_agent_worker toneMint
class node_research,node_comparison,node_summary toneRose
class node_arxiv,node_model,node_embedding,node_storage,node_db,node_arxiv_service,node_provider_service toneIndigo
```

## Components

### Web workspace

- [React application](https://github.com/zzz395/researchweave/blob/main/src/app/router.tsx): `src/app/router.tsx`
- [API client](https://github.com/zzz395/researchweave/blob/main/src/services/api/client.ts): `src/services/api/client.ts`
- [Authentication UI](https://github.com/zzz395/researchweave/blob/main/src/features/auth/pages/login-page.tsx): `src/features/auth/pages/login-page.tsx`
- [Spaces UI](https://github.com/zzz395/researchweave/blob/main/src/features/spaces/pages/spaces-page.tsx): `src/features/spaces/pages/spaces-page.tsx`
- [Research UI](https://github.com/zzz395/researchweave/blob/main/src/features/research/pages/research-page.tsx): `src/features/research/pages/research-page.tsx`
- [Knowledge UI](https://github.com/zzz395/researchweave/blob/main/src/features/knowledge/pages/knowledge-page.tsx): `src/features/knowledge/pages/knowledge-page.tsx`
- [Agent UI](https://github.com/zzz395/researchweave/blob/main/src/features/agents/pages/agents-page.tsx): `src/features/agents/pages/agents-page.tsx`
- [Space chat UI](https://github.com/zzz395/researchweave/blob/main/src/features/chat/pages/space-chat-page.tsx): `src/features/chat/pages/space-chat-page.tsx`
- [Realtime client](https://github.com/zzz395/researchweave/blob/main/src/services/realtime/realtime-provider.tsx): `src/services/realtime/realtime-provider.tsx`

### Application API

- [Express application](https://github.com/zzz395/researchweave/blob/main/server/app.ts): `server/app.ts`
- [Authentication](https://github.com/zzz395/researchweave/blob/main/server/modules/auth/routes.ts): `server/modules/auth/routes.ts`
- [Spaces and members](https://github.com/zzz395/researchweave/blob/main/server/modules/spaces/routes.ts): `server/modules/spaces/routes.ts`
- [Connections](https://github.com/zzz395/researchweave/blob/main/server/modules/connections/routes.ts): `server/modules/connections/routes.ts`
- [Activity and overview](https://github.com/zzz395/researchweave/blob/main/server/modules/activity/routes.ts): `server/modules/activity/routes.ts`
- [Chat API](https://github.com/zzz395/researchweave/blob/main/server/modules/chat/routes.ts): `server/modules/chat/routes.ts`
- [Realtime gateway](https://github.com/zzz395/researchweave/blob/main/server/realtime/gateway.ts): `server/realtime/gateway.ts`

### Knowledge workflows

- [Document ingestion](https://github.com/zzz395/researchweave/blob/main/server/modules/documents/routes.ts): `server/modules/documents/routes.ts`
- [Indexing pipeline](https://github.com/zzz395/researchweave/blob/main/server/modules/documents/document-indexing-worker.ts): `server/modules/documents/document-indexing-worker.ts`
- [Knowledge retrieval](https://github.com/zzz395/researchweave/blob/main/server/modules/retrieval/routes.ts): `server/modules/retrieval/routes.ts`
- [Grounded answers](https://github.com/zzz395/researchweave/blob/main/server/modules/grounded-answer/routes.ts): `server/modules/grounded-answer/routes.ts`
- [Bounded Agent runtime](https://github.com/zzz395/researchweave/blob/main/server/modules/agents/runtime.ts): `server/modules/agents/runtime.ts`
- [Durable Agent worker](https://github.com/zzz395/researchweave/blob/main/server/modules/agents/worker.ts): `server/modules/agents/worker.ts`

### Research workflows

- [Research discovery](https://github.com/zzz395/researchweave/blob/main/server/modules/research/routes.ts): `server/modules/research/routes.ts`
- [Paper comparison](https://github.com/zzz395/researchweave/blob/main/server/modules/paper-comparison/routes.ts): `server/modules/paper-comparison/routes.ts`
- [Paper summaries](https://github.com/zzz395/researchweave/blob/main/server/modules/research/summary-repository.ts): `server/modules/research/summary-repository.ts`

### Persistence and integrations

- [arXiv service](https://github.com/zzz395/researchweave/blob/main/server/integrations/arxiv/client.ts): `server/integrations/arxiv/client.ts`
- [Model providers](https://github.com/zzz395/researchweave/blob/main/server/integrations/grounded-answer/openai-compatible-generator.ts): `server/integrations/grounded-answer/openai-compatible-generator.ts`
- [Embedding provider](https://github.com/zzz395/researchweave/blob/main/server/integrations/document-embedding/openai-compatible-document-embedding-generator.ts): `server/integrations/document-embedding/openai-compatible-document-embedding-generator.ts`
- [Document storage](https://github.com/zzz395/researchweave/blob/main/server/integrations/document-storage/local-filesystem-storage.ts): `server/integrations/document-storage/local-filesystem-storage.ts`
- [PostgreSQL + pgvector](https://github.com/zzz395/researchweave/blob/main/server/db/schema.ts): `server/db/schema.ts`

### Other components

- **Workspace user**
- **arXiv**
- **Configured model service**
- **Local filesystem**

## Connections

- Workspace user → React application: uses
- React application → Authentication UI: renders
- React application → Spaces UI: renders
- React application → Research UI: renders
- React application → Knowledge UI: renders
- React application → Agent UI: renders
- React application → Space chat UI: renders
- Authentication UI → API client: requests
- Spaces UI → API client: requests
- Research UI → API client: requests
- Knowledge UI → API client: requests
- Agent UI → API client: requests
- Space chat UI → API client: requests
- API client → Express application: HTTP requests
- Realtime client → Realtime gateway: WebSocket events
- Express application → Authentication: dispatches
- Express application → Spaces and members: dispatches
- Express application → Connections: dispatches
- Express application → Activity and overview: dispatches
- Express application → Document ingestion: dispatches
- Express application → Knowledge retrieval: dispatches
- Express application → Grounded answers: dispatches
- Express application → Bounded Agent runtime: dispatches
- Express application → Research discovery: dispatches
- Express application → Paper comparison: dispatches
- Express application → Chat API: dispatches
- Document ingestion → Document storage: stores sources
- Document ingestion → Indexing pipeline: queues indexing
- Indexing pipeline → Document storage: reads sources
- Indexing pipeline → Embedding provider: generates vectors
- Indexing pipeline → PostgreSQL + pgvector: writes indexes
- Knowledge retrieval → PostgreSQL + pgvector: searches authorized chunks
- Grounded answers → Knowledge retrieval: retrieves evidence
- Grounded answers → Model providers: generates answer
- Bounded Agent runtime → Durable Agent worker: submits execution
- Durable Agent worker → Knowledge retrieval: uses Knowledge tool
- Durable Agent worker → Research discovery: uses arXiv tool
- Durable Agent worker → Model providers: requests decisions
- Durable Agent worker → PostgreSQL + pgvector: persists runs and evidence
- Research discovery → arXiv service: searches metadata
- arXiv service → arXiv: queries
- Paper comparison → Model providers: generates comparison
- Paper summaries → Model providers: generates summary
- Research discovery → PostgreSQL + pgvector: stores papers
- Chat API → PostgreSQL + pgvector: persists messages
- Chat API → Realtime gateway: broadcasts updates
- Realtime gateway → Realtime client: sends events
- Authentication → PostgreSQL + pgvector: reads and writes sessions