# creatorzzy/chromosomal_structure_tools architecture

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

- Interactive diagram: https://gitdiagram.com/creatorzzy/chromosomal_structure_tools
- Repository: https://github.com/creatorzzy/chromosomal_structure_tools

## Overview

Chromosomal Structure Tools is a browser-based Hi-C reconstruction and 3D viewing app, with Deno command-line tools for matrix and coordinate exports. The main web workflow accepts a contact file, runs shared ShRec3D computation in a Web Worker, then displays and exports the resulting chromosome model. The stages and shared-core calls are documented in the README and sampled source; UI event wiring and some export handling are only partially sampled, so those links are kept at the supported module level.

Main entry points: [`src/main.js`](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/main.js) (UI controller), [`src/cli/fullsize-matrix.mjs`](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/cli/fullsize-matrix.mjs) (Matrix CLI), [`src/cli/coordinates.mjs`](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/cli/coordinates.mjs) (Coordinates CLI), [`src/worker.mjs`](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/worker.mjs) (Compute worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_page["App page<br/>[index.html]"]
  node_controller["UI controller<br/>[main.js]"]
  node_worker["Compute worker<br/>[worker.mjs]"]
  node_display["Display controls<br/>[main.js]"]
  node_guidance["Help and tour<br/>[main.js]"]
end

subgraph group_compute["Reconstruction core"]
  node_sparse["Parse contacts<br/>[core.mjs]"]
  node_matrix["Build matrix<br/>[core.mjs]"]
  node_distances["Contact distances<br/>[core.mjs]"]
  node_mds["3D coordinates<br/>[core.mjs]"]
  node_smooth["Curve smoothing<br/>[core.mjs]"]
  node_serialize["CSV serialization<br/>[core.mjs]"]
end

subgraph group_cli["Deno command line"]
  node_matrixcli["Matrix CLI"]
  node_coordscli["Coordinates CLI<br/>[coordinates.mjs]"]
end

subgraph group_view["3D viewing"]
  node_viewer["Structure viewer<br/>[viewer.js]"]
  node_exports["Image/video export<br/>[viewer.js]"]
end

node_person(("User"))
node_files["Input/output files"]

node_person -->|"opens"| node_page
node_person -->|"selects data"| node_controller
node_page -->|"hosts UI"| node_controller
node_controller -->|"sends text"| node_worker
node_worker -->|"runs pipeline"| node_sparse
node_sparse -->|"parsed contacts"| node_matrix
node_matrix -->|"contact matrix"| node_distances
node_distances -->|"distance matrix"| node_mds
node_mds -->|"coordinates"| node_worker
node_matrix -->|"matrix data"| node_serialize
node_mds -->|"coordinates"| node_serialize
node_serialize -->|"CSV strings"| node_worker
node_worker -->|"results and progress"| node_controller
node_controller -->|"sets structure"| node_viewer
node_viewer -->|"smooths coordinates"| node_smooth
node_controller -->|"updates options"| node_display
node_display -->|"applies settings"| node_viewer
node_controller -->|"requests export"| node_exports
node_exports -->|"image or video"| node_controller
node_controller -->|"opens help or tour"| node_guidance
node_person -->|"runs command"| node_matrixcli
node_person -->|"runs command"| node_coordscli
node_files -->|"sparse matrix"| node_matrixcli
node_matrixcli -->|"parses contacts"| node_sparse
node_matrixcli -->|"builds full matrix"| node_matrix
node_matrixcli -->|"formats CSV"| node_serialize
node_matrixcli -->|"writes matrix CSV"| node_files
node_files -->|"matrix CSV"| node_coordscli
node_coordscli -->|"computes distances"| node_distances
node_coordscli -->|"computes coordinates"| node_mds
node_coordscli -->|"formats coordinates"| node_serialize
node_coordscli -->|"writes coordinates CSV"| node_files

click node_page "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/index.html"
click node_controller "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/main.js"
click node_worker "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/worker.mjs"
click node_sparse "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/core.mjs"
click node_matrix "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/core.mjs"
click node_distances "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/core.mjs"
click node_mds "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/core.mjs"
click node_smooth "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/core.mjs"
click node_serialize "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/core.mjs"
click node_viewer "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/viewer.js"
click node_exports "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/viewer.js"
click node_display "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/main.js"
click node_guidance "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/main.js"
click node_matrixcli "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/cli/fullsize-matrix.mjs"
click node_coordscli "https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/cli/coordinates.mjs"

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_page,node_controller,node_worker,node_display,node_guidance,node_person toneBlue
class node_sparse,node_matrix,node_distances,node_mds,node_smooth,node_serialize toneAmber
class node_matrixcli,node_coordscli toneMint
class node_viewer,node_exports toneRose
class node_files toneIndigo
```

## Components

### Web application

- [App page](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/index.html): `index.html`
- [UI controller](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/main.js): `src/main.js`
- [Compute worker](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/worker.mjs): `src/worker.mjs`
- [Display controls](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/main.js): `src/main.js`
- [Help and tour](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/main.js): `src/main.js`

### Reconstruction core

- [Parse contacts](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/core.mjs): `src/core.mjs`
- [Build matrix](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/core.mjs): `src/core.mjs`
- [Contact distances](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/core.mjs): `src/core.mjs`
- [3D coordinates](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/core.mjs): `src/core.mjs`
- [Curve smoothing](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/core.mjs): `src/core.mjs`
- [CSV serialization](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/core.mjs): `src/core.mjs`

### Deno command line

- [Matrix CLI](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/cli/fullsize-matrix.mjs): `src/cli/fullsize-matrix.mjs`
- [Coordinates CLI](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/cli/coordinates.mjs): `src/cli/coordinates.mjs`

### 3D viewing

- [Structure viewer](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/viewer.js): `src/viewer.js`
- [Image/video export](https://github.com/creatorzzy/chromosomal_structure_tools/blob/pure-frontend/src/viewer.js): `src/viewer.js`

### Other components

- **User**
- **Input/output files**

## Connections

- User → App page: opens
- User → UI controller: selects data
- App page → UI controller: hosts UI
- UI controller → Compute worker: sends text
- Compute worker → Parse contacts: runs pipeline
- Parse contacts → Build matrix: parsed contacts
- Build matrix → Contact distances: contact matrix
- Contact distances → 3D coordinates: distance matrix
- 3D coordinates → Compute worker: coordinates
- Build matrix → CSV serialization: matrix data
- 3D coordinates → CSV serialization: coordinates
- CSV serialization → Compute worker: CSV strings
- Compute worker → UI controller: results and progress
- UI controller → Structure viewer: sets structure
- Structure viewer → Curve smoothing: smooths coordinates
- UI controller → Display controls: updates options
- Display controls → Structure viewer: applies settings
- UI controller → Image/video export: requests export
- Image/video export → UI controller: image or video
- UI controller → Help and tour: opens help or tour
- User → Matrix CLI: runs command
- User → Coordinates CLI: runs command
- Input/output files → Matrix CLI: sparse matrix
- Matrix CLI → Parse contacts: parses contacts
- Matrix CLI → Build matrix: builds full matrix
- Matrix CLI → CSV serialization: formats CSV
- Matrix CLI → Input/output files: writes matrix CSV
- Input/output files → Coordinates CLI: matrix CSV
- Coordinates CLI → Contact distances: computes distances
- Coordinates CLI → 3D coordinates: computes coordinates
- Coordinates CLI → CSV serialization: formats coordinates
- Coordinates CLI → Input/output files: writes coordinates CSV