Skip to content

File Paths

Every iFlow project has a dedicated cloud storage bucket (GCS on Google Cloud, S3 on AWS). Paths shown to users are relative to the project bucket — you do not see or type bucket names, gs://, or s3:// URIs anywhere in iFlow except on the project settings page where an administrator configures the bucket.

Canonical layout

{project-bucket}/
├── client-resources/              # Permanent resources, exempt from retention
│   ├── report-templates/          # Report DOCX templates
│   ├── bed-files/                 # BED interval files
│   └── gene-panels/               # Gene panel lists
│
├── subjects/{slug}/uploads/       # Subject-level uploads (consent forms, notes)
│
├── samples/{slug}/uploads/        # Sample-level uploads (VCF, BAM, FASTQ)
│
├── analyses/{slug}/               # Analysis pipeline outputs
│
├── orders/{slug}/                 # Order-level artefacts
│   └── signed-report.pdf          # Immutable final report (set at sign-off)
│
├── reports/{slug}/                # Report drafts, preview PDFs, attachments
│
├── workspace/
│   ├── wdl/                       # WDL pipeline scratch
│   └── nextflow/                  # Nextflow pipeline scratch
│
└── uploads/                       # General project uploads

The {slug} convention

{slug} is derived from the entity's display_id (the human-readable identifier you see in the UI) by:

  1. Lower-casing.
  2. Replacing every run of non-alphanumeric characters with a single hyphen.
  3. Trimming leading and trailing hyphens.

So a subject with display_id = "NA12878" uses subjects/na12878/uploads/, and an order with display_id = "ORD-001" uses orders/ord-001/.

Because paths are derived from display_id, entities that already have files on disk cannot be renamed. The slug is effectively frozen at the moment the first file is written under that entity.

What lives where

Path What it contains
client-resources/report-templates/ DOCX report templates referenced by report_template_type.
client-resources/bed-files/ BED interval files used by pipelines for target enrichment.
client-resources/gene-panels/ Gene panel lists used by the variant browser.
subjects/{slug}/uploads/ Subject-scoped documents (consent, clinical notes).
samples/{slug}/uploads/ Sample inputs: VCF (bgzipped, tabix-indexed), BAM, FASTQ, plus any lab-supplied metadata.
analyses/{slug}/ Pipeline outputs, logs, and metadata.
orders/{slug}/ Order-scoped artefacts (e.g. the final signed PDF).
orders/{slug}/signed-report.pdf The immutable signed report PDF, written once by Approve-and-Sign.
reports/{slug}/ Preview and draft report renderings, attachments.
workspace/wdl/, workspace/nextflow/ Pipeline engine scratch.
uploads/ General uploads not tied to a specific entity.

Entities with files cannot be renamed

Because display_id drives the slug in the path, renaming an entity after files are written would orphan those files. The slug is effectively frozen at first file write.

Retention

  • Files under client-resources/ are exempt from retention cleanup. Use it for anything that must survive regardless of retention policy — report templates, BED files, gene panels.
  • All other paths are subject to the project's retention policy, if any. Consult your project administrator.

Use client-resources/ for anything that must survive retention

Report templates, BED files, and gene panels go here. Everything else is subject to the project's retention policy.

Why you never see bucket names

The platform's data model deliberately hides the bucket from end users:

  • The CLI displays paths relative to the project bucket.
  • API responses return relative paths.
  • Internal DB columns store relative paths; bucket identity is in the project's configuration, not on the file record.

The only place a bucket name is surfaced is on the project settings page, where an administrator configures which bucket backs the project.

Legacy paths

Some files from earlier versions of iFlow live outside this layout. They are grandfathered and remain accessible through the file browser, but new files always use the canonical layout above.