# fulcrumgenomics/fgsv architecture

> Architecture diagram of the GitHub repository fulcrumgenomics/fgsv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fulcrumgenomics/fgsv
- Repository: https://github.com/fulcrumgenomics/fgsv

## Overview

fgsv is a command-line toolkit for detecting and exploring structural-variant breakpoint evidence, not a complete variant-calling pipeline. Its principal workflow scans queryname-grouped alignments into breakpoint pileups, aggregates nearby evidence, then can convert aggregate results to BEDPE. Filtering/merging is a separate pileup-processing option. The model layer represents aligned segments, breakpoints, evidence, and pileups. README capabilities inform the tool relationships; several tool implementations were not sampled, so their internal calls are not inferred.

Main entry points: [`src/main/scala/com/fulcrumgenomics/sv/tools/SvPileup.scala`](https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/tools/SvPileup.scala) (SvPileup), [`src/main/scala/com/fulcrumgenomics/sv/tools/AggregateSvPileup.scala`](https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/tools/AggregateSvPileup.scala) (AggregateSvPileup), [`src/main/scala/com/fulcrumgenomics/sv/cmdline/SvMain.scala`](https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/cmdline/SvMain.scala) (fgsv dispatcher), [`src/main/scala/com/fulcrumgenomics/sv/cmdline/SvTool.scala`](https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/cmdline/SvTool.scala) (Tool framework)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entry"]
  node_svmain["fgsv dispatcher<br/>[SvMain.scala]"]
  node_svtool["Tool framework<br/>[SvTool.scala]"]
end

subgraph group_detection["Breakpoint detection"]
  node_svpileup["SvPileup<br/>[SvPileup.scala]"]
end

subgraph group_processing["Pileup processing"]
  node_aggregate["AggregateSvPileup"]
  node_bedpe["AggregateSvPileupToBedPE"]
  node_filtermerge["FilterAndMerge"]
end

subgraph group_models["Domain models"]
  node_segments["Aligned segments"]
  node_evidence["Breakpoint evidence"]
  node_breakpoint["Breakpoint model<br/>[Breakpoint.scala]"]
  node_pileup_model["Breakpoint pileup"]
end

node_user(("CLI user"))
node_bam_in["Queryname BAM"]
node_pileup_table["Pileup table"]
node_tagged_bam["Tagged BAM"]
node_aggregate_table["Aggregated pileups"]
node_aggregate_bam["Aggregate-tagged BAM"]
node_targets["Target BED"]
node_bedpe_file["BEDPE output"]
node_merged_table["Filtered merged pileups"]
node_genome_browser(("Genome browser"))

node_user -->|"runs command"| node_svmain
node_svmain -->|"dispatches tools"| node_svtool
node_svmain -->|"dispatches"| node_svpileup
node_svmain -->|"dispatches"| node_aggregate
node_svmain -->|"dispatches"| node_bedpe
node_svmain -->|"dispatches"| node_filtermerge
node_svpileup -->|"uses framework"| node_svtool
node_aggregate -->|"uses framework"| node_svtool
node_bedpe -->|"uses framework"| node_svtool
node_filtermerge -->|"uses framework"| node_svtool
node_svpileup -->|"scans templates"| node_bam_in
node_svpileup -->|"builds segments"| node_segments
node_svpileup -->|"detects evidence"| node_evidence
node_evidence -->|"forms breakpoint"| node_breakpoint
node_svpileup -->|"collects pileups"| node_pileup_model
node_svpileup -->|"writes candidates"| node_pileup_table
node_svpileup -->|"writes tags"| node_tagged_bam
node_aggregate -->|"reads pileups"| node_pileup_table
node_aggregate -.->|"queries support"| node_bam_in
node_aggregate -.->|"checks overlap"| node_targets
node_aggregate -->|"writes aggregates"| node_aggregate_table
node_aggregate -->|"writes tags"| node_aggregate_bam
node_aggregate -->|"produces input"| node_aggregate_table
node_aggregate_table -->|"provides pileups"| node_bedpe
node_bedpe -->|"converts to BEDPE"| node_bedpe_file
node_bedpe_file -.->|"viewed in"| node_genome_browser
node_filtermerge -->|"reads pileups"| node_pileup_table
node_filtermerge -->|"writes merged sites"| node_merged_table

