# mountainash-io/mountainash architecture

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

- Interactive diagram: https://gitdiagram.com/mountainash-io/mountainash
- Repository: https://github.com/mountainash-io/mountainash

## Overview

mountainash is a backend-independent semantic layer for tabular data: users build expressions and relational plans, then compile or materialize them on Polars, Narwhals, or Ibis. The main path runs from Python or frame input through relation and expression ASTs, backend selection and visitors, then to a native plan or requested output. The README also describes TypeSpec extraction and conformance and relation DAGs. Evidence is limited to the README, source index references, and excerpts shown; some documented subsystems are represented at directory level.

Main entry points: [`src/mountainash/relations/core/relation_api/relation.py`](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/relations/core/relation_api/relation.py) (Relation API), [`src/mountainash/expressions/core/unified_visitor/visitor.py`](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/expressions/core/unified_visitor/visitor.py) (Expression visitor), [`src/mountainash/relations/core/unified_visitor/relation_visitor.py`](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/relations/core/unified_visitor/relation_visitor.py) (Relation visitor), [`src/mountainash/expressions/core/expression_api/entrypoints.py`](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/expressions/core/expression_api/entrypoints.py) (Expression API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Semantic API"]
  node_expr_api["Expression API<br/>[entrypoints.py]"]
  node_expr_ast["Expression AST<br/>[exn_base.py]"]
end

subgraph group_planning["Plans and schemas"]
  node_relation_api["Relation API<br/>[relation.py]"]
  node_relation_ast["Relation nodes<br/>[reln_base.py]"]
  node_typespec["TypeSpec schemas<br/>[frictionless.py]"]
  node_typespec_extract["Schema extraction<br/>[extraction.py]"]
  node_conform["Schema conformance<br/>[compiler.py]"]
  node_relation_dag["Relation DAG<br/>[dag.py]"]
end

subgraph group_compile["Compilation"]
  node_expr_registry["Function registry<br/>[registry.py]"]
  node_expr_visitor["Expression visitor<br/>[visitor.py]"]
  node_relation_visitor["Relation visitor"]
  node_relation_systems["Relation backends<br/>[__init__.py]"]
  node_expr_systems["Expression backends<br/>[base.py]"]
end

subgraph group_boundary["Data boundaries"]
  node_py_ingress["Python ingress<br/>[pydata_ingress.py]"]
  node_dag_readers["Data readers<br/>[csv.py]"]
  node_egress["Output conversion"]
end

node_user(("Application"))
node_native_result(("Native result"))
node_storage[("Remote storage")]

node_user -->|"builds expressions"| node_expr_api
node_user -->|"builds plans"| node_relation_api
node_relation_api -->|"creates nodes"| node_relation_ast
node_expr_api -->|"creates nodes"| node_expr_ast
node_relation_api -->|"converts input"| node_py_ingress
node_user -->|"extracts schema"| node_typespec_extract
node_typespec_extract -->|"produces schema"| node_typespec
node_relation_api -->|"adds conformance"| node_conform
node_conform -->|"uses schema"| node_typespec
node_relation_api -.->|"integrates DAG"| node_relation_dag
node_relation_ast -->|"walked by"| node_relation_visitor
node_expr_ast -->|"walked by"| node_expr_visitor
node_expr_visitor -->|"resolves functions"| node_expr_registry
node_relation_visitor -->|"compiles expressions"| node_expr_visitor
node_relation_visitor -->|"dispatches operations"| node_relation_systems
node_expr_visitor -->|"lowers expressions"| node_expr_systems
node_relation_systems -->|"returns native plan"| node_native_result
node_user -.->|"loads resources"| node_dag_readers
node_dag_readers -->|"reads remote bytes"| node_storage
node_user -->|"requests output"| node_egress
node_egress -.->|"converts result"| node_native_result

click node_expr_api "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/expressions/core/expression_api/entrypoints.py"
click node_expr_ast "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/expressions/core/expression_nodes/substrait/exn_base.py"
click node_relation_api "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/relations/core/relation_api/relation.py"
click node_relation_ast "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/relations/core/relation_nodes/reln_base.py"
click node_typespec "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/typespec/frictionless.py"
click node_typespec_extract "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/typespec/extraction.py"
click node_conform "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/conform/compiler.py"
click node_relation_dag "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/relations/dag/dag.py"
click node_expr_registry "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/expressions/core/expression_system/function_mapping/registry.py"
click node_expr_visitor "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/expressions/core/unified_visitor/visitor.py"
click node_relation_visitor "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/relations/core/unified_visitor/relation_visitor.py"
click node_relation_systems "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/relations/backends/relation_systems/polars/__init__.py"
click node_expr_systems "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/expressions/backends/expression_systems/base.py"
click node_py_ingress "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/pydata/ingress/pydata_ingress.py"
click node_dag_readers "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/relations/dag/readers/csv.py"
click node_egress "https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/pydata/egress/egress_to_pythondata.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_expr_api,node_expr_ast toneBlue
class node_relation_api,node_relation_ast,node_typespec,node_typespec_extract,node_conform,node_relation_dag,node_storage toneAmber
class node_expr_registry,node_expr_visitor,node_relation_visitor,node_relation_systems,node_expr_systems toneMint
class node_py_ingress,node_dag_readers,node_egress toneRose
class node_user,node_native_result toneIndigo
```

## Components

### Semantic API

- [Expression API](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/expressions/core/expression_api/entrypoints.py): `src/mountainash/expressions/core/expression_api/entrypoints.py`
- [Expression AST](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/expressions/core/expression_nodes/substrait/exn_base.py): `src/mountainash/expressions/core/expression_nodes/substrait/exn_base.py`

### Plans and schemas

- [Relation API](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/relations/core/relation_api/relation.py): `src/mountainash/relations/core/relation_api/relation.py`
- [Relation nodes](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/relations/core/relation_nodes/reln_base.py): `src/mountainash/relations/core/relation_nodes/reln_base.py`
- [TypeSpec schemas](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/typespec/frictionless.py): `src/mountainash/typespec/frictionless.py`
- [Schema extraction](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/typespec/extraction.py): `src/mountainash/typespec/extraction.py`
- [Schema conformance](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/conform/compiler.py): `src/mountainash/conform/compiler.py`
- [Relation DAG](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/relations/dag/dag.py): `src/mountainash/relations/dag/dag.py`

### Compilation

- [Function registry](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/expressions/core/expression_system/function_mapping/registry.py): `src/mountainash/expressions/core/expression_system/function_mapping/registry.py`
- [Expression visitor](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/expressions/core/unified_visitor/visitor.py): `src/mountainash/expressions/core/unified_visitor/visitor.py`
- [Relation visitor](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/relations/core/unified_visitor/relation_visitor.py): `src/mountainash/relations/core/unified_visitor/relation_visitor.py`
- [Relation backends](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/relations/backends/relation_systems/polars/__init__.py): `src/mountainash/relations/backends/relation_systems/polars/__init__.py`
- [Expression backends](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/expressions/backends/expression_systems/base.py): `src/mountainash/expressions/backends/expression_systems/base.py`

### Data boundaries

- [Python ingress](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/pydata/ingress/pydata_ingress.py): `src/mountainash/pydata/ingress/pydata_ingress.py`
- [Data readers](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/relations/dag/readers/csv.py): `src/mountainash/relations/dag/readers/csv.py`
- [Output conversion](https://github.com/mountainash-io/mountainash/blob/main/src/mountainash/pydata/egress/egress_to_pythondata.py): `src/mountainash/pydata/egress/egress_to_pythondata.py`

### Other components

- **Application**
- **Native result**
- **Remote storage**

## Connections

- Application → Expression API: builds expressions (evidence: `README.md`)
- Application → Relation API: builds plans (evidence: `README.md`)
- Relation API → Relation nodes: creates nodes (evidence: `src/mountainash/relations/core/relation_api/relation.py`)
- Expression API → Expression AST: creates nodes (evidence: `src/mountainash/expressions/core/expression_api/entrypoints.py`)
- Relation API → Python ingress: converts input (evidence: `src/mountainash/relations/core/relation_api/relation.py`)
- Application → Schema extraction: extracts schema (evidence: `README.md`)
- Schema extraction → TypeSpec schemas: produces schema (evidence: `src/mountainash/typespec/extraction.py`)
- Relation API → Schema conformance: adds conformance (evidence: `README.md`)
- Schema conformance → TypeSpec schemas: uses schema
- Relation API → Relation DAG: integrates DAG (evidence: `src/mountainash/relations/dag/dag.py`)
- Relation nodes → Relation visitor: walked by (evidence: `src/mountainash/relations/core/unified_visitor/relation_visitor.py`)
- Expression AST → Expression visitor: walked by
- Expression visitor → Function registry: resolves functions (evidence: `src/mountainash/expressions/core/unified_visitor/visitor.py`)
- Relation visitor → Expression visitor: compiles expressions (evidence: `src/mountainash/relations/core/unified_visitor/relation_visitor.py`)
- Relation visitor → Relation backends: dispatches operations (evidence: `src/mountainash/relations/core/unified_visitor/relation_visitor.py`)
- Expression visitor → Expression backends: lowers expressions (evidence: `README.md`)
- Relation backends → Native result: returns native plan (evidence: `README.md`)
- Application → Data readers: loads resources
- Data readers → Remote storage: reads remote bytes
- Application → Output conversion: requests output (evidence: `README.md`)
- Output conversion → Native result: converts result
