Syntology — orientation

{: .fs-9 }

A provenance-first knowledge graph of AI/ML research — papers, authors, venues, citations, methods, datasets, concepts, reviews, code repositories, and verified code samples — served to humans at syntology.ai / app.syntology.ai and to agents over REST and MCP. {: .fs-6 .fw-300 }

Architecture{: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } File catalog{: .btn .fs-5 .mb-4 .mb-md-0 }

What it is (one paragraph)

Syntology indexes AI/ML research into a Neo4j graph where every edge carries provenance (deterministic:*, derived:*, llm:*, measured, …). Humans get a marketing site, Atlas citation map, and demo/API surfaces; agents get trial tokens, /api/graph/ask, and an MCP server with typed tools. The graph is built by a local batch pipeline (codename canebrake) on a Mac writer machine and served from Neo4j Aura; the public edge is a Cloudflare Worker; the query API + MCP run on AWS App Runner.

Live product framing for agents: public/llms.txt and /developers.

5-minute system map

 browser / agent
      │
      ▼
 Cloudflare Worker (worker.js + modules, public/ assets)
      │  /api/graph/*, /mcp, /api/atlas/*, billing, trial tokens
      │  KV · Turnstile · Stripe · Aura HTTP (pulse/slice/atlas)
      ▼
 AWS App Runner — uvicorn main:app (Dockerfile.api)
      │  /graph/ask · templates · MCP · reviewer-bot
      ▼
 Neo4j Aura Professional
      ▲
      │  writer: local Mac (launchd + canebrake stages + WriteLedger)
 Local ingestion / enrichment / code harvest / QC

Runtime	Where	Main code	Credential tier
Site + edge API	Cloudflare Workers	`worker.js`, `*.js`, `public/`	Aura HTTP as `syntology_web` (RO); Stripe; KV
Query API + MCP	AWS App Runner `syntology-api`	`main.py`, `mcp_server.py`, `query_engine/`	`syntology_api_reader` (RO); Bedrock via task role
Ingestion / QC	Local Mac	`NN_.py`, `load_.py`, `run_*.sh`, `groundwork/`	`syntology_loader` (write); admin break-glass

Three runtimes share one repository but not one process. The ~130GB corpus (PDFs, TEI, parsed JSON) is not in git — it lives under a local corpus root (canebrake_corpus → working set) with S3/Glacier backup.

How to read these docs (black-box → white-box)

This project grew fast (“vibe-coded” with mechanical provenance standards bolted on). Docs here are intentionally layered:

Black box — this page + Architecture: what exists, who talks to whom, what is live vs illustrative.
Subsystem prose — Serving, Edge/CF, Ingestion, Graph & ledger, Code harvest, Frontend / Atlas, Ops / deploy, Modular candidate.
White box — File / module catalog: path → role → inputs → outputs → interactions → risks. Honest gaps beat invention.
Fragility — Security & fragility (key names only; link out to incident / review docs).
Contributor path — Reading order: which root markdown to trust when local main leads origin/main.

External deep dives (repo root, not always present on every branch): ARCHITECTURE.md, REVIEW_FINDINGS.md, UPGRADE_CANDIDATE.md, STANDARDS.md / USAGE.md / QC_PROCESS.md, SECURITY_INCIDENT_2026-08-21.md, CLAUDE.md. See Reading order.

What’s covered vs deferred

Covered here	Deferred / elsewhere
Topology, credentials tiers (names), pipeline stages, serving paths	Live graph counts (change daily — use `python -m syntology census` when available)
Important module roles and known risks	Exhaustive listing of every root `*.py` / every groundwork lane artifact
How to enable GitHub Pages from `/docs`	Auto-generated API reference from OpenAPI
Pointers to security findings	Secret values, PEM contents, `.env`

Local main may lead origin/main by hundreds of commits; a refresh pass after merge timing makes sense is expected.