# syxscott/paleoast architecture

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

- Interactive diagram: https://gitdiagram.com/syxscott/paleoast
- Repository: https://github.com/syxscott/paleoast

## Overview

PaleoAST is a PyQt6 desktop toolkit for paleontological research. Its principal workflow is to load a dataset, maintain it as application state, run an analysis, and inspect results in the workspace. The README documents broad statistics, ecology, phylogenetics, macroevolution, morphometrics, and stratigraphy capabilities; several are represented at subsystem level because their implementation was not sampled. Edges are limited to relationships visible in excerpts, the source index, or README; unsampled subsystem wiring is intentionally omitted.

Main entry points: [`controllers/statistics_controller.py`](https://github.com/syxscott/paleoast/blob/main/controllers/statistics_controller.py) (Analysis coordination), [`views/ui_main_window.py`](https://github.com/syxscott/paleoast/blob/main/views/ui_main_window.py) (Main workspace), [`controllers/data_controller.py`](https://github.com/syxscott/paleoast/blob/main/controllers/data_controller.py) (Data operations), [`models/state_manager.py`](https://github.com/syxscott/paleoast/blob/main/models/state_manager.py) (Application state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop application"]
  node_entry["Application startup<br/>[main.py]"]
  node_window["Main workspace<br/>[ui_main_window.py]"]
  node_errors["Error handling<br/>[exceptions.py]"]
  node_i18n["Language support<br/>[__init__.py]"]
end

subgraph group_data["Data management"]
  node_state["Application state<br/>[state_manager.py]"]
  node_matrix["Data matrix<br/>[data_matrix.py]"]
  node_data_controller["Data operations<br/>[data_controller.py]"]
  node_csv["CSV I/O<br/>[csv_io.py]"]
  node_drop["File drop parsing"]
  node_tps["TPS parser<br/>[tps_parser.py]"]
end

subgraph group_analysis["Analysis capabilities"]
  node_stats_controller["Analysis coordination"]
  node_stats["Multivariate statistics"]
  node_ecology["Ecology analyses"]
end

subgraph group_phylo["Trees and evolution"]
  node_macroevo["Macroevolution analyses"]
  node_tree["Phylogenetic trees<br/>[tree.py]"]
  node_pcm["Comparative methods<br/>[pcm.py]"]
end

subgraph group_shape["Shape and strata"]
  node_morpho["Morphometrics"]
  node_gpa3d["3D Procrustes<br/>[gpa3d.py]"]
  node_tps3d["3D thin-plate spline<br/>[tps3d.py]"]
  node_strata["Stratigraphy analyses"]
  node_strata_plot["Stratigraphy plots"]
end

node_researcher(("Researcher"))

node_researcher -->|"launches"| node_entry
node_entry -->|"opens"| node_window
node_researcher -->|"uses"| node_window
node_window -->|"invokes"| node_data_controller
node_window -->|"invokes"| node_stats_controller
node_window -->|"reads"| node_state
node_data_controller -->|"updates"| node_state
node_data_controller -->|"creates"| node_matrix
node_data_controller -->|"uses"| node_csv
node_drop -->|"parses"| node_tps
node_stats_controller -->|"reads"| node_state
node_stats_controller -->|"dispatches"| node_stats
node_stats_controller -->|"dispatches"| node_ecology
node_stats_controller -->|"dispatches"| node_morpho
node_stats_controller -->|"dispatches"| node_pcm
node_pcm -->|"uses"| node_tree
node_researcher -->|"runs PCA"| node_stats_controller
node_researcher -->|"uses"| node_ecology
node_researcher -->|"uses"| node_macroevo
node_researcher -->|"uses"| node_tree
node_researcher -->|"uses"| node_morpho
node_researcher -->|"uses"| node_gpa3d
node_researcher -->|"uses"| node_tps3d
node_researcher -->|"uses"| node_strata
node_strata_plot -->|"uses correlation"| node_strata
node_window -->|"uses"| node_i18n
node_data_controller -->|"raises"| node_errors

click node_entry "https://github.com/syxscott/paleoast/blob/main/main.py"
click node_window "https://github.com/syxscott/paleoast/blob/main/views/ui_main_window.py"
click node_state "https://github.com/syxscott/paleoast/blob/main/models/state_manager.py"
click node_matrix "https://github.com/syxscott/paleoast/blob/main/models/data_matrix.py"
click node_data_controller "https://github.com/syxscott/paleoast/blob/main/controllers/data_controller.py"
click node_csv "https://github.com/syxscott/paleoast/blob/main/utils/csv_io.py"
click node_drop "https://github.com/syxscott/paleoast/blob/main/views/file_drop_handler.py"
click node_tps "https://github.com/syxscott/paleoast/blob/main/parsers/tps_parser.py"
click node_stats_controller "https://github.com/syxscott/paleoast/blob/main/controllers/statistics_controller.py"
click node_stats "https://github.com/syxscott/paleoast/tree/main/stats"
click node_ecology "https://github.com/syxscott/paleoast/tree/main/ecology"
click node_macroevo "https://github.com/syxscott/paleoast/tree/main/macroevolution"
click node_tree "https://github.com/syxscott/paleoast/blob/main/phylogenetics/tree.py"
click node_pcm "https://github.com/syxscott/paleoast/blob/main/stats/pcm.py"
click node_morpho "https://github.com/syxscott/paleoast/tree/main/morphometrics"
click node_gpa3d "https://github.com/syxscott/paleoast/blob/main/morpho3d/gpa3d.py"
click node_tps3d "https://github.com/syxscott/paleoast/blob/main/morpho3d/tps3d.py"
click node_strata "https://github.com/syxscott/paleoast/tree/main/stratigraphy"
click node_strata_plot "https://github.com/syxscott/paleoast/blob/main/visualization/stratigraphy_plot.py"
click node_errors "https://github.com/syxscott/paleoast/blob/main/utils/exceptions.py"
click node_i18n "https://github.com/syxscott/paleoast/blob/main/config/i18n/__init__.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_entry,node_window,node_errors,node_i18n toneBlue
class node_state,node_matrix,node_data_controller,node_csv,node_drop,node_tps toneAmber
class node_stats_controller,node_stats,node_ecology toneMint
class node_macroevo,node_tree,node_pcm toneRose
class node_morpho,node_gpa3d,node_tps3d,node_strata,node_strata_plot,node_researcher toneIndigo
```

## Components

### Desktop application

- [Application startup](https://github.com/syxscott/paleoast/blob/main/main.py): `main.py`
- [Main workspace](https://github.com/syxscott/paleoast/blob/main/views/ui_main_window.py): `views/ui_main_window.py`
- [Error handling](https://github.com/syxscott/paleoast/blob/main/utils/exceptions.py): `utils/exceptions.py`
- [Language support](https://github.com/syxscott/paleoast/blob/main/config/i18n/__init__.py): `config/i18n/__init__.py`

### Data management

- [Application state](https://github.com/syxscott/paleoast/blob/main/models/state_manager.py): `models/state_manager.py`
- [Data matrix](https://github.com/syxscott/paleoast/blob/main/models/data_matrix.py): `models/data_matrix.py`
- [Data operations](https://github.com/syxscott/paleoast/blob/main/controllers/data_controller.py): `controllers/data_controller.py`
- [CSV I/O](https://github.com/syxscott/paleoast/blob/main/utils/csv_io.py): `utils/csv_io.py`
- [File drop parsing](https://github.com/syxscott/paleoast/blob/main/views/file_drop_handler.py): `views/file_drop_handler.py`
- [TPS parser](https://github.com/syxscott/paleoast/blob/main/parsers/tps_parser.py): `parsers/tps_parser.py`

### Analysis capabilities

- [Analysis coordination](https://github.com/syxscott/paleoast/blob/main/controllers/statistics_controller.py): `controllers/statistics_controller.py`
- [Multivariate statistics](https://github.com/syxscott/paleoast/tree/main/stats): `stats`
- [Ecology analyses](https://github.com/syxscott/paleoast/tree/main/ecology): `ecology`

### Trees and evolution

- [Macroevolution analyses](https://github.com/syxscott/paleoast/tree/main/macroevolution): `macroevolution`
- [Phylogenetic trees](https://github.com/syxscott/paleoast/blob/main/phylogenetics/tree.py): `phylogenetics/tree.py`
- [Comparative methods](https://github.com/syxscott/paleoast/blob/main/stats/pcm.py): `stats/pcm.py`

### Shape and strata

- [Morphometrics](https://github.com/syxscott/paleoast/tree/main/morphometrics): `morphometrics`
- [3D Procrustes](https://github.com/syxscott/paleoast/blob/main/morpho3d/gpa3d.py): `morpho3d/gpa3d.py`
- [3D thin-plate spline](https://github.com/syxscott/paleoast/blob/main/morpho3d/tps3d.py): `morpho3d/tps3d.py`
- [Stratigraphy analyses](https://github.com/syxscott/paleoast/tree/main/stratigraphy): `stratigraphy`
- [Stratigraphy plots](https://github.com/syxscott/paleoast/blob/main/visualization/stratigraphy_plot.py): `visualization/stratigraphy_plot.py`

### Other components

- **Researcher**

## Connections

- Researcher → Application startup: launches (evidence: `README.md`)
- Application startup → Main workspace: opens (evidence: `main.py`)
- Researcher → Main workspace: uses (evidence: `README.md`)
- Main workspace → Data operations: invokes (evidence: `views/ui_main_window.py`)
- Main workspace → Analysis coordination: invokes (evidence: `views/ui_main_window.py`)
- Main workspace → Application state: reads (evidence: `views/ui_main_window.py`)
- Data operations → Application state: updates (evidence: `controllers/data_controller.py`)
- Data operations → Data matrix: creates (evidence: `controllers/data_controller.py`)
- Data operations → CSV I/O: uses (evidence: `controllers/data_controller.py`)
- File drop parsing → TPS parser: parses (evidence: `views/file_drop_handler.py`)
- Analysis coordination → Application state: reads (evidence: `controllers/statistics_controller.py`)
- Analysis coordination → Multivariate statistics: dispatches (evidence: `controllers/statistics_controller.py`)
- Analysis coordination → Ecology analyses: dispatches (evidence: `controllers/statistics_controller.py`)
- Analysis coordination → Morphometrics: dispatches (evidence: `controllers/statistics_controller.py`)
- Analysis coordination → Comparative methods: dispatches (evidence: `controllers/statistics_controller.py`)
- Comparative methods → Phylogenetic trees: uses (evidence: `stats/pcm.py`)
- Researcher → Analysis coordination: runs PCA (evidence: `README.md`)
- Researcher → Ecology analyses: uses (evidence: `README.md`)
- Researcher → Macroevolution analyses: uses (evidence: `README.md`)
- Researcher → Phylogenetic trees: uses (evidence: `README.md`)
- Researcher → Morphometrics: uses (evidence: `README.md`)
- Researcher → 3D Procrustes: uses (evidence: `README.md`)
- Researcher → 3D thin-plate spline: uses (evidence: `README.md`)
- Researcher → Stratigraphy analyses: uses (evidence: `README.md`)
- Stratigraphy plots → Stratigraphy analyses: uses correlation (evidence: `visualization/stratigraphy_plot.py`)
- Main workspace → Language support: uses (evidence: `views/ui_main_window.py`)
- Data operations → Error handling: raises (evidence: `controllers/data_controller.py`)
