@page code_review_map Code Review Map

# Quadrix Source Code Review Map

**Total**: ~52,500 lines across 70+ source files

## Library: `src/`

### Layer 1: Core Geometry (`src/geometry/`) ~1,830 lines

*Foundational spatial types everything else builds on.*

| # | File | Lines | What it does |
|---|---|---|---|
| 1 | `src/geometry/vector3d.rs` | 90 | 3D vector type and operations |
| 2 | `src/geometry/vertex.rs` | 973 | Vertex struct (3D point in a dendritic tree, path distances, parent/child relationships) |
| 3 | `src/geometry/edges.rs` | 764 | Edge struct (vertex pairs, quadric matrix computation per edge) |

### Layer 2: Morphology (`src/morphology/`) ~4,300 lines

*Neuron data structures and file I/O.*

| # | File | Lines | What it does |
|---|---|---|---|
| 4 | `src/morphology/dendrite.rs` | 1,538 | Dendrite struct -- tree of vertices/edges, aggregate quadric computation |
| 5 | `src/morphology/neuron.rs` | 1,157 | Neuron struct -- collection of dendrites, multi-compartment support |
| 6 | `src/morphology/swc.rs` | 936 | SWC file parser (neuronal morphology format) |
| 7 | `src/morphology/formats.rs` | 672 | CSV, ASC, and other export formats |

### Layer 3: Analysis (`src/analysis/`) ~6,600 lines

*Computational algorithms for morphology analysis.*

| # | File | Lines | What it does |
|---|---|---|---|
| 8 | `src/analysis/eigenvalues.rs` | 670 | Eigenvalue/eigenvector computation from quadric matrices |
| 9 | `src/analysis/persistence.rs` | 1,396 | Persistent homology -- topological data analysis of dendrites |
| 10 | `src/analysis/persistent_quadric.rs` | 425 | Persistent quadric -- filtration-based quadric analysis |
| 11 | `src/analysis/morphometrics.rs` | 1,072 | Classical morphometrics (Sholl, L-Measure, Strahler, tortuosity) |
| 12 | `src/analysis/features.rs` | 998 | ML feature extraction for clustering and comparison |
| 13 | `src/analysis/simplification.rs` | 1,292 | Edge contraction simplification algorithm |
| 14 | `src/analysis/validation.rs` | 755 | Data validation and integrity checks |

### Layer 4: Visualization (`src/viz/`) ~4,500 lines

*Plotting and visual output.*

| # | File | Lines | What it does |
|---|---|---|---|
| 15 | `src/viz/hexplot.rs` | 2,237 | Hexagonal eigenvalue distribution plots (NormPolar transform) |
| 16 | `src/viz/visualization.rs` | 984 | Dendrograms, branch coloring, neuron comparison |
| 17 | `src/viz/persistence_viz.rs` | 741 | Persistence diagram visualization and topological distances |
| 18 | `src/viz/plotting.rs` | 521 | Interactive 3D plotting (plotly, requires "interactive" feature) |

### Layer 5: Population Comparison (`src/population_comparison/`) ~2,370 lines

*Statistical methods for comparing neuron populations.*

| # | File | Lines | What it does |
|---|---|---|---|
| 19 | `src/population_comparison/mod.rs` | 577 | Module orchestration, shared types |
| 20 | `src/population_comparison/dissimilarity.rs` | 537 | Dissimilarity matrix computation between neurons |
| 21 | `src/population_comparison/mds.rs` | 343 | Multidimensional scaling (MDS) for dimensionality reduction |
| 22 | `src/population_comparison/hca.rs` | 493 | Hierarchical cluster analysis (dendrograms) |
| 23 | `src/population_comparison/ellipsoid.rs` | 416 | Ellipsoid-based population comparison metrics |

### Layer 6: Database (`src/database/`) ~2,470 lines

*SQLite persistence layer.*

| # | File | Lines | What it does |
|---|---|---|---|
| 24 | `src/database/mod.rs` | 494 | Database module setup, connection management |
| 25 | `src/database/models.rs` | 881 | ORM-style model structs |
| 26 | `src/database/repository.rs` | 1,093 | CRUD operations, queries |

### Other Library Files

| # | File | Lines | What it does |
|---|---|---|---|
| 27 | `src/lib.rs` | 685 | Library root -- re-exports, module declarations, Python bindings |
| 28 | `src/swc_batch.rs` | 1,317 | Batch processing of SWC directories (requires "database" feature) |

---

## Desktop App: `src/bin/desktop/` ~8,200 lines

*Tauri desktop application backend, split into focused modules.*

| # | File | Lines | What it does |
|---|---|---|---|
| 29 | `main.rs` | 189 | Entry point, module declarations, Tauri builder, handler registration |
| 30 | `state.rs` | 134 | Shared state structs: DirectoryState, CancellationState, LoadedFile, ImportBatch |
| 31 | `path_utils.rs` | 88 | Cross-platform path normalization and resolution |
| 32 | `directory.rs` | 274 | Directory loading/unloading, file listing |
| 33 | `batch_import.rs` | 948 | Batch import workflow, metadata extraction, file import to DB |
| 34 | `merge.rs` | 216 | Database merge scan and execution |
| 35 | `file_dialog.rs` | 694 | File/directory dialogs, plot generation, SWC analysis |
| 36 | `structure.rs` | 739 | SWC structure loading, intersections, eigenvalues, persistence |
| 37 | `hexplot.rs` | 1,044 | Directory/DB hexplot generation, box plots, PQ curves |
| 38 | `database.rs` | 1,764 | DatabaseState, neuron CRUD, open/close/create/save DB |
| 39 | `analysis.rs` | 886 | Sholl, L-Measure, tortuosity, dendrogram, comparison, CSV export |
| 40 | `persistence_db.rs` | 181 | Persistence diagram retrieval from database |
| 41 | `metadata_fields.rs` | 287 | Metadata field definitions CRUD |
| 42 | `population.rs` | 768 | Population dissimilarity, MDS, HCA, ellipsoid comparison |

