# kojix2/unclone architecture

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

- Interactive diagram: https://gitdiagram.com/kojix2/unclone
- Repository: https://github.com/kojix2/unclone

## Overview

#### Purpose and executable entry point
UnClone is a command-line cancer clonal-analysis tool: a near-parity PyClone-VI-style variational inference mode plus experimental PhyClone-style phylogenetic sampling and trace post-processing. The Crystal executable starts at `src/main.cr`, delegates CLI orchestration through `src/unclone/cli.cr`, and is built as `bin/unclone` by `Makefile`.

#### CLI orchestration and mode dispatch
The Crystal layer owns argument parsing, validation, deterministic seed/control configuration, file paths, and user-facing errors. It dispatches `vi` to the VI kernel path and `phy run/map/consensus/topology-report` to phylogenetic operations.
- `src/unclone/cli.cr`
- `src/unclone/run.cr`
- `src/unclone/config.cr`

#### Input normalization and result boundaries
TSV mutation/sample observations enter Crystal-side parsing and sanitization, where required PyClone-compatible count/copy-number fields and optional purity/error values are validated and normalized. Crystal domain/result objects bridge parsed data to inference and serialize TSV or JSON/JSONL outputs; this is the principal boundary between filesystem formats and numerical/runtime kernels.
- `src/unclone/input.cr`
- `src/unclone/sanitize.cr`
- `src/unclone/output.cr`

#### Rust kernel FFI boundary
Crystal invokes a Rust static/native kernel through bindings and a C ABI. This isolates memory layout, ownership, error/result conversion, and Rust parallel execution from the CLI runtime. The public native interface is represented by the C header and Rust entry points.
- `src/unclone/ffi.cr`
- `rust-kernel/include/pcv_kernel.h`
- `rust-kernel/src/c_api/entrypoints.rs`

#### VI inference pipeline
VI transforms normalized observations into kernel-ready tensors, preprocesses likelihood inputs, then optimizes cluster assignments, mixture weights, and cellular-prevalence grid parameters across restarts. It supports binomial/beta-binomial likelihoods, ELBO-based best-restart selection, optional profiling/debug initialization, and Rayon-controlled kernel threads. Final cluster IDs/results return to Crystal for TSV generation.
- `src/unclone/vi_kernel.cr`
- `rust-kernel/src/core/preprocess.rs`
- `rust-kernel/src/core/inference.rs`

#### Numerical core and parallel runtime
The Rust core centralizes typed inference inputs/results, likelihood evaluation, and numerical primitives used by VI. Rust/Cargo is the compute runtime; Rayon is the material parallelism mechanism indicated by the kernel design, while Crystal can separately control restart-level orchestration.
- `rust-kernel/src/core/types.rs`
- `rust-kernel/src/core/likelihood.rs`
- `rust-kernel/src/core/math.rs`

#### Phylogenetic sampling and trace workflow
Phy mode is a separate Rust compatibility implementation rather than reuse of the VI engine. `phy run` builds tree/data models and performs MCMC/SMC-style proposals and sampling, emitting JSONL traces. Crystal then supports MAP, consensus/clade reconstruction, and topology-support summaries over those traces. Optional cluster TSV metadata informs loss-prior behavior.
- `src/unclone/phyclone.cr`
- `src/unclone/phyclone_kernel.cr`
- `rust-kernel/src/phyclone/compat/smc.rs`

#### Build, compatibility, and research artifacts
Builds combine Crystal with Cargo and expose CPU-target choices for portable versus AVX2/FMA-oriented releases. CI is GitHub Actions. The repository also contains a reproducible benchmark/paper pipeline that runs measurements and generates figures, distinct from the production CLI.
- `Makefile`
- `.github/workflows/build.yml`
- `paper/scripts/benchmark.py`

