Product Specification

Aligned with Olink SDLC for Analytical Tools (D15979).

---

1. Purpose

The GraphRAG platform is an analytical tool suite that enables Olink researchers and product managers to:

• Collect and integrate biomedical data from 30+ public and proprietary sources
• Build a knowledge graph of protein-disease-drug relationships from literature and databases
• Query the graph using natural language to support panel design, competitive analysis, and biomarker discovery
• Evaluate extraction quality and compare LLM models for continuous improvement

This specification documents the software architecture, responsibilities, development process, and current status of all components.

---

2. Scope

The scope covers the full lifecycle of five interconnected analytical tools:

Tool	Scope	Status
bioingest	Data acquisition, transformation, competitor scraping, S3 publishing	Production (ECS + CLI)
graphrag_api	Knowledge graph construction, query engine, LLM orchestration	Production (ECS)
graphrag_react	Web frontend for NL graph queries and visualization	Production (3 environments)
graphrag_eval	Benchmarking extraction accuracy, model comparison, cost analysis	Internal tool
00panel	Proteomic panel design research using KG + data lake	Research / Development

In scope

• Requirements, design, development, testing, deployment, and maintenance of all five tools
• Infrastructure provisioning (AWS CDK)
• Data pipelines from source to queryable graph
• User-facing documentation (wikis)

Out of scope

• External customer-facing products (Olink Analyze, NPX Software)
• QC manufacturing tools
• Raw instrument data processing

---

3. Responsibility

3.1 Tool Owner

Responsible for:

• Defining software architecture and technical vision across all five repos
• Reviewing requirements from requesters (PMs, researchers)
• Aligning with Product Manager on features, roadmap, and strategic priorities
• Aligning with dependent tools (see Section 6 — Dependency Map)
• Communication with stakeholders about changes and releases
• Managing third-party library status and licenses
• Deploying new releases
• Distributing release notes
• Ensuring this specification stays current

3.2 Software Developers

Responsible for:

• Refining tasks from GitHub Issues
• Writing code following repo conventions (see AGENTS.md per repo)
• Writing unit tests (pytest / Vitest)
• Performing code reviews (PR approval required before merge)
• Contributing to technical documentation and wiki pages

3.3 Product Manager

Involved when:

• New data sources are prioritized for ingestion
• New frontend features are scoped
• Panel design requirements change
• Competitive analysis scope changes (which platforms to track)

3.4 Requesters

Researchers or PMs who:

• Request new data sources via Request a Source
• File feature requests as GitHub Issues
• Validate that delivered features meet requirements

3.5 QA

Involved for:

• Production deployments affecting shared infrastructure (Neptune, Aurora)
• Breaking changes to the API contract
• Changes to data published to S3 (affects downstream consumers)

---

4. Description

4.1 System Architecture

flowchart TB
    subgraph Sources["Data Sources"]
        DB[(Public DBs\nUniProt, STRING, Reactome\nClinVar, GTEx, gnomAD...)]
        COMP[Competitor Catalogs\nMSD, Quanterix, Nomic\nRBM, Alamar, Roche, Abbott]
        LIT[Literature\nPubMed, bioRxiv, PMC, PDFs]
        INT[Internal\nOlink panels, LIMS, curated data]
    end

    subgraph Pipeline["bioingest"]
        DL[Download / Scrape]
        CLEAN[Clean and Transform]
        KG[KG Extraction\nLLM entities + relationships]
        PUB[Publish to S3 + Graph]
    end

    subgraph Backend["graphrag_api"]
        QUERY[NL Query Engine]
        INGEST[Ingestion Pipeline]
    end

    subgraph Storage["Storage Layer"]
        NEP[(Neptune\nKnowledge Graph)]
        AUR[(Aurora pgvector\nEmbeddings)]
        S3[(S3 Data Lake\nParquet + Athena)]
    end

    subgraph Frontend["User-Facing"]
        REACT[graphrag_react\nWeb UI]
        WIKI[Wikis\nData Explorer]
    end

    subgraph Support["Support Tools"]
        EVAL[graphrag_eval\nBenchmarks]
        PANEL[00panel\nPanel Design]
    end

    DB & COMP & LIT & INT --> DL
    DL --> CLEAN --> PUB
    DL --> KG --> PUB
    PUB --> NEP & AUR & S3

    QUERY --> NEP & AUR
    INGEST --> NEP & AUR
    REACT -->|REST / WebSocket| QUERY
    S3 --> WIKI
    S3 --> PANEL
    NEP --> PANEL
    EVAL -->|test harness| QUERY

4.2 Component Details

bioingest

Attribute	Value
Language	Python 3.10+
Package manager	uv
Entry point	bioingest CLI, bioingest.tui interactive menu
Deployment	ECS Fargate worker (prod), local CLI (dev)
Infrastructure	CDK TypeScript (infra/)
Tests	330+ (pytest)
Repository	Olink-Proteomics/bioingest
Wiki	bioingest.mlapps.olink.systems

Key capabilities: bulk download (28 sources), competitor scraping (10 platforms), KG pipeline (fetch/extract/chunk/resolve/write/embed), S3 publish + Athena, platform overlap analysis, interactive TUI.

graphrag_api

Attribute	Value
Language	Python 3.12
Framework	LangGraph + LangChain
LLM	AWS Bedrock (Claude, Nova), Ollama (local)
Graph DB	Neo4j (dev) / Neptune (prod)
Vector store	Aurora pgvector
Deployment	ECS Fargate
Version	0.2.0
Repository	Olink-Proteomics/graphrag_api
Wiki	api.mlapps.olink.systems

