# elias-wahl/atlas-vis architecture

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

- Interactive diagram: https://gitdiagram.com/elias-wahl/atlas-vis
- Repository: https://github.com/elias-wahl/atlas-vis

## Overview

1. **Overall shape**
   - `atlas-vis` is a Python package for atmospheric visualization in local-domain terrain-oriented workflows.
   - The architecture is a pipeline: **configuration → data discovery/parsing → derived physics/transformations → visualization serving**.

2. **Entry point**
   - `src/atlas_vis/main.py` is the top-level entry module that likely wires the package together.
   - It sits above the other subsystems and is the place where runtime startup and orchestration begin.

3. **Configuration boundary**
   - `src/atlas_vis/config/default_settings.yaml` provides package defaults.
   - `src/atlas_vis/core/config.py` likely loads, merges, and validates runtime settings.
   - This is the main control plane for changing behavior without touching the processing or visualization code.

4. **Core discovery and error handling**
   - `src/atlas_vis/core/scanner.py` suggests filesystem or dataset discovery logic, probably identifying available inputs or variables.
   - `src/atlas_vis/core/exceptions.py` centralizes domain-specific failures so parsing, processing, and visualization can fail cleanly and consistently.

5. **Parser subsystem**
   - The `parsers` package is responsible for normalizing external data sources into internal structures.
   - Separate parser implementations exist for **pandas** and **xarray**, which implies support for both tabular and multidimensional scientific data.
   - `base.py`, `registry.py`, `mapper.py`, `aliases.py`, and `util.py` indicate a pluggable parsing layer with variable-name mapping and alias resolution.

6. **Physics / derived-variable subsystem**
   - The `physics` package appears to encapsulate atmospheric formulas and computed diagnostics.
   - `formulas.py` contains the actual physical calculations; `graph.py` suggests dependency tracking between derived quantities.
   - `registry.py` likely registers available physics operations so they can be selected dynamically from configuration or data context.

7. **Processing and execution model**
   - `src/atlas_vis/processing/transformer.py` likely applies transformations from parsed inputs to visualization-ready outputs.
   - `src/atlas_vis/processing/dask_manager.py` indicates optional or integrated parallel/distributed execution via Dask for heavier computations.
   - This layer is the main computation boundary between raw data and interactive presentation.

8. **Visualization subsystem**
   - `src/atlas_vis/visualization/engine.py` is the presentation orchestrator, likely converting processed data into visual outputs.
   - `src/atlas_vis/visualization/trame_server.py` shows that the UI/runtime is built around **Trame**, which is commonly used for interactive scientific visualization apps.
   - This suggests a server-backed interactive visualization model rather than a static plotting script.

9. **Data flow through the system**
   - Input data is discovered by the scanner, interpreted by the appropriate parser, normalized through mapping/alias logic, then enriched by physics formulas and transformers.
   - The processed result is handed to the visualization engine, which serves interactive views through the Trame server.
   - The boundaries are cleanly separated: **I/O and parsing**, **domain computation**, and **presentation**.

10. **Integration and extensibility**
   - Registries in both `parsers` and `physics` imply a plugin-style architecture where supported data formats and derived quantities can be extended without rewriting the pipeline.
   - This makes the system adaptable to different atmospheric datasets and analysis needs while preserving a single orchestration flow.

11. **What to show in an architecture diagram**
   - Draw four main blocks: **config/core**, **parsers**, **physics + processing**, and **visualization**.
   - Show `main.py` as the entry/orchestration point.
   - Represent Dask as an execution accelerator inside processing, and Trame as the interactive serving layer at the output end.

