[ThePyProgrammer]

Outcome and scope

Let a user open a paper and see which papers in the current library it cites and which library papers cite it. Each connection must have retrievable evidence, a reliable direction, and an indexing status that distinguishes missing data from a failed lookup.

Milestone 1 delivers persistent OpenAlex identities/references, a resumable indexing worker, local citation matching, API responses, paper-detail lists, and a measured coverage pilot. Milestone 2 captures Crossref references and measures the additional coverage. Milestone 3 evaluates Semantic Scholar and GROBID against the remaining gaps before adding a fallback.

The initial UI is library-scoped. Database-wide analysis can use an explicit authorized scope in the backfill tool. Graph visualization, citation-context highlighting, OCR, and automatic merging of preprint/published records are deferred. Semantic similarity is not citation evidence.

Design decisions

• Use PostgreSQL tables and transactional functions through the existing Supabase client. No graph database is required.
• Keep citation indexing separate from the capped discovery response in related_paper_service.py. Reuse provider request infrastructure only after making it suitable for bulk indexing.
• Resolve exact normalized identifiers automatically. Store title/author/year matches as candidates until validated; never accept the first search result by default. Missing or conflicting identities remain unresolved.
• Resolve the source population before intersecting references with local identities. Keep unresolved references so adding a target paper later can create a link without refetching the source.
• Keep provider assertions distinct from evidence extracted from the actual stored PDF. Preserve version/alias provenance; preprints and published versions can have different bibliographies.
• Use durable database jobs and a separate worker command. FastAPI background tasks may enqueue work, but do not own durable execution.
• An empty provider reference list means no references returned by that provider. It does not establish an empty bibliography.