click node_svmain "https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/cmdline/SvMain.scala"
click node_svtool "https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/cmdline/SvTool.scala"
click node_svpileup "https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/tools/SvPileup.scala"
click node_segments "https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/AlignedSegment.scala"
click node_evidence "https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/BreakpointEvidence.scala"
click node_breakpoint "https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/Breakpoint.scala"
click node_pileup_model "https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/BreakpointPileup.scala"
click node_aggregate "https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/tools/AggregateSvPileup.scala"
click node_bedpe "https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/tools/AggregateSvPileupToBedPE.scala"
click node_filtermerge "https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/tools/FilterAndMerge.scala"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_svmain,node_svtool,node_user,node_genome_browser toneBlue
class node_svpileup toneAmber
class node_aggregate,node_bedpe,node_filtermerge toneMint
class node_segments,node_evidence,node_breakpoint,node_pileup_model toneRose
class node_bam_in,node_pileup_table,node_tagged_bam,node_aggregate_table,node_aggregate_bam,node_targets,node_bedpe_file,node_merged_table toneIndigo
```

## Components

### Command entry

- [fgsv dispatcher](https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/cmdline/SvMain.scala): `src/main/scala/com/fulcrumgenomics/sv/cmdline/SvMain.scala`
- [Tool framework](https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/cmdline/SvTool.scala): `src/main/scala/com/fulcrumgenomics/sv/cmdline/SvTool.scala`

### Breakpoint detection

- [SvPileup](https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/tools/SvPileup.scala): `src/main/scala/com/fulcrumgenomics/sv/tools/SvPileup.scala`

### Pileup processing

- [AggregateSvPileup](https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/tools/AggregateSvPileup.scala): `src/main/scala/com/fulcrumgenomics/sv/tools/AggregateSvPileup.scala`
- [AggregateSvPileupToBedPE](https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/tools/AggregateSvPileupToBedPE.scala): `src/main/scala/com/fulcrumgenomics/sv/tools/AggregateSvPileupToBedPE.scala`
- [FilterAndMerge](https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/tools/FilterAndMerge.scala): `src/main/scala/com/fulcrumgenomics/sv/tools/FilterAndMerge.scala`

### Domain models

- [Aligned segments](https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/AlignedSegment.scala): `src/main/scala/com/fulcrumgenomics/sv/AlignedSegment.scala`
- [Breakpoint evidence](https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/BreakpointEvidence.scala): `src/main/scala/com/fulcrumgenomics/sv/BreakpointEvidence.scala`
- [Breakpoint model](https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/Breakpoint.scala): `src/main/scala/com/fulcrumgenomics/sv/Breakpoint.scala`
- [Breakpoint pileup](https://github.com/fulcrumgenomics/fgsv/blob/main/src/main/scala/com/fulcrumgenomics/sv/BreakpointPileup.scala): `src/main/scala/com/fulcrumgenomics/sv/BreakpointPileup.scala`

### Other components

- **CLI user**
- **Queryname BAM**
- **Pileup table**
- **Tagged BAM**
- **Aggregated pileups**
- **Aggregate-tagged BAM**
- **Target BED**
- **BEDPE output**
- **Filtered merged pileups**
- **Genome browser**

## Connections

- CLI user → fgsv dispatcher: runs command
- fgsv dispatcher → Tool framework: dispatches tools
- fgsv dispatcher → SvPileup: dispatches
- fgsv dispatcher → AggregateSvPileup: dispatches
- fgsv dispatcher → AggregateSvPileupToBedPE: dispatches
- fgsv dispatcher → FilterAndMerge: dispatches
- SvPileup → Tool framework: uses framework
- AggregateSvPileup → Tool framework: uses framework
- AggregateSvPileupToBedPE → Tool framework: uses framework
- FilterAndMerge → Tool framework: uses framework
- SvPileup → Queryname BAM: scans templates
- SvPileup → Aligned segments: builds segments
- SvPileup → Breakpoint evidence: detects evidence
- Breakpoint evidence → Breakpoint model: forms breakpoint
- SvPileup → Breakpoint pileup: collects pileups
- SvPileup → Pileup table: writes candidates
- SvPileup → Tagged BAM: writes tags
- AggregateSvPileup → Pileup table: reads pileups
- AggregateSvPileup → Queryname BAM: queries support
- AggregateSvPileup → Target BED: checks overlap
- AggregateSvPileup → Aggregated pileups: writes aggregates
- AggregateSvPileup → Aggregate-tagged BAM: writes tags
- AggregateSvPileup → Aggregated pileups: produces input
- Aggregated pileups → AggregateSvPileupToBedPE: provides pileups
- AggregateSvPileupToBedPE → BEDPE output: converts to BEDPE
- BEDPE output → Genome browser: viewed in
- FilterAndMerge → Pileup table: reads pileups
- FilterAndMerge → Filtered merged pileups: writes merged sites