# mountainash-io/mountainash-data architecture

> Architecture diagram of the GitHub repository mountainash-io/mountainash-data, 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-data
- Repository: https://github.com/mountainash-io/mountainash-data

## Overview

mountainash-data is a Python physical-access library for relational databases through Ibis and Iceberg catalogs through PyIceberg. The principal workflow configures a backend, opens a connection, then executes operations or inspects physical metadata; connections can also expose relational expressions. The README documents the facade and factory-driven settings flow. Source excerpts show key backend dispatch and Iceberg connection behavior, but several factories and backend modules were not sampled, so uncertain internal links are omitted.

Main entry points: [`src/mountainash_data/backends/iceberg/connection.py`](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/iceberg/connection.py) (Iceberg connection), [`src/mountainash_data/backends/ibis/backend.py`](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/ibis/backend.py) (Ibis backend), [`src/mountainash_data/backends/ibis/connection.py`](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/ibis/connection.py) (Ibis connection), [`src/mountainash_data/backends/iceberg/backend.py`](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/iceberg/backend.py) (Iceberg backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public access"]
  node_utils["DatabaseUtils<br/>[utils.py]"]
  node_conn_factory["Connection factory"]
end

subgraph group_config["Configuration"]
  node_settings_factory["Settings factory"]
  node_backend_settings["Backend settings"]
  node_settings_registry["Settings registry<br/>[registry.py]"]
end

subgraph group_ibis["Ibis backends"]
  node_ibis_backend["Ibis backend<br/>[backend.py]"]
  node_ibis_dialects["Dialect registry<br/>[_registry.py]"]
  node_ibis_connection["Ibis connection<br/>[connection.py]"]
  node_ibis_operations["Ibis operations<br/>[operations.py]"]
  node_ibis_inspection["Ibis inspection<br/>[inspect.py]"]
end

subgraph group_iceberg["Iceberg backends"]
  node_iceberg_backend["Iceberg backend<br/>[backend.py]"]
  node_rest_catalog["REST catalog<br/>[rest.py]"]
  node_iceberg_connection["Iceberg connection<br/>[connection.py]"]
  node_iceberg_operations["Iceberg operations<br/>[operations.py]"]
  node_iceberg_inspection["Iceberg inspection<br/>[inspect.py]"]
end

subgraph group_model["Shared contracts"]
  node_connection_base["Connection base<br/>[connection.py]"]
  node_contracts["Backend contracts<br/>[protocol.py]"]
  node_metadata["Inspection metadata<br/>[inspection.py]"]
end

node_developer(("Library user"))
node_data_service[("Data service or catalog")]
node_expressions(("Expressions consumer"))

node_developer -->|"creates connection"| node_utils
node_utils -.->|"delegates to"| node_conn_factory
node_settings_factory -->|"builds profiles"| node_backend_settings
node_backend_settings -->|"registers profiles"| node_settings_registry
node_developer -->|"selects settings"| node_settings_factory
node_conn_factory -.->|"selects backend"| node_ibis_backend
node_ibis_backend -->|"uses registry"| node_ibis_dialects
node_ibis_backend -->|"uses helpers"| node_ibis_inspection
node_ibis_connection -->|"extends base"| node_connection_base
node_ibis_connection -.->|"delegates operations"| node_ibis_operations
node_ibis_backend -.->|"connects to"| node_data_service
node_ibis_connection -->|"returns relation"| node_expressions
node_iceberg_backend -->|"creates connection"| node_iceberg_connection
node_iceberg_backend -->|"uses catalog"| node_rest_catalog
node_iceberg_connection -->|"extends base"| node_connection_base
node_iceberg_connection -->|"delegates operations"| node_iceberg_operations
node_iceberg_connection -->|"uses helpers"| node_iceberg_inspection
node_iceberg_connection -.->|"populates metadata"| node_metadata
node_ibis_inspection -->|"produces metadata"| node_metadata
node_iceberg_inspection -->|"produces metadata"| node_metadata
node_iceberg_connection -.->|"accesses catalog"| node_data_service
node_ibis_backend -.->|"implements protocol"| node_contracts
node_iceberg_backend -->|"implements protocol"| node_contracts

click node_utils "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/core/utils.py"
click node_conn_factory "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/core/factories/connection_factory.py"
click node_settings_factory "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/core/factories/settings_factory.py"
click node_backend_settings "https://github.com/mountainash-io/mountainash-data/tree/main/src/mountainash_data/core/settings"
click node_settings_registry "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/core/settings/registry.py"
click node_connection_base "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/core/connection.py"
click node_contracts "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/core/protocol.py"
click node_metadata "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/core/inspection.py"
click node_ibis_backend "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/ibis/backend.py"
click node_ibis_dialects "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/ibis/dialects/_registry.py"
click node_ibis_connection "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/ibis/connection.py"
click node_ibis_operations "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/ibis/operations.py"
click node_ibis_inspection "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/ibis/inspect.py"
click node_iceberg_backend "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/iceberg/backend.py"
click node_rest_catalog "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/iceberg/catalogs/rest.py"
click node_iceberg_connection "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/iceberg/connection.py"
click node_iceberg_operations "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/iceberg/operations.py"
click node_iceberg_inspection "https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/iceberg/inspect.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_utils,node_conn_factory,node_developer toneBlue
class node_settings_factory,node_backend_settings,node_settings_registry,node_data_service toneAmber
class node_ibis_backend,node_ibis_dialects,node_ibis_connection,node_ibis_operations,node_ibis_inspection toneMint
class node_iceberg_backend,node_rest_catalog,node_iceberg_connection,node_iceberg_operations,node_iceberg_inspection toneRose
class node_connection_base,node_contracts,node_metadata,node_expressions toneIndigo
```

## Components

### Public access

- [DatabaseUtils](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/core/utils.py): `src/mountainash_data/core/utils.py`
- [Connection factory](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/core/factories/connection_factory.py): `src/mountainash_data/core/factories/connection_factory.py`

### Configuration

- [Settings factory](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/core/factories/settings_factory.py): `src/mountainash_data/core/factories/settings_factory.py`
- [Backend settings](https://github.com/mountainash-io/mountainash-data/tree/main/src/mountainash_data/core/settings): `src/mountainash_data/core/settings`
- [Settings registry](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/core/settings/registry.py): `src/mountainash_data/core/settings/registry.py`

### Ibis backends

- [Ibis backend](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/ibis/backend.py): `src/mountainash_data/backends/ibis/backend.py`
- [Dialect registry](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/ibis/dialects/_registry.py): `src/mountainash_data/backends/ibis/dialects/_registry.py`
- [Ibis connection](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/ibis/connection.py): `src/mountainash_data/backends/ibis/connection.py`
- [Ibis operations](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/ibis/operations.py): `src/mountainash_data/backends/ibis/operations.py`
- [Ibis inspection](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/ibis/inspect.py): `src/mountainash_data/backends/ibis/inspect.py`

### Iceberg backends

- [Iceberg backend](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/iceberg/backend.py): `src/mountainash_data/backends/iceberg/backend.py`
- [REST catalog](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/iceberg/catalogs/rest.py): `src/mountainash_data/backends/iceberg/catalogs/rest.py`
- [Iceberg connection](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/iceberg/connection.py): `src/mountainash_data/backends/iceberg/connection.py`
- [Iceberg operations](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/iceberg/operations.py): `src/mountainash_data/backends/iceberg/operations.py`
- [Iceberg inspection](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/backends/iceberg/inspect.py): `src/mountainash_data/backends/iceberg/inspect.py`

### Shared contracts

- [Connection base](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/core/connection.py): `src/mountainash_data/core/connection.py`
- [Backend contracts](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/core/protocol.py): `src/mountainash_data/core/protocol.py`
- [Inspection metadata](https://github.com/mountainash-io/mountainash-data/blob/main/src/mountainash_data/core/inspection.py): `src/mountainash_data/core/inspection.py`

### Other components

- **Library user**
- **Data service or catalog**
- **Expressions consumer**

## Connections

- Library user → DatabaseUtils: creates connection (evidence: `README.md`)
- DatabaseUtils → Connection factory: delegates to
- Settings factory → Backend settings: builds profiles (evidence: `src/mountainash_data/core/factories/settings_factory.py`)
- Backend settings → Settings registry: registers profiles (evidence: `src/mountainash_data/core/settings/bigquery.py`)
- Library user → Settings factory: selects settings (evidence: `README.md`)
- Connection factory → Ibis backend: selects backend
- Ibis backend → Dialect registry: uses registry (evidence: `src/mountainash_data/backends/ibis/backend.py`)
- Ibis backend → Ibis inspection: uses helpers (evidence: `src/mountainash_data/backends/ibis/backend.py`)
- Ibis connection → Connection base: extends base (evidence: `src/mountainash_data/backends/ibis/connection.py`)
- Ibis connection → Ibis operations: delegates operations
- Ibis backend → Data service or catalog: connects to
- Ibis connection → Expressions consumer: returns relation (evidence: `README.md`)
- Iceberg backend → Iceberg connection: creates connection (evidence: `src/mountainash_data/backends/iceberg/backend.py`)
- Iceberg backend → REST catalog: uses catalog (evidence: `src/mountainash_data/backends/iceberg/backend.py`)
- Iceberg connection → Connection base: extends base (evidence: `src/mountainash_data/backends/iceberg/connection.py`)
- Iceberg connection → Iceberg operations: delegates operations (evidence: `src/mountainash_data/backends/iceberg/connection.py`)
- Iceberg connection → Iceberg inspection: uses helpers (evidence: `src/mountainash_data/backends/iceberg/connection.py`)
- Iceberg connection → Inspection metadata: populates metadata (evidence: `src/mountainash_data/backends/iceberg/connection.py`)
- Ibis inspection → Inspection metadata: produces metadata (evidence: `src/mountainash_data/backends/ibis/inspect.py`)
- Iceberg inspection → Inspection metadata: produces metadata (evidence: `src/mountainash_data/backends/iceberg/inspect.py`)
- Iceberg connection → Data service or catalog: accesses catalog
- Ibis backend → Backend contracts: implements protocol
- Iceberg backend → Backend contracts: implements protocol (evidence: `src/mountainash_data/backends/iceberg/backend.py`)