Main entry points: [`src/unclone/cli.cr`](https://github.com/kojix2/unclone/blob/main/src/unclone/cli.cr) (CLI dispatch), [`src/unclone/phyclone.cr`](https://github.com/kojix2/unclone/blob/main/src/unclone/phyclone.cr) (Phy commands), [`src/unclone/sanitize.cr`](https://github.com/kojix2/unclone/blob/main/src/unclone/sanitize.cr) (Observation sanitization), [`src/unclone/ffi.cr`](https://github.com/kojix2/unclone/blob/main/src/unclone/ffi.cr) (Native FFI bindings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_crystal["Crystal CLI"]
  node_main(("Executable entry<br/>Crystal entrypoint<br/>[main.cr]"))
  node_cli["CLI dispatch<br/>Crystal CLI<br/>[cli.cr]"]
  node_run_config["Run controls<br/>Crystal config<br/>[run.cr]"]
  node_config["Mode configuration<br/>Crystal config<br/>[config.cr]"]
  node_input["Input normalization<br/>TSV parser<br/>[input.cr]"]
  node_sanitize["Observation sanitization<br/>domain validation<br/>[sanitize.cr]"]
  node_output["Result serialization<br/>TSV / JSONL output<br/>[output.cr]"]
  node_ffi{{"Native FFI bindings<br/>Crystal FFI<br/>[ffi.cr]"}}
end

subgraph group_vi["VI kernel"]
  node_c_abi{{"Kernel C ABI<br/>native interface<br/>[pcv_kernel.h]"}}
  node_entrypoints["Rust entrypoints<br/>C ABI implementation<br/>[entrypoints.rs]"]
  node_vi_adapter["VI tensor adapter<br/>Crystal VI bridge<br/>[vi_kernel.cr]"]
  node_preprocess["Likelihood preprocessing<br/>Rust VI stage<br/>[preprocess.rs]"]
  node_inference["VI optimization<br/>Rust inference engine<br/>[inference.rs]"]
  node_numerics["Numerical core<br/>Rust likelihood &amp; math<br/>[likelihood.rs]"]
end

subgraph group_phy["Phy workflow"]
  node_phy_cli["Phy commands<br/>Crystal phy workflow<br/>[phyclone.cr]"]
  node_phy_bridge["Phy kernel bridge<br/>Crystal native bridge<br/>[phyclone_kernel.cr]"]
  node_smc["Phy sampling<br/>Rust SMC / MCMC<br/>[smc.rs]"]
end

subgraph group_delivery["Build &amp; research"]
  node_build["Production build<br/>Make build"]
  node_ci["Build CI<br/>GitHub Actions<br/>[build.yml]"]
  node_benchmark["Benchmark pipeline<br/>research script<br/>[benchmark.py]"]
end

node_main -->|"starts"| node_cli
node_cli -->|"configures"| node_run_config
node_cli -->|"parses mode options"| node_config
node_cli -->|"reads TSV"| node_input
node_input -->|"validates fields"| node_sanitize
node_sanitize -->|"normalized observations"| node_vi_adapter
node_vi_adapter -->|"kernel request"| node_ffi
node_ffi -->|"C ABI"| node_c_abi
node_c_abi -->|"implemented by"| node_entrypoints
node_entrypoints -->|"VI inputs"| node_preprocess
node_preprocess -->|"prepared likelihood data"| node_inference
node_inference -->|"likelihood evaluation"| node_numerics
node_ffi -->|"cluster results"| node_output
node_cli -->|"phy run / map / consensus"| node_phy_cli
node_sanitize -->|"observations and metadata"| node_phy_cli
node_phy_cli -->|"sampling request"| node_phy_bridge
node_phy_bridge -->|"native execution"| node_smc
node_phy_cli -->|"trace reports"| node_output
node_build -->|"builds bin/unclone"| node_main
node_ci -->|"runs"| node_build
node_benchmark -.->|"uses executable"| node_build

click node_main "https://github.com/kojix2/unclone/blob/main/src/main.cr"
click node_cli "https://github.com/kojix2/unclone/blob/main/src/unclone/cli.cr"
click node_run_config "https://github.com/kojix2/unclone/blob/main/src/unclone/run.cr"
click node_config "https://github.com/kojix2/unclone/blob/main/src/unclone/config.cr"
click node_input "https://github.com/kojix2/unclone/blob/main/src/unclone/input.cr"
click node_sanitize "https://github.com/kojix2/unclone/blob/main/src/unclone/sanitize.cr"
click node_output "https://github.com/kojix2/unclone/blob/main/src/unclone/output.cr"
click node_ffi "https://github.com/kojix2/unclone/blob/main/src/unclone/ffi.cr"
click node_c_abi "https://github.com/kojix2/unclone/blob/main/rust-kernel/include/pcv_kernel.h"
click node_entrypoints "https://github.com/kojix2/unclone/blob/main/rust-kernel/src/c_api/entrypoints.rs"
click node_vi_adapter "https://github.com/kojix2/unclone/blob/main/src/unclone/vi_kernel.cr"
click node_preprocess "https://github.com/kojix2/unclone/blob/main/rust-kernel/src/core/preprocess.rs"
click node_inference "https://github.com/kojix2/unclone/blob/main/rust-kernel/src/core/inference.rs"
click node_numerics "https://github.com/kojix2/unclone/blob/main/rust-kernel/src/core/likelihood.rs"
click node_phy_cli "https://github.com/kojix2/unclone/blob/main/src/unclone/phyclone.cr"
click node_phy_bridge "https://github.com/kojix2/unclone/blob/main/src/unclone/phyclone_kernel.cr"
click node_smc "https://github.com/kojix2/unclone/blob/main/rust-kernel/src/phyclone/compat/smc.rs"
click node_build "https://github.com/kojix2/unclone/blob/main/Makefile"
click node_ci "https://github.com/kojix2/unclone/blob/main/.github/workflows/build.yml"
click node_benchmark "https://github.com/kojix2/unclone/blob/main/paper/scripts/benchmark.py"

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_main,node_cli,node_run_config,node_config,node_input,node_sanitize,node_output,node_ffi toneBlue
class node_c_abi,node_entrypoints,node_vi_adapter,node_preprocess,node_inference,node_numerics toneAmber
class node_phy_cli,node_phy_bridge,node_smc toneMint
class node_build,node_ci,node_benchmark toneRose
```

## Components

### Crystal CLI

User-facing orchestration and format boundary.

- [Executable entry](https://github.com/kojix2/unclone/blob/main/src/main.cr): Crystal entrypoint · `src/main.cr`
- [CLI dispatch](https://github.com/kojix2/unclone/blob/main/src/unclone/cli.cr): Crystal CLI · Routes VI and phy commands after validation. · `src/unclone/cli.cr`
- [Run controls](https://github.com/kojix2/unclone/blob/main/src/unclone/run.cr): Crystal config · Seed, paths, and execution controls. · `src/unclone/run.cr`
- [Mode configuration](https://github.com/kojix2/unclone/blob/main/src/unclone/config.cr): Crystal config · `src/unclone/config.cr`
- [Input normalization](https://github.com/kojix2/unclone/blob/main/src/unclone/input.cr): TSV parser · Validates and normalizes mutation observations. · `src/unclone/input.cr`
- [Observation sanitization](https://github.com/kojix2/unclone/blob/main/src/unclone/sanitize.cr): domain validation · `src/unclone/sanitize.cr`
- [Result serialization](https://github.com/kojix2/unclone/blob/main/src/unclone/output.cr): TSV / JSONL output · `src/unclone/output.cr`
- [Native FFI bindings](https://github.com/kojix2/unclone/blob/main/src/unclone/ffi.cr): Crystal FFI · Owns ABI conversion and native error handling. · `src/unclone/ffi.cr`

### VI kernel

Rust variational-inference pipeline.

- [Kernel C ABI](https://github.com/kojix2/unclone/blob/main/rust-kernel/include/pcv_kernel.h): native interface · `rust-kernel/include/pcv_kernel.h`
- [Rust entrypoints](https://github.com/kojix2/unclone/blob/main/rust-kernel/src/c_api/entrypoints.rs): C ABI implementation · `rust-kernel/src/c_api/entrypoints.rs`
- [VI tensor adapter](https://github.com/kojix2/unclone/blob/main/src/unclone/vi_kernel.cr): Crystal VI bridge · Converts normalized observations to kernel inputs. · `src/unclone/vi_kernel.cr`
- [Likelihood preprocessing](https://github.com/kojix2/unclone/blob/main/rust-kernel/src/core/preprocess.rs): Rust VI stage · `rust-kernel/src/core/preprocess.rs`
- [VI optimization](https://github.com/kojix2/unclone/blob/main/rust-kernel/src/core/inference.rs): Rust inference engine · Optimizes assignments, weights, and prevalence grids across restarts. · `rust-kernel/src/core/inference.rs`
- [Numerical core](https://github.com/kojix2/unclone/blob/main/rust-kernel/src/core/likelihood.rs): Rust likelihood & math · Typed inputs, likelihoods, and numerical primitives; uses Rayon parallelism. · `rust-kernel/src/core/likelihood.rs`

### Phy workflow

Separate sampling and trace-analysis path.

- [Phy commands](https://github.com/kojix2/unclone/blob/main/src/unclone/phyclone.cr): Crystal phy workflow · Runs sampling and post-processes JSONL traces. · `src/unclone/phyclone.cr`
- [Phy kernel bridge](https://github.com/kojix2/unclone/blob/main/src/unclone/phyclone_kernel.cr): Crystal native bridge · `src/unclone/phyclone_kernel.cr`
- [Phy sampling](https://github.com/kojix2/unclone/blob/main/rust-kernel/src/phyclone/compat/smc.rs): Rust SMC / MCMC · Builds phylogenetic models, proposes trees, and emits traces. · `rust-kernel/src/phyclone/compat/smc.rs`

### Build & research

- [Production build](https://github.com/kojix2/unclone/blob/main/Makefile): Make build · Combines Crystal and Cargo into bin/unclone with CPU-target variants. · `Makefile`
- [Build CI](https://github.com/kojix2/unclone/blob/main/.github/workflows/build.yml): GitHub Actions · `.github/workflows/build.yml`
- [Benchmark pipeline](https://github.com/kojix2/unclone/blob/main/paper/scripts/benchmark.py): research script · Runs reproducible measurements and figure generation. · `paper/scripts/benchmark.py`

## Connections

- Executable entry → CLI dispatch: starts
- CLI dispatch → Run controls: configures
- CLI dispatch → Mode configuration: parses mode options
- CLI dispatch → Input normalization: reads TSV
- Input normalization → Observation sanitization: validates fields
- Observation sanitization → VI tensor adapter: normalized observations
- VI tensor adapter → Native FFI bindings: kernel request
- Native FFI bindings → Kernel C ABI: C ABI
- Kernel C ABI → Rust entrypoints: implemented by
- Rust entrypoints → Likelihood preprocessing: VI inputs
- Likelihood preprocessing → VI optimization: prepared likelihood data
- VI optimization → Numerical core: likelihood evaluation
- Native FFI bindings → Result serialization: cluster results
- CLI dispatch → Phy commands: phy run / map / consensus
- Observation sanitization → Phy commands: observations and metadata
- Phy commands → Phy kernel bridge: sampling request
- Phy kernel bridge → Phy sampling: native execution
- Phy commands → Result serialization: trace reports
- Production build → Executable entry: builds bin/unclone
- Build CI → Production build: runs
- Benchmark pipeline → Production build: uses executable