Main entry points: [`src/atlas_vis/main.py`](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/main.py) (Main), [`src/atlas_vis/parsers/registry.py`](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/registry.py) (Parser Registry), [`src/atlas_vis/processing/transformer.py`](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/processing/transformer.py) (Transformer), [`src/atlas_vis/parsers/mapper.py`](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/mapper.py) (Mapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_entry["Entry"]
  node_node_main["Main<br/>entrypoint<br/>[main.py]"]
end

subgraph group_group_core["Core"]
  node_node_default_settings["Defaults<br/>settings"]
  node_node_config["Config<br/>[config.py]"]
  node_node_scanner["Scanner<br/>discovery<br/>[scanner.py]"]
  node_node_exceptions{{"Errors<br/>exception set<br/>[exceptions.py]"}}
end

subgraph group_group_parsers["Parsers"]
  node_node_parser_base["Parser Base<br/>parser framework<br/>[base.py]"]
  node_node_parser_registry["Parser Registry<br/>plugin registry<br/>[registry.py]"]
  node_node_parser_mapper["Mapper<br/>name mapping<br/>[mapper.py]"]
  node_node_parser_aliases["Aliases<br/>alias rules<br/>[aliases.py]"]
  node_node_parser_pandas["Pandas Parser<br/>tabular parser<br/>[pandas.py]"]
  node_node_parser_xarray["Xarray Parser<br/>[xarray.py]"]
  node_node_parser_util["Parser Util<br/>helpers<br/>[util.py]"]
end

subgraph group_group_physics["Physics"]
  node_node_phys_registry["Physics Registry<br/>operation registry<br/>[registry.py]"]
  node_node_phys_formulas["Formulas<br/>[formulas.py]"]
  node_node_phys_graph["Phys Graph<br/>dependency graph<br/>[graph.py]"]
end

subgraph group_group_processing["Processing"]
  node_node_transformer["Transformer<br/>data transform<br/>[transformer.py]"]
  node_node_dask["Dask Manager<br/>execution backend<br/>[dask_manager.py]"]
end

subgraph group_group_viz["Visualization"]
  node_node_viz_engine["Viz Engine<br/>presentation orchestrator<br/>[engine.py]"]
  node_node_trame["Trame Server<br/>interactive server<br/>[trame_server.py]"]
end

node_node_main -->|"loads"| node_node_config
node_node_main -->|"discovers"| node_node_scanner
node_node_main -->|"orchestrates"| node_node_parser_registry
node_node_main -->|"runs"| node_node_transformer
node_node_main -->|"starts"| node_node_viz_engine
node_node_config -->|"defaults"| node_node_default_settings
node_node_config -->|"raises"| node_node_exceptions
node_node_scanner -->|"raises"| node_node_exceptions
node_node_parser_registry -->|"implements"| node_node_parser_base
node_node_parser_registry -->|"selects"| node_node_parser_pandas
node_node_parser_registry -->|"selects"| node_node_parser_xarray
node_node_parser_pandas -->|"maps"| node_node_parser_mapper
node_node_parser_xarray -->|"maps"| node_node_parser_mapper
node_node_parser_mapper -->|"resolves"| node_node_parser_aliases
node_node_parser_mapper -->|"uses"| node_node_parser_util
node_node_transformer -->|"requests"| node_node_phys_registry
node_node_phys_registry -->|"executes"| node_node_phys_formulas
node_node_phys_registry -->|"orders"| node_node_phys_graph
node_node_transformer -->|"accelerates"| node_node_dask
node_node_transformer -->|"raises"| node_node_exceptions
node_node_viz_engine -->|"serves"| node_node_trame

click node_node_main "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/main.py"
click node_node_default_settings "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/config/default_settings.yaml"
click node_node_config "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/core/config.py"
click node_node_scanner "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/core/scanner.py"
click node_node_exceptions "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/core/exceptions.py"
click node_node_parser_base "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/base.py"
click node_node_parser_registry "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/registry.py"
click node_node_parser_mapper "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/mapper.py"
click node_node_parser_aliases "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/aliases.py"
click node_node_parser_pandas "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/pandas.py"
click node_node_parser_xarray "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/xarray.py"
click node_node_parser_util "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/util.py"
click node_node_phys_registry "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/physics/registry.py"
click node_node_phys_formulas "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/physics/formulas.py"
click node_node_phys_graph "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/physics/graph.py"
click node_node_transformer "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/processing/transformer.py"
click node_node_dask "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/processing/dask_manager.py"
click node_node_viz_engine "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/visualization/engine.py"
click node_node_trame "https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/visualization/trame_server.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_node_main toneBlue
class node_node_default_settings,node_node_config,node_node_scanner,node_node_exceptions toneAmber
class node_node_parser_base,node_node_parser_registry,node_node_parser_mapper,node_node_parser_aliases,node_node_parser_pandas,node_node_parser_xarray,node_node_parser_util toneMint
class node_node_phys_registry,node_node_phys_formulas,node_node_phys_graph toneRose
class node_node_transformer,node_node_dask toneIndigo
class node_node_viz_engine,node_node_trame toneTeal
```

## Components

### Entry

Package startup and orchestration

- [Main](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/main.py): entrypoint · Top-level runtime entry that wires the pipeline together · `src/atlas_vis/main.py`

### Core

Configuration, discovery, and shared errors

- [Defaults](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/config/default_settings.yaml): settings · Package default configuration values · `src/atlas_vis/config/default_settings.yaml`
- [Config](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/core/config.py): config loader · Loads, merges, and validates runtime settings · `src/atlas_vis/core/config.py`
- [Scanner](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/core/scanner.py): discovery · Finds inputs, files, or variables in the local domain · `src/atlas_vis/core/scanner.py`
- [Errors](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/core/exceptions.py): exception set · Shared domain-specific failures across the package · `src/atlas_vis/core/exceptions.py`

### Parsers

Input normalization and format adapters

- [Parser Base](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/base.py): parser framework · Common parser interface and shared behavior · `src/atlas_vis/parsers/base.py`
- [Parser Registry](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/registry.py): plugin registry · Selects parser implementations dynamically · `src/atlas_vis/parsers/registry.py`
- [Mapper](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/mapper.py): name mapping · Maps dataset names to internal variables · `src/atlas_vis/parsers/mapper.py`
- [Aliases](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/aliases.py): alias rules · Resolves alternate variable names and synonyms · `src/atlas_vis/parsers/aliases.py`
- [Pandas Parser](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/pandas.py): tabular parser · Parses table-like inputs into internal structures · `src/atlas_vis/parsers/pandas.py`
- [Xarray Parser](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/xarray.py): array parser · Parses multidimensional scientific data inputs · `src/atlas_vis/parsers/xarray.py`
- [Parser Util](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/parsers/util.py): helpers · Shared parsing utilities and normalization helpers · `src/atlas_vis/parsers/util.py`

### Physics

Derived-variable formulas and dependency logic

- [Physics Registry](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/physics/registry.py): operation registry · Registers available derived-variable computations · `src/atlas_vis/physics/registry.py`
- [Formulas](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/physics/formulas.py): physics formulas · Atmospheric calculations and derived diagnostics · `src/atlas_vis/physics/formulas.py`
- [Phys Graph](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/physics/graph.py): dependency graph · Tracks dependencies between derived quantities · `src/atlas_vis/physics/graph.py`

### Processing

Transformation and execution management

- [Transformer](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/processing/transformer.py): data transform · Applies physics and reshaping to prepare outputs · `src/atlas_vis/processing/transformer.py`
- [Dask Manager](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/processing/dask_manager.py): execution backend · Coordinates parallel or distributed computation · `src/atlas_vis/processing/dask_manager.py`

### Visualization

Interactive serving and presentation

- [Viz Engine](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/visualization/engine.py): presentation orchestrator · Builds visualization state from processed data · `src/atlas_vis/visualization/engine.py`
- [Trame Server](https://github.com/elias-wahl/atlas-vis/blob/main/src/atlas_vis/visualization/trame_server.py): interactive server · Serves the interactive visualization runtime · `src/atlas_vis/visualization/trame_server.py`

## Connections

- Main → Config: loads · Startup reads and applies runtime configuration
- Main → Scanner: discovers · Entry point begins dataset discovery
- Main → Parser Registry: orchestrates · Chooses parsing strategy for discovered inputs
- Main → Transformer: runs · Coordinates the main processing pipeline
- Main → Viz Engine: starts · Hands processed results to visualization
- Config → Defaults: defaults · Base settings come from packaged defaults
- Config → Errors: raises · Configuration failures use shared errors
- Scanner → Errors: raises · Discovery issues surface through domain exceptions
- Parser Registry → Parser Base: implements · Registry manages parser implementations
- Parser Registry → Pandas Parser: selects · Pandas adapter is one supported implementation
- Parser Registry → Xarray Parser: selects · Xarray adapter is one supported implementation
- Pandas Parser → Mapper: maps · Tabular parsing uses variable mapping
- Xarray Parser → Mapper: maps · Array parsing uses variable mapping
- Mapper → Aliases: resolves · Mappings are normalized through aliases
- Mapper → Parser Util: uses · Shared parsing helpers support normalization
- Transformer → Physics Registry: requests · Transformation layer selects derived computations
- Physics Registry → Formulas: executes · Registered operations resolve to formulas
- Physics Registry → Phys Graph: orders · Dependencies between derived variables are tracked
- Transformer → Dask Manager: accelerates · Heavy work may be dispatched through Dask
- Transformer → Errors: raises · Processing failures share the common error boundary
- Viz Engine → Trame Server: serves · Visualization output is exposed through Trame