---

## Other Binaries: `src/bin/`

| # | File | Lines | What it does |
|---|---|---|---|
| 43 | `src/bin/test_report.rs` | 1,407 | Integration test report generator |
| 44 | `src/bin/web_gui.rs` | 1,524 | Web GUI server (legacy) |
| 45 | `src/bin/hexplot.rs` | 507 | CLI hexplot generator |
| 46 | `src/bin/hexplot_interactive.rs` | 616 | Interactive HTML hexplot |
| 47 | `src/bin/database_cli.rs` | 191 | Database management CLI |
| 48 | `src/bin/dendrite_plot.rs` | 118 | Simple dendrite plotter |
| 49 | `src/bin/dendrite_server.rs` | 95 | Dendrite web server launcher |
| 50 | `src/bin/process_swc_directory.rs` | 74 | Batch SWC directory processor |
| 51 | `src/bin/swc_info.rs` | 83 | SWC file info tool |

---

## Web Backend (Legacy): `src/web/` ~6,500 lines

| # | File | Lines | What it does |
|---|---|---|---|
| 52 | `src/web/mod.rs` | 335 | Web module setup |
| 53 | `src/web/api.rs` | 72 | API route definitions |
| 54 | `src/web/handlers.rs` | 5,481 | Request handlers |
| 55 | `src/web/state.rs` | 266 | Shared web app state |
| 56 | `src/web/websocket.rs` | 301 | WebSocket support |

---

## Frontend UI: `ui/` ~17,900 lines

*Tauri frontend, split into ES modules.*

### Entry Point

| # | File | Lines | What it does |
|---|---|---|---|
| 57 | `ui/main.js` | 950 | Module imports, DOMContentLoaded wiring, single-file analysis |

### Modules (`ui/modules/`)

| # | File | Lines | What it does |
|---|---|---|---|
| 58 | `modules/state.js` | 140 | Centralized app state, Tauri detection, invoke/listen wrappers |
| 59 | `modules/utils.js` | 87 | Notifications, path helpers, escapeHtml, SVG utilities |
| 60 | `modules/navigation.js` | 108 | Page/view switching, sidebar navigation |
| 61 | `modules/file-selection.js` | 325 | File/database dropdowns, directory loader |
| 62 | `modules/viewer-3d.js` | 632 | 3D structure loader, compartment render, subtree analysis |
| 63 | `modules/data-explorer.js` | 598 | Data explorer panel, eigenvalues, persistence, vertex table |
| 64 | `modules/database.js` | 627 | Database CRUD, neuron list, import/export |
| 65 | `modules/hexplot.js` | 764 | Hexplot generation and export |
| 66 | `modules/hex-boxplot.js` | 701 | Hex box plot with persistent quadric overlay |
| 67 | `modules/neuroscience.js` | 1,475 | Sholl, L-measure, tortuosity, batch analysis, dendrogram |
| 68 | `modules/population.js` | 1,073 | Population comparison, MDS, HCA, dissimilarity matrix |
| 69 | `modules/workspace.js` | 2,234 | Unified workspace: directory loading, DB management, imports |
| 70 | `modules/pq-viewer.js` | 846 | Persistent quadric trajectory viewer |
| 71 | `modules/settings.js` | 401 | Metadata field CRUD for Settings panel |

### Other Frontend Files

| # | File | Lines | What it does |
|---|---|---|---|
| 72 | `ui/index.html` | 2,896 | Main HTML shell (sidebar, views, modals) |
| 73 | `ui/styles.css` | 3,449 | All styling |
| 74 | `ui/three-viewer.js` | 868 | Three.js 3D neuron viewer (communicates via custom events) |
| 75 | `ui/web_gui_index.html` | 1,105 | Web GUI HTML (legacy) |

---

## Build & Config

| File | What it does |
|---|---|
| `Cargo.toml` | Rust dependencies and feature flags |
| `build.rs` | Build script |
| `tauri.conf.json` | Tauri desktop app configuration |
| `justfile` | Build commands (`just build`, `just dev`, etc.) |
| `Doxyfile` | Doxygen documentation config |

## Suggested Review Order

**Bottom-up approach** (understand foundations first):

1. **Core types**: `geometry/vector3d.rs` -> `geometry/vertex.rs` -> `geometry/edges.rs`
2. **Structures**: `morphology/dendrite.rs` -> `morphology/neuron.rs` -> `morphology/swc.rs`
3. **Analysis**: `analysis/eigenvalues.rs` -> `analysis/persistence.rs` -> `analysis/morphometrics.rs`
4. **Population**: `population_comparison/`
5. **Visualization**: `viz/hexplot.rs` -> `viz/visualization.rs`
6. **Desktop app**: `bin/desktop/main.rs` -> `database.rs` -> `structure.rs` -> remaining modules
7. **Frontend**: `ui/modules/state.js` -> `navigation.js` -> `main.js` -> remaining modules

## Architecture Notes

- The library (`src/`) is organized into four groups: `geometry/`, `morphology/`, `analysis/`, `viz/`
- Public API is preserved via `pub use` re-exports in `lib.rs` (e.g. `quadrix::vertex` still works)
- The desktop backend (`src/bin/desktop/`) uses `pub(crate)` visibility for cross-module access
- The frontend uses ES modules with `import`/`export` syntax (no bundler required)
- `state.js` is the leaf dependency -- imported by all other JS modules
- The codebase follows a layered architecture: geometry -> morphology -> analysis -> viz -> app
