Skip to main content

Where does the V-model live when you develop software?

If your device includes software, the V-model is the reference for how requirements flow down to implementation and back up through verification and validation. The question most teams face is: which parts of that model belong in CertHub, and which parts stay in the engineering environment?

The short answer is: the V-model records live in CertHub. Implementation and test execution live outside. That is not a CertHub convention. It is how medical-device design controls already separate a traceability matrix of controlled artifacts from the last hop into source.

Two jobs, not one annotation scheme​

A newcomer often asks: if I have to sync system requirements, why don't I put SYSREQ on every function? Because those are two different jobs.

Job 1 — the QMS / technical file. ISO 13485 requires you to document methods to ensure traceability of design and development outputs to design and development inputs (ISO 13485:2016 clause 7.3.2(e); the same text is now in US QMSR via 21 CFR 820). That method is a bidirectional matrix of records: user needs, design inputs, design outputs, verification, validation. Auditors walk that matrix. They do not grep your repository for requirement IDs.

Job 2 — this git baseline. FDA's General Principles of Software Validation (GPSV, 2002) §5.2.4 asks for a source code traceability analysis: modules and functions trace to an element of the software design specification, and tests trace to that same specification. The design specification is a design output, not a system requirement.

Put the two together:

CertHub (Job 1)                         Engineering (Job 2)
UREQ → SYSREQ → DOUT ───────────────►  source tagged with DOUT
              ↘ VERIF ──────────────►  test tagged with VERIF
UREQ → VALID                           (manual / intended use — not unit tests)

You sync the left so the matrix exists in your tools. You tag only the right, because that is the hop GPSV actually names for source. Putting SYSREQ on functions would skip the design-output layer that verification is defined against (ISO 13485 7.3.6: verification shall confirm that the design output meets the design input requirements; 21 CFR 820.30(f)).

IEC 62304 says the same thing in planning language: the software development plan shall address TRACEABILITY between SYSTEM requirements, software requirements, SOFTWARE SYSTEM test and RISK CONTROL measures implemented in software (IEC 62304:2006+A1:2015 5.1.1(c)). Those traces live between controlled records. Source comments are one engineering method for the last hop, not a substitute for the matrix.

Records — maintain in CertHub​

Keep these as controlled, reviewable records, including the traces between them:

  • user requirements (user needs)
  • system / software requirements (design inputs)
  • component and unit requirements, if you use those layers
  • design outputs (the software design specification and related specifications)
  • verification (the controlled definition of the activity — and, when you file it, the result)
  • validation (the controlled definition of the intended-use activity)
  • the Tracer edges that make the matrix bidirectional

This is the technical-file view that QM and RA need to review, defend, and approve. CertHub is built for that.

Design output belongs here as a record. ISO 13485 7.3.4 requires outputs to be documented in a form suitable for verification against inputs, to contain or reference acceptance criteria, and to be approved before release. The source file that implements an output is not a substitute for that record.

Execution — your engineering environment​

Everything that is a build, a run, or a generated report stays where the engineering team works:

  • code and implementation
  • unit and integration test execution
  • per-commit dashboards and generated evidence packs
  • build artifacts and CI pipelines

How you do the last hop (Job 2) is your engineering choice: CodeLinks-style comments, Doorstop, Doxygen, a small script against the API. The pattern does not require a particular toolchain. See Working example.

CertHub does not need to become your IDE or your CI system.

Why you sync layers you never tag in code​

Export the whole V-model you maintain, not only the IDs that appear in comments.

  • Completeness is the point of 7.3.2(e). An input with no output is a dropped requirement. An output with no input is scope creep. If your engineering export omits unlinked rows, you hide the finding the matrix is supposed to show.
  • Wrong-product or leftover text is a system-of-record problem. Clean it in CertHub. Do not drop a knowledge topic from the sync because some rows have no code.
  • Validation is a different question from verification. 21 CFR 820.30(g) and ISO 13485 7.3.7 ask whether the device meets user needs and intended use, typically under actual or simulated use. That is not “did the unit test pass?” Sync validation protocols; do not pretend pytest closes them.
  • You may still have rows with no software. Procedure design outputs, labelling specs, or hardware outputs stay in the catalog. They simply have no source marker. That is correct, not incomplete tagging.

