Skip to content

Infrastructure

Docker Compose

Available Profiles

Profile Services
dev fastapi, frontend-dev, redis
api / fastapi fastapi, redis
db neo4j (local instance)
pipeline / ingest pipeline-ingest
embed pipeline-embed
kg pipeline-kg
shell pipeline-shell (interactive)
streamlit / webapp webapp-streamlit
react-webapp graph-rag-react-webapp
monitoring prometheus, pushgateway, grafana
full everything

Development Stack

# Full dev stack (API + frontend + Redis)
docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile dev up

# With monitoring
docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile dev --profile monitoring up

# Custom frontend path
FRONTEND_PATH=~/Developer/olink/graphrag-react docker compose ... up

Services

  • fastapi — API on http://localhost:8000 with Granian --reload
  • frontend-dev — Vite dev server on http://localhost:5173 with HMR
  • redis — Session/cache store (2GB max, LRU eviction, AOF persistence)
  • neo4j — Graph database (2GB heap, 1GB page cache)
  • prometheus — Metrics scraping (every 15s)
  • pushgateway — CI metric push endpoint
  • grafana — Dashboards on http://localhost:3000

Neo4j

  • Version 5.20, Bolt (7687) + HTTP (7474)
  • Vector indexes for semantic search (node_embeddings, chunk_embeddings)
  • Fulltext indexes for keyword search
  • Connection options:
  • Local: bolt://localhost:7687
  • Docker: bolt://host.docker.internal:7687
  • AWS: bolt://your-neo4j-nlb.eu-north-1.elb.amazonaws.com:7687

Redis

  • Version 7 (Alpine), 2GB max memory, LRU eviction
  • Used for: session management, query result caching, ingestion job state, precomputed queries
  • Fallback: automatic in-memory fallback if Redis unavailable
  • See Redis Integration Guide for details

Neptune + Aurora (Scaled Production)

For millions-of-papers scale, the system supports AWS Neptune (graph) + Aurora pgvector (embeddings) as an alternative to Neo4j:

  • Neptune: OpenCypher queries via HTTPS with IAM SigV4 auth, serverless auto-scaling (1–128 NCU)
  • Aurora pgvector: HNSW-indexed 768-dim embeddings for vector similarity search
  • SQS: Decoupled extraction → ingestion pipeline for independent scaling
  • ECS Fargate: Extraction workers (4 vCPU/16 GB) + ingestion workers (1 vCPU/4 GB)

Key modules: - src/core/neptune_database.py — NeptuneDatabase class (batch UNWIND writes) - src/core/aurora_embedding_store.py — AuroraEmbeddingStore (pgvector) - src/agents/neptune_query_agent.py — NL-to-OpenCypher query agent - pipeline/ingest/scaled_ingest.py — Async pipeline (LLM pool + Neptune + Aurora) - pipeline/ingest/sqs_extraction_worker.py + sqs_ingestion_worker.py — SQS workers

CDK stacks: neptune_stack.py, aurora_pgvector_stack.py, extraction_queue.py, ingest_task_stack.py

See Neptune Massive Ingest and Neptune Runbook for operational details.

AWS CDK (Production)

cdk_resources/ is a separate Python project with its own pyproject.toml:

  • ECS for API containers + ingest tasks
  • Neo4j NLB (Network Load Balancer)
  • Neptune serverless (graph, scaled prod)
  • Aurora pgvector (embeddings, scaled prod)
  • SQS extraction queue + DLQ
  • EventBridge weekly ingest schedule
  • Secrets Manager for credentials
  • ElastiCache for Redis

Monitoring

Grafana Dashboard

Auto-provisioned at http://localhost:3000/d/olink-rag-eval-e2e:

  • Eval metrics: entity recall, retrieval recall, classification accuracy, latency percentiles
  • E2E metrics: journey pass/fail, execution time, accessibility violations
  • Alert rules: fire when any eval metric drops >5%
CI Workflows → Pushgateway:9091 ← Prometheus:9090 ← Grafana:3000

See Grafana Dashboard for setup details.

OpenTelemetry

Configured in src/services/telemetry.py, ready to enable:

OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_SERVICE_NAME=olink-rag

Dockerfile

Multi-stage build with Python 3.12-slim-bookworm:

  • Base: system deps + uv + dependency install
  • FastAPI target: Granian ASGI server on port 8000
  • Pipeline target: CLI entry point for ingestion
  • Test target: import checks + unit tests

CI/CD

GitHub Actions with 4 parallel test categories:

Category Timeout Runner
Unit 3 min ubuntu-latest
Integration 10 min ubuntu-latest
Property-based 10 min ubuntu-latest
Slow 15 min ubuntu-latest

Plus known-failures job with continue-on-error: true.