# iai-ustc-quantum/quantumatlas architecture

> Architecture diagram of the GitHub repository iai-ustc-quantum/quantumatlas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iai-ustc-quantum/quantumatlas
- Repository: https://github.com/iai-ustc-quantum/quantumatlas

## Overview

QuantumAtlas is a paper collection, registry, and multi-paradigm search service, exposed through a Go/PocketBase server and browser UI. The principal flow is arXiv or user-submitted papers entering lazy acquisition, durable asset storage and registry tracking, then becoming searchable across local and external sources. Other documented capabilities include MinerU parsing, OpenAlex corpus mirroring, collaboration, and managed downloader workers. The README supports the broad product flow; source excerpts clarify selected ingestion and search behavior. Several UI and service connections remain unverified because their implementations were not sampled.

Main entry points: [`internal/routes`](https://github.com/iai-ustc-quantum/quantumatlas/tree/main/internal/routes) (HTTP API routes), [`internal/search/engine.go`](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/search/engine.go) (Search engine), [`internal/ingest/ingester.go`](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/ingest/ingester.go) (Lazy ingestion), [`internal/objstore/store.go`](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/objstore/store.go) (Object storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server and API"]
  node_qatlasd["qatlasd service<br/>[main.go]"]
  node_api["HTTP API routes"]
  node_identity["OAuth and tokens<br/>[oauth.go]"]
  node_comments["Paper discussions<br/>[comments.go]"]
end

subgraph group_acquisition["Acquisition and parsing"]
  node_ingester["Lazy ingestion<br/>[ingester.go]"]
  node_downloader["PDF acquisition<br/>[downloader.go]"]
  node_fleet["Worker fleet<br/>[service.go]"]
  node_mineru["MinerU parsing<br/>[client.go]"]
  node_mineru_upload["Parse uploads"]
end

subgraph group_paperdata["Paper data"]
  node_object_store[("Object storage<br/>[store.go]")]
  node_registry[("Paper registry<br/>[registry.go]")]
  node_assets["Paper assets<br/>[path.go]"]
  node_openalex_corpus[("OpenAlex corpus<br/>[ingest.go]")]
end

subgraph group_discovery["Search and discovery"]
  node_search_api["Search endpoint<br/>[search.go]"]
  node_search_engine["Search engine<br/>[engine.go]"]
  node_catalog["Local catalog<br/>[catalog.go]"]
  node_arxiv_search["arXiv search<br/>[arxiv.go]"]
  node_openalex_search["OpenAlex search<br/>[openalex.go]"]
  node_qdrant["Qdrant retrieval<br/>[remote.go]"]
end

subgraph group_experience["User experience"]
  node_web_app["Web application<br/>[main.tsx]"]
  node_search_page["Search and results"]
  node_paper_page["Paper reader"]
  node_discussion_page["Discussion view"]
  node_dashboard["Dashboard"]
  node_device_login["Device authorization<br/>[$lang.device.tsx]"]
  node_downloader_page["Downloader controls"]
  node_pat_page["Token management<br/>[$lang.pat.tsx]"]
  node_admin_assets["Asset administration"]
  node_admin_workers["Worker administration"]
  node_admin_home["Admin console"]
  node_admin_pipelines["Pipeline controls"]
  node_admin_plugins["Plugin controls"]
end

node_researcher(("Researchers"))
node_submit(("arXiv and uploads"))

node_researcher -->|"uses"| node_web_app
node_submit -->|"submits papers"| node_ingester
node_qatlasd -->|"hosts API"| node_api
node_web_app -.->|"calls"| node_api
node_api -.->|"authenticates"| node_identity
node_api -.->|"requests ingestion"| node_ingester
node_ingester -->|"fetches PDFs"| node_downloader
node_downloader -->|"stores assets"| node_object_store
node_ingester -->|"registers assets"| node_registry
node_ingester -->|"writes PDFs"| node_object_store
node_mineru_upload -->|"parses uploads"| node_mineru
node_mineru_upload -->|"stores parse outputs"| node_object_store
node_mineru_upload -->|"records revisions"| node_registry
node_fleet -->|"dispatches downloads"| node_downloader
node_api -.->|"manages workers"| node_fleet
node_api -->|"serves search"| node_search_api
node_search_api -.->|"queries"| node_search_engine
node_search_engine -.->|"fans out"| node_catalog
node_search_engine -.->|"fans out"| node_arxiv_search
node_search_engine -.->|"fans out"| node_openalex_search
node_search_engine -.->|"retrieves vectors"| node_qdrant
node_search_engine -->|"anchors results"| node_registry
node_search_page -.->|"submits queries"| node_search_api
node_paper_page -.->|"loads paper"| node_api
node_discussion_page -.->|"loads discussions"| node_comments
node_api -.->|"serves collaboration"| node_comments
node_openalex_corpus -->|"reads corpus"| node_object_store
node_dashboard -.->|"loads status"| node_api
node_device_login -.->|"authorizes device"| node_identity
node_downloader_page -.->|"controls acquisition"| node_api
node_pat_page -.->|"manages tokens"| node_api
node_admin_assets -.->|"manages assets"| node_api
node_admin_workers -.->|"manages workers"| node_api
node_admin_home -.->|"loads administration"| node_api
node_admin_pipelines -.->|"controls pipelines"| node_api
node_admin_plugins -.->|"manages plugins"| node_api

click node_qatlasd "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/cmd/qatlasd/main.go"
click node_api "https://github.com/iai-ustc-quantum/quantumatlas/tree/main/internal/routes"
click node_identity "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/auth/oauth.go"
click node_comments "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/comments/comments.go"
click node_ingester "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/ingest/ingester.go"
click node_downloader "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/downloader/downloader.go"
click node_fleet "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/downloadfleet/service.go"
click node_mineru "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/mineru/client.go"
click node_mineru_upload "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/routes/papers_mineru_ingest.go"
click node_object_store "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/objstore/store.go"
click node_registry "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/registry/registry.go"
click node_assets "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/paperassets/path.go"
click node_openalex_corpus "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/openalexcorpus/ingest.go"
click node_search_api "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/routes/search.go"
click node_search_engine "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/search/engine.go"
click node_catalog "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/search/catalog.go"
click node_arxiv_search "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/search/arxiv.go"
click node_openalex_search "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/search/openalex.go"
click node_qdrant "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/rag/remote.go"
click node_web_app "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/main.tsx"
click node_search_page "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.papers.search.tsx"
click node_paper_page "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.papers.%24paperId.tsx"
click node_discussion_page "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.papers.%24paperId_.discussions.tsx"
click node_dashboard "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.dashboard.tsx"
click node_device_login "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.device.tsx"
click node_downloader_page "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.downloader.tsx"
click node_pat_page "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.pat.tsx"
click node_admin_assets "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.admin.assets.tsx"
click node_admin_workers "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.admin.downloader-workers.tsx"
click node_admin_home "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.admin.index.tsx"
click node_admin_pipelines "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.admin.pipelines.tsx"
click node_admin_plugins "https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.admin.plugins.tsx"

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_qatlasd,node_api,node_identity,node_comments toneBlue
class node_ingester,node_downloader,node_fleet,node_mineru,node_mineru_upload toneAmber
class node_object_store,node_registry,node_assets,node_openalex_corpus toneMint
class node_search_api,node_search_engine,node_catalog,node_arxiv_search,node_openalex_search,node_qdrant toneRose
class node_web_app,node_search_page,node_paper_page,node_discussion_page,node_dashboard,node_device_login,node_downloader_page,node_pat_page,node_admin_assets,node_admin_workers,node_admin_home,node_admin_pipelines,node_admin_plugins,node_researcher,node_submit toneIndigo
```

## Components

### Server and API

- [qatlasd service](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/cmd/qatlasd/main.go): `cmd/qatlasd/main.go`
- [HTTP API routes](https://github.com/iai-ustc-quantum/quantumatlas/tree/main/internal/routes): `internal/routes`
- [OAuth and tokens](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/auth/oauth.go): `internal/auth/oauth.go`
- [Paper discussions](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/comments/comments.go): `internal/comments/comments.go`

### Acquisition and parsing

- [Lazy ingestion](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/ingest/ingester.go): `internal/ingest/ingester.go`
- [PDF acquisition](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/downloader/downloader.go): `internal/downloader/downloader.go`
- [Worker fleet](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/downloadfleet/service.go): `internal/downloadfleet/service.go`
- [MinerU parsing](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/mineru/client.go): `internal/mineru/client.go`
- [Parse uploads](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/routes/papers_mineru_ingest.go): `internal/routes/papers_mineru_ingest.go`

### Paper data

- [Object storage](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/objstore/store.go): `internal/objstore/store.go`
- [Paper registry](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/registry/registry.go): `internal/registry/registry.go`
- [Paper assets](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/paperassets/path.go): `internal/paperassets/path.go`
- [OpenAlex corpus](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/openalexcorpus/ingest.go): `internal/openalexcorpus/ingest.go`

### Search and discovery

- [Search endpoint](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/routes/search.go): `internal/routes/search.go`
- [Search engine](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/search/engine.go): `internal/search/engine.go`
- [Local catalog](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/search/catalog.go): `internal/search/catalog.go`
- [arXiv search](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/search/arxiv.go): `internal/search/arxiv.go`
- [OpenAlex search](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/search/openalex.go): `internal/search/openalex.go`
- [Qdrant retrieval](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/internal/rag/remote.go): `internal/rag/remote.go`

### User experience

- [Web application](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/main.tsx): `web/src/main.tsx`
- [Search and results](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.papers.search.tsx): `web/src/routes/$lang.papers.search.tsx`
- [Paper reader](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.papers.%24paperId.tsx): `web/src/routes/$lang.papers.$paperId.tsx`
- [Discussion view](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.papers.%24paperId_.discussions.tsx): `web/src/routes/$lang.papers.$paperId_.discussions.tsx`
- [Dashboard](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.dashboard.tsx): `web/src/routes/$lang.dashboard.tsx`
- [Device authorization](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.device.tsx): `web/src/routes/$lang.device.tsx`
- [Downloader controls](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.downloader.tsx): `web/src/routes/$lang.downloader.tsx`
- [Token management](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.pat.tsx): `web/src/routes/$lang.pat.tsx`
- [Asset administration](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.admin.assets.tsx): `web/src/routes/$lang.admin.assets.tsx`
- [Worker administration](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.admin.downloader-workers.tsx): `web/src/routes/$lang.admin.downloader-workers.tsx`
- [Admin console](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.admin.index.tsx): `web/src/routes/$lang.admin.index.tsx`
- [Pipeline controls](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.admin.pipelines.tsx): `web/src/routes/$lang.admin.pipelines.tsx`
- [Plugin controls](https://github.com/iai-ustc-quantum/quantumatlas/blob/main/web/src/routes/%24lang.admin.plugins.tsx): `web/src/routes/$lang.admin.plugins.tsx`

### Other components

- **Researchers**
- **arXiv and uploads**

## Connections

- Researchers → Web application: uses (evidence: `README.md`)
- arXiv and uploads → Lazy ingestion: submits papers (evidence: `README.md`)
- qatlasd service → HTTP API routes: hosts API (evidence: `README.md`)
- Web application → HTTP API routes: calls
- HTTP API routes → OAuth and tokens: authenticates
- HTTP API routes → Lazy ingestion: requests ingestion
- Lazy ingestion → PDF acquisition: fetches PDFs (evidence: `internal/ingest/ingester.go`)
- PDF acquisition → Object storage: stores assets (evidence: `internal/downloader/downloader.go`)
- Lazy ingestion → Paper registry: registers assets (evidence: `internal/ingest/ingester.go`)
- Lazy ingestion → Object storage: writes PDFs (evidence: `internal/ingest/ingester.go`)
- Parse uploads → MinerU parsing: parses uploads (evidence: `internal/routes/papers_mineru_ingest.go`)
- Parse uploads → Object storage: stores parse outputs (evidence: `internal/routes/papers_mineru_ingest.go`)
- Parse uploads → Paper registry: records revisions (evidence: `internal/routes/papers_mineru_ingest.go`)
- Worker fleet → PDF acquisition: dispatches downloads (evidence: `internal/downloadfleet/service.go`)
- HTTP API routes → Worker fleet: manages workers
- HTTP API routes → Search endpoint: serves search (evidence: `README.md`)
- Search endpoint → Search engine: queries
- Search engine → Local catalog: fans out
- Search engine → arXiv search: fans out
- Search engine → OpenAlex search: fans out
- Search engine → Qdrant retrieval: retrieves vectors (evidence: `README.md`)
- Search engine → Paper registry: anchors results (evidence: `internal/search/engine.go`)
- Search and results → Search endpoint: submits queries
- Paper reader → HTTP API routes: loads paper
- Discussion view → Paper discussions: loads discussions
- HTTP API routes → Paper discussions: serves collaboration
- OpenAlex corpus → Object storage: reads corpus (evidence: `internal/openalexcorpus/ingest.go`)
- Dashboard → HTTP API routes: loads status
- Device authorization → OAuth and tokens: authorizes device
- Downloader controls → HTTP API routes: controls acquisition
- Token management → HTTP API routes: manages tokens
- Asset administration → HTTP API routes: manages assets
- Worker administration → HTTP API routes: manages workers
- Admin console → HTTP API routes: loads administration
- Pipeline controls → HTTP API routes: controls pipelines
- Plugin controls → HTTP API routes: manages plugins