AAMI TIR45:2023 (FDA-recognized consensus standard 13-143) is the usual reference for doing this in an Agile team: traces are lifecycle outputs, updated as you go, not a comment-only scheme bolted on at release.

What this split does not claim: IEC 62304 5.1.1(c) also names risk-control measures. Those stay in the risk file (ISO 14971) in CertHub unless you explicitly export them. Source comments are one method for GPSV’s last hop; the standard requires the traces, not a particular marker syntax.

Two directions, not one​

This split creates two data movements, and most teams need both.

1. Export: V-model records go out​

Your engineering tools need the controlled records and the traces. Export them from CertHub via the API so Git, Jira, Sphinx, Azure DevOps, or an internal service can use them.

This is a read operation. CertHub stays the system of record. Your tools get a synced copy of the matrix — including rows you will never tag in source.

2. Write back: selected evidence comes in​

When your engineering process produces a result that matters for the technical file, write a short evidence record back into CertHub.

This is typically a release-level record, not a copy of every test run. A practical minimum is:

  • a version number
  • a commit or build identifier
  • a timestamp
  • a URL pointing to the full evidence (for example, a CI run or a report in your artifact store)
  • a short summary of the gate result

The full build tree, the complete JUnit output, the generated HTML dashboards — those stay in your CI or artifact store. CertHub gets the controlled pointer and the summary you actually review.

You choose the depth​

How much you write back is a decision for your team. Some organizations write a single release record per version. Others write more granular records per verification activity.

The recommendation is: start with the minimum that gives QM and RA what they need. You can always add depth later. You should not try to replicate the entire engineering environment inside CertHub.

On the export side, the usual depth is the V-model you actually maintain (often seven content topics plus traces). You do not have to implement every layer in software. You do have to see it if it is in the SoR.

One example, not the method​

Cadence is CertHub’s public engineering example of this pattern. It uses the CertHub API; useblocks (Sphinx-Needs / CodeLinks / Test-Reports) is the optional last-hop toolchain in that repo, not a CertHub requirement.

Cadence syncs seven Requirements Engineering knowledge topics from CertHub into a Git codebase. Source comments use design-output IDs; tests use verification IDs. System requirements close the engineering gate through Tracer links, not through extra comments. It builds a full evidence pack on every commit, and writes one release-evidence record back to CertHub on full version tags.

Use it as a reference implementation. Replace the bottom of the V with your own stack — the pattern stays the same. See Working example for the annotated V and the two downstream applications (trace down to code, and tests plus selected write-back), or watch the walkthrough.

Try the example locally
git clone https://github.com/CertHubCode/certhub-useblocks-example.git
cd certhub-useblocks-example
make install
make show              # tests + gate + open dashboard — expect VERIFIED, 4/4 SYSREQ PASS (no API key)

API key only when you sync or push a Release Record (cp .env.example .env, then make sync). The repository README covers the guided path, the RED/GREEN demo (make break / make fix), and CI setup. docs/traceability-map.md in that repo is the worked example of what to mark in code and why.

What not to do​

  • Do not try to replicate your entire engineering workflow inside CertHub.
  • Do not leave requirements, design outputs, and verification only in your development tool without a controlled copy in the technical file.
  • Do not stamp system-requirement IDs on source as a substitute for the design-output record. Verification confirms that the output meets the input.
  • Do not drop unlinked rows from the export to make the pack look cleaner. Completeness is the finding.
  • Do not dump the full CI artifact tree into CertHub. Store it where it belongs and write a pointer back.
  • Do not build a custom sync without first understanding which IDs CertHub uses for API calls versus dashboard URLs. They are not interchangeable.

Recommendation​

For software as a medical device, maintain the V-model records and their traces in CertHub. Let engineering own the last hop into source and test execution. Connect the two with the API: export the matrix your tools need, write back what the technical file needs.

Rule of thumb: sync the V-model; in code, tag only what software actually implements or verifies. Unlinked rows are fine. Wrong-product rows are a system-of-record problem, not a reason to sync less.

When you are ready​