How it works

How PhageFlow Works

A step-by-step tour of what happens to your FASTA file after upload — each pipeline stage, the output it produces, and what is discovered about the genome along the way. The fast stages run on upload; the heavier evidence stages run as a background pass.

Two passes

Baseline runs on upload; evidence runs in the background.

Baseline (fast)Validation + ORF calling return immediately so you see a draft right away (stages 1–2).

Evidence (background)tRNA, translation, Pfam, BLASTp, and the structure seam run as a follow-up pass that merges in when ready (stages 3–7).

ReviewEverything lands in one review screen with exports (stage 8).

Upload · synchronous

FASTA intake & validation

Your uploaded file is parsed as a single-record FASTA. PhageFlow confirms there is exactly one sequence, that every base is valid DNA (A/T/C/G/N), and reads the header as the genome name.

How it runs

Rejects multi-record files, sequence-before-header, or non-DNA characters with a clear error.
Auto-detects target: a header containing “phage” / “bacteriophage” / “prophage” switches on phage-specific expectations; everything else is treated as generic.
Measures basic composition and flags anything that looks off.

Output

header the genome name from the > line
target "phage" or "generic"
sequence.length_bp total base pairs
sequence.gc_percent GC content, e.g. 63.4
sequence.ambiguous_bases counts of any non-ATCG bases
warnings[] e.g. “too short for a complete phage genome”, “contains N bases”

What is discovered

Whether the file is even usable before any compute is spent.
Rough genome size and GC% — first sanity check that this looks like a real phage genome.
Early red flags (truncated paste, ambiguous bases, wrong organism type).

Upload · synchronous

Baseline ORF calling

A six-frame open-reading-frame scan walks all three frames on both strands, opening at a start codon (ATG/GTG/TTG) and closing at a stop (TAA/TAG/TGA). ORFs shorter than the minimum (default 30 aa) are dropped.

How it runs

Forward and reverse-complement strands are both scanned; coordinates are mapped back to the original genome.
Each ORF records its strand, frame, start/stop positions, the actual start and stop codons, and length in nt and aa.
This is deliberately a conservative baseline — it is labeled as draft suggestions, not final gene calls.

Output

baseline_orfs.method "six-frame start/stop ORF scan"
baseline_orfs.count number of candidate ORFs
baseline_orfs.items[] id, strand, frame, start, end, start_codon, stop_codon, length_nt, length_aa

What is discovered

Candidate gene locations across the whole genome — the scaffold every later stage hangs off of.
How many potential protein-coding regions exist and roughly how they are distributed.
A reviewable draft queue, not an answer: short genes, big overlaps, and gaps still need human curation.

Evidence · background

tRNA detection

The evidence stage scans the genome for transfer-RNA genes — which ordinary ORF calling cannot find because tRNAs do not code for protein.

How it runs

Prefers tRNAscan-SE; falls back to Aragorn; if neither binary is on the image it returns a clearly-labeled “unavailable” block rather than guessing.
Production worker images ship Aragorn, so real classroom runs get genuine calls.

Output

trna.method "tRNAscan-SE", "Aragorn", or "unavailable"
trna.count number of tRNAs found
trna.items[] id, strand, start, end, isotype, anticodon, score

What is discovered

Whether the phage carries its own tRNA genes (some do, some don’t — a real biological feature of the genome).
Which amino acids those tRNAs serve, via the predicted isotype and anticodon.
Non-coding features that the ORF scan would otherwise miss entirely.

Evidence · background

Protein translation

Every baseline ORF is translated into an amino-acid sequence using the standard codon table, with alternative starts (GTG/TTG) forced to methionine, stopping at the first stop codon.

How it runs

Reverse-strand ORFs are reverse-complemented before translation so the reading frame is correct.
These translated proteins become the input for all downstream function-prediction stages.

Output

proteins.count number of translated proteins
proteins.items[] orf_id, length_aa, sequence (the amino-acid string)
export proteins-fasta — a standard .faa protein FASTA

What is discovered

