Skip to content

Report Service

The Report service owns the clinical report artefact: the draft the curator builds during review, the signed PDF that sign-off produces, and the audit machinery around them (comments, snapshots, amendments).

What Report owns

Entity Purpose
Report The report itself — status, template type, PDF paths, approval / sign fields
ReportVariantAssociation Variants included in the report, with per-report overrides and snapshots
ReportComment Threaded comments (general / review / signoff / amendment)
ReportSnapshot Point-in-time saves of a report's state

Separate service, separate database

Report service runs independently from Miner. It references orders by string ID, not a foreign key, so each service can be deployed, scaled, and updated without coupling.

Cross-service boundary

Report service references orders and files by plain-string IDs, not foreign keys. Report.order_id and Report.file_id are strings that resolve to entities in Miner and the File service respectively. This is deliberate: it lets Report evolve independently of Miner's schema at the cost of no database-level referential integrity.

To fetch an order's data for rendering, Report makes an HTTP call to Miner via the MinerServiceClient. Sign-off's final step — advancing the order from sign_off to completed — also goes through this client.

Report states

stateDiagram-v2
    [*] --> draft
    draft --> pending_review: submit for review
    pending_review --> approved: approve
    approved --> signed: sign (Approve-and-Sign)
    signed --> amended: amend (creates new draft)
    draft --> draft: edit
    pending_review --> draft: send back

Enum values, as stored:

  • draft — being edited.
  • pending_review — awaiting review.
  • approved — approved; ready to sign.
  • signed — final; immutable PDF written.
  • amended — superseded by a later signed report on the same order.

Template types

Each report has a template_type that selects the DOCX template used for rendering:

  • clinical — default clinical report.
  • hereditary — germline / hereditary testing template.
  • somatic — somatic / tumour testing template.

The template is selected at report creation based on the order's analysis mode and, for somatic cases, additional metadata from the VCF. See Templates.

Subpages

  • Templates — template types and how they are selected.
  • Rendering — how a report becomes a PDF.
  • Sign-off PDF — the atomic Approve-and-Sign flow.
  • Snapshots — versioned saves of report state.
  • Comments — threaded review feedback.

Files

  • Draft / preview PDFs — reports/{slug}/.
  • Signed PDF — orders/{slug}/signed-report.pdf. Written once by Approve-and-Sign; never overwritten.

See File Paths.