# twilightsail/conservatory architecture

> Architecture diagram of the GitHub repository twilightsail/conservatory, 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/twilightsail/conservatory
- Repository: https://github.com/twilightsail/conservatory

## Overview

Conservatory identifies conserved non-coding sequences across related and distant genomes. Users prepare genome data, a genome database, family trees, and neutral models; they then build databases for a reference and run conservation per gene. The documented analysis uses regulatory-sequence alignments and orthology to reconstruct ancestral CNS sequences and search syntenic regions. Results can be merged within a reference and across references. The README describes these capabilities, but no source excerpts were supplied, so internal call wiring beyond documented commands is not inferred.

Main entry points: [`scripts/buildConservation`](https://github.com/twilightsail/conservatory/blob/master/scripts/buildConservation) (Build conservation), [`processGenomes`](https://github.com/twilightsail/conservatory/blob/master/processGenomes) (Process genomes), [`scripts/mergeCNS`](https://github.com/twilightsail/conservatory/blob/master/scripts/mergeCNS) (Merge CNS), [`genomes`](https://github.com/twilightsail/conservatory/tree/master/genomes) (Family trees)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Reference data"]
  node_genome_files["Genome files"]
  node_genome_catalog["Genome catalog"]
  node_family_tree["Family trees"]
  node_neutral_model["Neutral models"]
end

subgraph group_preparation["Genome preparation"]
  node_process_genomes["Process genomes"]
  node_ortholog_db["Orthology database"]
  node_regulatory_db["Regulatory sequence DB"]
end

subgraph group_analysis["CNS analysis"]
  node_build_conservation["Build conservation"]
  node_family_alignment["Family alignments"]
  node_mapping["Synteny mapping<br/>[Mapping.pm]"]
  node_tree_model["Tree and model"]
  node_ancestral["Ancestral reconstruction"]
end

subgraph group_results["CNS results"]
  node_cns_results["Per-gene CNS"]
  node_merge_cns["Merge CNS"]
  node_consensus["Multi-reference consensus"]
end

node_user(("Researcher"))

node_user -->|"runs setup"| node_process_genomes
node_genome_files -->|"provides genomes"| node_process_genomes
node_genome_catalog -->|"configures genomes"| node_process_genomes
node_process_genomes -->|"builds orthology"| node_ortholog_db
node_process_genomes -->|"builds sequence DB"| node_regulatory_db
node_user -->|"runs per gene"| node_build_conservation
node_ortholog_db -->|"supplies orthology"| node_build_conservation
node_regulatory_db -->|"supplies sequences"| node_build_conservation
node_family_tree -->|"provides tree"| node_tree_model
node_neutral_model -->|"sets conservation model"| node_build_conservation
node_family_tree -->|"guides comparisons"| node_build_conservation
node_build_conservation -->|"produces alignments"| node_family_alignment
node_build_conservation -->|"uses synteny mapping"| node_mapping
node_build_conservation -->|"reconstructs CNS"| node_ancestral
node_ancestral -->|"writes CNS"| node_cns_results
node_user -->|"requests merge"| node_merge_cns
node_cns_results -->|"provides per-gene CNS"| node_merge_cns
node_merge_cns -->|"combines references"| node_consensus

click node_genome_files "https://github.com/twilightsail/conservatory/tree/master/genomes"
click node_genome_catalog "https://github.com/twilightsail/conservatory/blob/master/genome_database.csv"
click node_family_tree "https://github.com/twilightsail/conservatory/tree/master/genomes"
click node_neutral_model "https://github.com/twilightsail/conservatory/tree/master/genomes"
click node_process_genomes "https://github.com/twilightsail/conservatory/blob/master/processGenomes"
click node_ortholog_db "https://github.com/twilightsail/conservatory/blob/master/scripts/buildOrthologDB"
click node_regulatory_db "https://github.com/twilightsail/conservatory/blob/master/scripts/buildRegulatorySeqDB"
click node_build_conservation "https://github.com/twilightsail/conservatory/blob/master/scripts/buildConservation"
click node_family_alignment "https://github.com/twilightsail/conservatory/tree/master/alignments"
click node_mapping "https://github.com/twilightsail/conservatory/blob/master/scripts/Mapping.pm"
click node_tree_model "https://github.com/twilightsail/conservatory/blob/master/scripts/buildModel"
click node_ancestral "https://github.com/twilightsail/conservatory/blob/master/scripts/reconstructCNSSequences"
click node_cns_results "https://github.com/twilightsail/conservatory/tree/master/CNS"
click node_merge_cns "https://github.com/twilightsail/conservatory/blob/master/scripts/mergeCNS"
click node_consensus "https://github.com/twilightsail/conservatory/blob/master/scripts/mergeCNS"

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_genome_files,node_genome_catalog,node_family_tree,node_neutral_model toneBlue
class node_process_genomes,node_ortholog_db,node_regulatory_db toneAmber
class node_build_conservation,node_family_alignment,node_mapping,node_tree_model,node_ancestral toneMint
class node_cns_results,node_merge_cns,node_consensus toneRose
class node_user toneIndigo
```

## Components

### Reference data

- [Genome files](https://github.com/twilightsail/conservatory/tree/master/genomes): `genomes`
- [Genome catalog](https://github.com/twilightsail/conservatory/blob/master/genome_database.csv): `genome_database.csv`
- [Family trees](https://github.com/twilightsail/conservatory/tree/master/genomes): `genomes`
- [Neutral models](https://github.com/twilightsail/conservatory/tree/master/genomes): `genomes`

### Genome preparation

- [Process genomes](https://github.com/twilightsail/conservatory/blob/master/processGenomes): `processGenomes`
- [Orthology database](https://github.com/twilightsail/conservatory/blob/master/scripts/buildOrthologDB): `scripts/buildOrthologDB`
- [Regulatory sequence DB](https://github.com/twilightsail/conservatory/blob/master/scripts/buildRegulatorySeqDB): `scripts/buildRegulatorySeqDB`

### CNS analysis

- [Build conservation](https://github.com/twilightsail/conservatory/blob/master/scripts/buildConservation): `scripts/buildConservation`
- [Family alignments](https://github.com/twilightsail/conservatory/tree/master/alignments): `alignments`
- [Synteny mapping](https://github.com/twilightsail/conservatory/blob/master/scripts/Mapping.pm): `scripts/Mapping.pm`
- [Tree and model](https://github.com/twilightsail/conservatory/blob/master/scripts/buildModel): `scripts/buildModel`
- [Ancestral reconstruction](https://github.com/twilightsail/conservatory/blob/master/scripts/reconstructCNSSequences): `scripts/reconstructCNSSequences`

### CNS results

- [Per-gene CNS](https://github.com/twilightsail/conservatory/tree/master/CNS): `CNS`
- [Merge CNS](https://github.com/twilightsail/conservatory/blob/master/scripts/mergeCNS): `scripts/mergeCNS`
- [Multi-reference consensus](https://github.com/twilightsail/conservatory/blob/master/scripts/mergeCNS): `scripts/mergeCNS`

### Other components

- **Researcher**

## Connections

- Researcher → Process genomes: runs setup
- Genome files → Process genomes: provides genomes
- Genome catalog → Process genomes: configures genomes
- Process genomes → Orthology database: builds orthology
- Process genomes → Regulatory sequence DB: builds sequence DB
- Researcher → Build conservation: runs per gene
- Orthology database → Build conservation: supplies orthology
- Regulatory sequence DB → Build conservation: supplies sequences
- Family trees → Tree and model: provides tree
- Neutral models → Build conservation: sets conservation model
- Family trees → Build conservation: guides comparisons
- Build conservation → Family alignments: produces alignments
- Build conservation → Synteny mapping: uses synteny mapping
- Build conservation → Ancestral reconstruction: reconstructs CNS
- Ancestral reconstruction → Per-gene CNS: writes CNS
- Researcher → Merge CNS: requests merge
- Per-gene CNS → Merge CNS: provides per-gene CNS
- Merge CNS → Multi-reference consensus: combines references