Link from NCBI to BRC Analytics

[NoopDog]

Summary

NCBI and BRC Analytics are coordinating to improve cross-linking between their respective platforms.

Current State

• NCBI Assembly Pages (e.g. example) and NCBI Organism Pages (e.g. example) currently provide assembly- and taxonomy-specific data from NCBI.
• BRC Analytics already links out to NCBI from its assembly pages, allowing users to easily navigate to the canonical NCBI records.

Proposed Change

• NCBI has offered to add reciprocal links from its assembly detail pages and organism pages back to BRC Analytics.
• This would allow users browsing NCBI datasets to directly discover relevant resources and analytics available in BRC Analytics.

Impact

• Improves discoverability of BRC Analytics resources from widely used NCBI entry points.
• Strengthens interoperability between NCBI and BRC Analytics.
• Provides researchers with a smoother navigation experience across both platforms.

High-Level Tech Design

1. NCBI will periodically call BRC Analytics APIs to get the links to our organism detail pages and our analyze pages for assemblies.
2. The API will be implemented by placing the JSON file at the appropriate path in the NextJS public folder during build time and serving the files statically from their path within public. For example, a file at public/api/assets/myfile.json will be available after build/export at /api/assets/myfile.json.
3. At build time or pre-build step, the assemblies.json and organisms.json files will be processed to extract the relevant information for linking to BRC.
4. Links will be available at /api/links/organism-links.json and /api/links/assembly-links.json
5. Exact file format and URL path TBD.

Subtasks

• UI mocks for NCBI site for reciprocal linking
• Download assembly links API #782
• Download organism links API
• Organism page updates to add context to support arriving from an external site
• Analyze page updates to add context to support arriving from an external site
• Track inbound links from NCBI

[d-callan]

"Exact file format and URL path TBD"

Can we soon try to quickly get consensus on what the format and URL should be, who makes it happen, when we think we can get it done by, etc?

[d-callan]

heres the proposal, currently (slightly modified from something @NoopDog sent me):

URLs
Assemblies: /api/v0/assemblies/links
Taxonomy: /api/v0/organisms/links
[ edit to URLs to include version based on feedback from @dannon ]

json

{
  "version": "2025-09-23",
  "baseUrl": "https://brc-analytics.dev.clevercanary.com",
  "assemblies": [
    {
      "assemblyAccession": "GCA_001008285.1",
      "relativePath": "/data/assemblies/GCA_001008285_1"
    },
    {
      "assemblyAccession": "GCA_000001405.40",
      "relativePath": "/data/assemblies/GCA_000001405_40"
    }
  ]
}

{
  "version": "2025-09-23",
  "baseUrl": "https://brc-analytics.dev.clevercanary.com",
  "organisms": [
    {
      "ncbiTaxonomyId": 43142,
      "relativePath": "/data/organisms/43142"
    },
    {
      "ncbiTaxonomyId": 9606,
      "relativePath": "/data/organisms/9606"
    },
    {
      "ncbiTaxonomyId": 10090,
      "relativePath": "/data/organisms/10090"
    }
  ]
}

[d-callan]

i think we have a point of discussion here: whether to have static json files made at build time vs rest endpoints. now we have a basic rest framework, and a pr for supporting this there, that seems to me a reasonable path forward that both gets what we need quickly for the near term but also has flexibility to possible changing reqs in the future. happy to hear others thoughts either here or on a call sometime