The actual protein products predicted from each candidate gene.
A protein FASTA students can carry into external tools (BLASTp, HHpred, AlphaFold) by hand.
Protein lengths — a quick reasonableness check on each ORF call.

Evidence · background · opt-in

Pfam / HMMER domain search

Each translated protein is searched against the Pfam profile-HMM database with hmmscan to find conserved protein domains — strong, family-level functional evidence.

How it runs

Runs only when hmmscan is installed AND a pressed Pfam-A.hmm database is configured via PFAM_DB.
The multi-GB Pfam database is intentionally not bundled; it is mounted on demand to keep image size and cost low.
Without the DB it reports “unavailable” with exact setup guidance — it never fabricates a hit.

Output

pfam.method "hmmscan/Pfam" or "unavailable"
pfam.count number of domain hits
pfam.items[] protein, pfam_name, pfam_acc, evalue, score
export pfam-csv

What is discovered

Conserved domains inside each protein — often the clearest clue to what a gene does.
Family-level function even when no near-identical sequence match exists.
Which proteins are likely structural, enzymatic, regulatory, etc., by domain signature.

Evidence · background · opt-in

BLASTp function hints

Translated proteins are compared against known protein sequences to find similar, already-characterized proteins and borrow their functional annotations.

How it runs

Resolution order: a local curated protein DB (BLASTP_DB) if present; else NCBI remote BLAST against nr when PHAGEFLOW_REMOTE_BLAST=1; else “unavailable”.
Remote BLAST is capped at 25 proteins and off by default, sized for a ~10-genomes-per-year classroom so NCBI is never hammered.

Output

blastp.method "blastp/local", "blastp/remote-nr", or "unavailable"
blastp.count number of hits
blastp.items[] protein, subject, percent_identity, evalue, bitscore, title
export blastp-csv

What is discovered

Named matches to previously characterized proteins — the most intuitive line of functional evidence.
How confident each match is, via percent identity, E-value, and bit score.
Candidate gene functions to confirm against Pfam and instructor review.

Evidence · seam · deferred

Structure-based function (Phase 4)

The hardest functional calls come from 3D protein structure: predict a fold (AlphaFold/ESMFold), then search it against known structures (Foldseek) or profiles (HHpred). PhageFlow has the report/UI seam in place but the engine is deferred.

How it runs

Structure prediction needs GPUs and multi-hundred-GB databases, so the plan is hosted-API-only, never self-hosted.
Until a hosted provider is approved (PHAGEFLOW_STRUCTURE_PROVIDER), this stage honestly reports “deferred” and fabricates nothing.

Output

structure.method "deferred" (until a provider is wired up)
structure.count 0 for now
structure.note explains it is Phase 4, hosted-API-only

What is discovered

Nothing yet — by design. The section is visible so the workflow is honest about what is and isn’t computed.
Once enabled: function for proteins that have no sequence match but a recognizable fold (remote homology).

Review · synchronous

Draft review & export

All of the above is merged into one report behind a review screen. Per-gene decisions and notes are saved as review_overrides on top of the baseline calls, and everything can be exported.

How it runs

Baseline ORFs become an editable review queue; instructor accept/change/notes persist without losing the underlying evidence.
Exports include the full JSON report plus per-evidence CSVs and the protein FASTA.

Output

report.review_overrides per-gene decisions and notes
pipeline { stage, stages_run, evidence_complete }
exports JSON report, review-csv, trna-csv, proteins-fasta, pfam-csv, blastp-csv

What is discovered

A single, reviewable draft annotation that gathers every evidence type in one place.
A clear record of which calls a human accepted or changed, and why.
Submission-ready exports — for classroom review, not automatic official submission.

What PhageFlow Computes

Validates and characterizes the FASTA.
Calls baseline ORFs across both strands.
Finds tRNA genes.
Translates proteins and gathers Pfam + BLASTp evidence.
Merges everything into one reviewable draft.

What It Leaves To Humans

Final gene calls and start-site choices.
Function decisions when evidence is weak.
Structure-based calls (Phase 4, deferred).
Official submission \u2014 never automatic.