Genetic History Module — Technical Brief

1. What it is

EU-based B2B push-model software module installed in clinical / medical laboratory infrastructure for Y-DNA / mtDNA ancestry-narrative generation — partner customer data never transfers out.

The module turns NGS pipeline output (VCF) into a research-grade haplogroup narrative plus per-subclade geographic heatmap. Partner delivers the narrative to its patient via the partner’s existing patient-communication channel.

2. Deployment form

Docker image, published to a container registry (GHCR primary; private registry on request). Multi-stage build, distroless base. Single command:

docker pull ghcr.io/genetichistory/module:v1.0
docker run --network none -p 8080:8080 -e PARTNER_KEY=... \
  ghcr.io/genetichistory/module:v1.0

--network none is supported and recommended — the module operates fully offline at runtime (see §6).

3. Input contract

Format: VCF v4.2+ (uncompressed or bgzipped)
Granularity: one sample per request
Schema: validated at the request boundary; unknown / malformed payloads rejected with structured error (RFC 7807)
No PII fields required or accepted — module rejects requests carrying patient-identifier metadata

4. Output contract

Narrative: structured JSON + presentational HTML; per-haplogroup; languages EN + ES at v1.0 (DE / FR / IT roadmap). Typical length 600–1200 words per lineage.
Heatmap: SVG choropleth per subclade. Adaptive granularity:
- subclades with ≥500 reference samples → admin-1 polygons (Natural Earth 1:10M)
- subclades with <500 reference samples → country-level polygons (Natural Earth 1:50M)
Optional referral footer: single non-intrusive link to the haplogroup’s page on yfull.com — partner can disable.
Disclaimer footer: non-clinical / historical-context framing, included on every response.

5. Integration surface

REST over HTTPS, container-local. No outbound calls.
POST /v1/analyze → { narrative, heatmap_svg, version_manifest }
Authentication: PARTNER_KEY (Bearer); rotation customer-driven
Idempotency: Idempotency-Key header honored
Errors: RFC 7807 Problem Details

End-to-end:

curl -X POST http://localhost:8080/v1/analyze \
  -H "Authorization: Bearer $PARTNER_KEY" \
  -H "Content-Type: application/json" \
  --data @sample.vcf.json

6. Data locality (architectural invariant — do not weaken)

Partner customer data never transfers to Genetic History S.L. infrastructure. No egress. No telemetry carrying sample identifiers. The module operates fully offline after the container starts; zero call-home, zero usage analytics, zero runtime logs sent to Genetic History.

Verifiable by the partner: docker run --network none ... confirms a full report served without any external call. Any opt-in metadata (e.g., aggregate library-version statistics) is documented, off by default, and contains no patient identifiers.

7. Library update protocol

Library refresh ships as a new image tag (v1.0.x). Partner pulls on a partner-controlled cadence (recommended weekly / monthly / quarterly per partner stability preference). No silent auto-update; partner controls every version transition.

Push channel: GHCR (Scaleway EU, Spain region — library-distribution scope only; non-PII assets)
Rollback: docker pull previous tag + restart
Version-skew: 12-month deprecation window on MAJOR; MINOR / PATCH additive

8. Resource footprint

Dimension	v1.0
Image size	≈ 500 MB – 1 GB (assets bundled, fully offline)
RAM	1 GB minimum, 2 GB recommended
CPU	1 vCPU minimum
Disk	2 GB free (image + scratch tmpfs)
Runtime per sample	typically 5–30 s

9. Supported coverage

Y-DNA: ≈ 200,000 Y-SNP branches via in-house YFull pipeline (as of 2026-04)
mtDNA: ≈ 20,000 mtDNA branches
Languages v1.0: EN + ES (DE / FR / IT planned per roadmap)
Tree source: YFull (ISOGG + FTDNA aliases for cross-reference)

10. Compliance posture

GDPR Art. 9: partner platform obtains explicit consent from the patient; module has no PII access by design (see §6). Sub-processor: Scaleway (EU, Spain region — library-distribution scope only).
EU AI Act: non-clinical ancestry-context framing; formal classification review by Peer 8 Legal / Compliance Counsel scheduled post-MVP-live (~2026-05-15..05-25). Module ships with AI-assisted-content disclosure on every response.
MDR / IVDR: out of scope — historical context, not medical interpretation. No diagnosis, no treatment, no risk-prediction, no pharmacogenomics output.
Ley 14/2007 (ES): wellness / genealogical scope; non-clinical framing.

DPA template + sub-processor registry available on request — see contact §12.

11. Sandbox availability

v1.0: prospect technical evaluation via dedicated staging endpoint, provisioned per pilot. Request access via §12 contact. v2.0: self-service sandbox planned post-Wave 1 validation.

12. Versioning + contact

Spec version: 1.0 (2026-04-27)
Owner: Genetic History S.L.U. (CIF B24962573, Barcelona)
Contact: urasin@yfull.com
Status / changelog: https://genetichistory.es/specs/api-module/changelog

Genetic History S.L.U. operates the YFull bioinformatics service (yfull.com) under the same corporate perimeter; B2B clinical-lab integration is the focus of this brief.

Direct contact: urasin@yfull.com