Key capabilities: semantic dynamic context graph, NL queries, multi-hop reasoning, provenance chains, context-aware routing, streaming WebSocket responses.

graphrag_react

Attribute	Value
Language	TypeScript
Framework	React 18 + TanStack Router + TanStack Query
Visualization	Graphistry, D3, Monaco editor
Deployment	ECS / CloudFront
Version	0.1.0
Repository	Olink-Proteomics/graphrag_react

Environment	URL
Production	graphrag-react.mlapps.olink.systems
Alpha	graphrag-alpha-react.mlapps.olink.systems
Beta	graphrag-beta-react.mlapps.olink.systems

Key capabilities: conversational KG queries, interactive graph viz, in-browser Python (Pyodide), admin panel, pipeline monitoring.

graphrag_eval

Attribute	Value
Language	Python 3.12
Deployment	Local / CI
Repository	Olink-Proteomics/graphrag_eval
Wiki	eval.mlapps.olink.systems

Key capabilities: entity/relationship extraction F1, model comparison, scaling projections, cost analysis, VLM benchmark.

00panel

Attribute	Value
Language	Python 3.11+
Deployment	Local / Wiki
Repository	Olink-Proteomics/00panel
Wiki	panel.mlapps.olink.systems

Key capabilities: panel design optimization, protein combination scoring, disease-association analysis. Sources data from S3 data lake (bioingest) and knowledge graph (graphrag_api) for evidence-based panel construction.

---

5. Development Process

5.1 Design Input (Requirements)

• Feature requests filed as GitHub Issues with labels (feature, data-source, bug)
• Large features documented in issue body with acceptance criteria
• Tool owner reviews and prioritizes with PM input
• Dependency chart (Section 6) consulted before starting work

5.2 Source Code Management

• All repos under Olink-Proteomics GitHub org (private)
• Peer review required (PR approval) before merge to main
• Development on feature branches, separated from production
• Git LFS for large data files (bioingest data/bulk/)
• Coding standards enforced by ruff (Python) and eslint (TypeScript)

5.3 Verification and Testing

Repo	Framework	Strategy
bioingest	pytest	Unit + integration, 330+ tests
graphrag_api	pytest + pytest-asyncio	Unit + integration + E2E
graphrag_react	Vitest	Component + integration
graphrag_eval	pytest	Benchmark harness
00panel	pytest	Analysis validation

• Tests stored in each repo alongside code
• CI runs tests on PR (GitHub Actions)
• Reference test data committed to repos

5.4 Release and Deployment

Versioning: Major.Minor.Patch per D15979:

• Major: Breaking changes (API contract, schema migration)
• Minor: New features, new data sources
• Patch: Bug fixes, documentation

Deployment channels:

Component	Method	Trigger
bioingest worker	CDK deploy → ECS	Manual (tool owner)
graphrag_api	Docker → ECS	Manual
graphrag_react	Docker → ECS/CloudFront	Manual (3 envs)
Wikis (all)	GitHub Actions → Pages	Auto on push to docs/
Data lake (S3)	bioingest publish	Manual / scheduled

Release communication: GitHub Releases with changelog. Breaking changes communicated to all dependent repo owners before deploy.

5.5 Maintenance

• Deficiencies handled per D13048
• Dependency updates reviewed monthly
• Feature requests tracked in GitHub Issues
• Wiki documentation updated when behavior changes (automated via kiro hook)

---

6. Dependency Map

flowchart LR
    BI[bioingest] -->|graph data| API[graphrag_api]
    BI -->|S3 parquet| PANEL[00panel]
    API -->|query API| REACT[graphrag_react]
    API -->|test harness| EVAL[graphrag_eval]
    API -->|KG queries| PANEL
    REACT -->|user feedback| API

Change impact matrix:

If you change...	Also check/update...
bioingest graph schema	graphrag_api query templates, graphrag_eval test fixtures
bioingest S3 table schema	00panel analysis scripts, wiki data explorer
graphrag_api endpoints	graphrag_react API calls, graphrag_eval harness
graphrag_api ingestion	bioingest bridge module
Neptune/Aurora schema	All repos using graph queries

---

7. Infrastructure

AWS (eu-north-1, unless noted)

Resource	Service	Account	Purpose
Neptune cluster	Graph DB	prod (357836458011)	Knowledge graph storage
Aurora PostgreSQL	pgvector	prod	Embedding similarity search
ECS bioingest-workers	Fargate	prod	Data ingestion workers
S3 bioingest-datalake-*	Object storage	dev (002356212513)	Parquet data lake
Glue bioingest	Catalog	dev	66 Athena tables
Bedrock	LLM	prod (us-east-1)	Claude, Nova inference
GitHub Pages	Static hosting	—	All 4 wikis

DNS (Route53, mlapps.olink.systems)

Subdomain	Target
bioingest.mlapps.olink.systems	Wiki (GitHub Pages)
api.mlapps.olink.systems	Wiki (GitHub Pages)
eval.mlapps.olink.systems	Wiki (GitHub Pages)
panel.mlapps.olink.systems	Wiki (GitHub Pages)
graphrag-react.mlapps.olink.systems	Frontend (Production)
graphrag-alpha-react.mlapps.olink.systems	Frontend (Alpha)
graphrag-beta-react.mlapps.olink.systems	Frontend (Beta)

---

8. References

Document	Title
D15979	SDLC for Analytical Tools (this spec follows)
D3858	User Requirement Specification template
D5517	Development and Verification Plan template
D15834	Dependency Chart (Software and Analytical Tools)
D13048	Software Deficiency Management Process
D0108	Change Request Procedure
D3156	IT Access Management Policy