This architecture is written by a taskforce. Every change goes through a pull request, so that we always know who wrote what, who reviewed it, and when.
New to the taskforce? Start with the Taskforce handbook (docs/handbook/): the writing order, a step-by-step choreography for each page, recipes per kind of page, the diagram rules, where to find sources, and the review checklists. This file is the short version.
| What | Where it is recorded |
|---|---|
| Who is responsible for a page | owner in the page's front matter, and the owner named in the issue's Review assignment; the owner is an assignee of the issue |
| Who must review it | reviewers in the front matter, by name and affiliation, as the architecture lead assigned them (decision D-029); reviewers with a GitHub account are requested on the pull request |
| Where the page stands | status in the front matter: placeholder → draft → in-review → approved |
| When it was last reviewed | last_reviewed in the front matter (set by the reviewer on approval) |
| Who changed what, and when | Git history; each page shows its last author and date at the bottom |
| Who approved a change, and when | Pull request approvals on GitHub (timestamped) |
| Which version readers see | Tagged releases (v0.1, v0.2, … v1.0) |
The Document status page of the site (docs/appendix/document-status.md) lists all pages with their owner, reviewers and status. It is generated from the front matter.
---
title: "6.2.2 Data discovery"
slug: /runtime/access/discovery
sidebar_position: 2
owner: "Name (Institution)"
reviewers: ["Name (Institution)", "Name (Institution, specialist)"]
status: draft # placeholder | draft | in-review | approved
wave: 4 # writing wave 1–6 (see docs/handbook/writing-order.md)
audience: [elsi, dpo, implementer] # policy | legal | elsi | security | dpo | implementer
governance_refs: ["VII.2.1", "VII.2.3"] # section IDs from src/data/governance.json
last_reviewed: 2026-10-15 # set when approved
---owner and reviewers give names and affiliations, not GitHub accounts: not every reviewer uses GitHub, and readers of the site and of the Word exports should see who reviewed a page. Mark a specialist reviewer with specialist after the affiliation (decision D-029).
npm run check validates these fields. CI runs it on every pull request.
The full step-by-step version, with who does what and when each step is done, is the page choreography.
- Pick up the page. Assign yourself the page's GitHub issue (titled
[page] <page title>), or open one with the Page task template. Setownerandstatus: draftin the front matter. The architecture lead assigns the reviewers of each page; write them inreviewersby name and affiliation, as in the example above, and name them in the issue. - Write on a branch. Keep the structure of every page:
- the
<InShort>box: at most three plain-language bullets; - the content, citing governance sections with
<GovRef id="VII.2.3" />and other sources with<Cite id="gdi-d3.4" />.
- the
- Ask for review. Set
status: in-review, open a pull request that saysCloses #<issue number>, and fill in the checklist. Request the reviewers listed inreviewerswho have a GitHub account on the pull request; the others review a Word export (Review rounds). Add aneeds-dpo,needs-security,needs-legalorneeds-elsilabel to the issue when a specialist must review. - Review. Reviewers read the page in the preview of the pull request: a rendered copy of the whole site at
https://genomicdatainfrastructure.github.io/system-architecture/pr-<number>/, linked in a comment on the pull request and updated on every push (see Previews and publication). Reviewers comment in the pull request. When satisfied, the reviewer setsstatus: approvedandlast_reviewedto today, and approves the pull request. - Merge.
mainaccepts a pull request once it has at least one approval and CI passes. Merging closes the issue.
- Write for a reader who is not an IT specialist: short sentences, active voice, one idea per paragraph.
- Use the governance terms exactly as defined (e.g. 1+MG Data Holder, Genome EDIC CC, key-coded identifier).
- Link the first mention of each glossary term on a page to its entry:
[1+MG Data Holder](/glossary#1mg-data-holder). Readers often land on a page directly, and these terms say who is responsible. Where a concept page explains a term in more depth, link to it instead (the types of dataset link to 8.12). Leave headings and the In short box without links (decision D-022).- The anchor is the glossary heading in lower case, with spaces turned into hyphens and other characters dropped: 1+MG Data Holder →
1mg-data-holder.npm run buildfails on a link to an anchor that doesn't exist.
- The anchor is the glossary heading in lower case, with spaces turned into hyphens and other characters dropped: 1+MG Data Holder →
- Link the first use of each acronym on a page with
<Acronym id="SPE" />: readers see its meaning as a tooltip, and it links to the glossary's acronym table. Add new acronyms tosrc/data/acronyms.json(decision D-021).<Acronym>is for acronyms only; an acronym inside a glossary term (1+MG NCP) is covered by the term's link. - Say which responsible party (the Genome EDIC, the Member Country, the User Organisation) a component or step belongs to (decision D-036). In chapter 7, say at which level (central, national, local) it runs.
- Prefer a diagram plus a short text over long prose. Diagrams follow the diagram rules (decision D-019): draw.io, a white background, and a legend with the section and the date of the last edit. Run
npm run diagramsafter editing one. - Record open points and open questions, risks and technical debt in chapter 11, in the same pull request that raises them: one entry each, with a fixed anchor. On the page, mark each point in a
:::caution[Open point],:::caution[Risk]or:::caution[Technical debt]box that links to its entry ([chapter 11](/risks#dataset-type-choice)). Only the entry links to the GitHub issue.npm run checkenforces the links (decision D-023). The page recipe gives the format of an entry.- If two pull requests add entries at the same place in chapter 11, Git reports a conflict. Keep both entries.
- Check each page against the arc42 documentation for its section. The page recipe lists what arc42 asks and the departures we agreed; explain any other departure in the pull request (decision D-024).
- Interfaces first: describe a component by its function, interfaces and standards, then name its reference implementation (GDI Starter Kit or GDI central service). A country may use other tools that meet the same interfaces (decisions D-007, D-020).
Every issue title starts with its main label in square brackets, [label] Title, and has that label (decision D-032). Each kind has an issue template.
| Kind | Title | Labels | Template |
|---|---|---|---|
| A page or an ADR | [page] <page title> |
page, chapter, wave, party |
Page task |
| An open point, open question or dependency (chapter 11) | [open-point] <title> |
open-point, chapter-11 |
Open point |
| A risk (chapter 11) | [risk] <title> |
risk, chapter-11 |
Risk |
| An action point from a taskforce meeting | [action] <title> |
action |
Action point |
| A question from a reader | [reader-question] <title> |
reader-question |
Reader question |
Every page has one GitHub issue, titled [page] <page title>. Its labels give the chapter, responsible party, wave and any specialist review (needs-dpo, needs-security, needs-legal, needs-elsi). Useful searches:
| To find | Search in Issues |
|---|---|
| Pages without an owner or reviewers | is:issue is:open label:page no:assignee |
| The pages you review or own | is:issue is:open label:page assignee:@me |
| Open action points from taskforce meetings | is:issue is:open label:action |
| Open points and risks | is:issue is:open label:open-point,risk |
| The pages of a wave | is:issue is:open label:page label:wave-1 |
| The pages of a chapter | is:issue label:page label:chapter-06 |
| The pages of a responsible party | is:issue label:page label:scope-national |
| Pages waiting for a DPO review | is:issue is:open label:needs-dpo |
The issue's assignees are the owner and the reviewers of the page; its Review assignment section says who is who (decision D-032). The taskforce board shows the pages of the active waves, the pull requests and the action points.
When pages are added, the architecture lead creates their issues with scripts/github/setup.mjs. The script skips issues that already exist, and its header lists all its commands.
- In the same pull request. A pull request that adds a page creates its issue, so that no page is ever without one. This includes every ADR.
- Renamed pages. The script finds an issue by its title,
[page] <page title>. When a page's title changes, rename its issue first, or the script creates a second one. - In the pull request description. List each page with its issue (
#123). Pages themselves don't link to issues; only chapter 11 does (decision D-023).
DRY_RUN=1 node scripts/github/setup.mjs issues # preview: prints the gh commands
node scripts/github/setup.mjs issues # creates the missing issuesBoth the published site and the pull request previews are served by GitHub Pages from the gh-pages branch (decision D-025). Nobody edits that branch by hand.
| What | Where | Published by |
|---|---|---|
The site, from main |
https://genomicdatainfrastructure.github.io/system-architecture/ (root of gh-pages) |
Deploy to GitHub Pages (.github/workflows/deploy.yml), on every push to main |
| The preview of a pull request | https://genomicdatainfrastructure.github.io/system-architecture/pr-<number>/ (folder pr-<number>/) |
Pull request preview (.github/workflows/preview.yml), on every push to the pull request |
- The preview workflow posts the URL in one comment on the pull request and updates it on every push. GitHub Pages needs a minute or two after the run to publish the files.
- The preview shows a banner naming the pull request and is marked
noindex, so search engines do not pick up drafts. When the pull request is closed or merged, its folder is removed and the comment says so. - Only pull requests from branches of this repository get a preview. A pull request from a fork runs with a read-only token and cannot publish; such a pull request is checked by CI but reviewed from the source.
- To see a page under the preview path locally:
PR_NUMBER=123 npm run build && npm run serve.
One-off set-up (architecture lead): the repository's Pages source must be Deploy from a branch, branch gh-pages, folder / (root) (Settings > Pages). The branch is created by the first run of Deploy to GitHub Pages; switch the source after that run, so that the site never goes blank. Nothing else changes: the deploy workflow keeps the pr-* folders, and the preview workflow touches only its own folder.
The architecture lead releases a version when a set of pages is approved, or when the baseline changes (for example, a new version of the governance).
- In a pull request, move the
[Unreleased]notes inCHANGELOG.mdunder a heading## [0.N.0] - YYYY-MM-DD(the day you will tag), and add its compare link at the bottom of the file. - Once it is merged, tag
mainwith a signed tag and push it:git tag -s v0.N -m "v0.N: <summary>", thengit push origin v0.N. - On GitHub, publish a release for the tag, with that changelog section as the release notes.
- Optional: to get a DOI, switch on the Zenodo–GitHub integration for this repository before publishing the release.