Architecture¶

Cross-Package Patterns¶

Five architectural patterns recur across the mountainash ecosystem. Understanding them once makes every package more approachable.

Expressions as Universal Substrate¶

The core expression engine compiles to three backend paths (Polars, Narwhals, Ibis). Every higher-level capability — rules, validation, conformance — compiles down to these expressions, inheriting backend portability automatically.

Package	How It Uses Expressions
mountainash	84 operations, 3 backends, three-valued logic, Polars-compatible syntax
mountainash-rules	Match strategies compile to expressions — backend-portable rule evaluation
mountainash (contracts)	Validation rules compile to expressions — backend-portable quality checks
mountainash (conform)	Conform pipeline stages compile to expressions — backend-portable type coercion

Protocol-Based Extension at Every Boundary¶

Every significant boundary is a @runtime_checkable Protocol. New implementations register via entry points or decorator registries without modifying existing code.

Package	Protocols
mountainash	ExpressionSystem, RelationSystem, RelationVisitRegistry, PipelineExecutor, PipelineStorage, CustomTypeRegistry
mountainash-data	Backend (connect/close/inspect/list_tables), DialectSpec (23 entries), IcebergConnectionBase
mountainash-transport	StorageRead, StorageWrite, StorageList, StorageDelete, StorageMetadata, StorageCopy, StorageDirectory, StorageConnection
mountainash-auth-client	SecretStore, AuthProvider
mountainash-treespec	SchemaHandler (10 methods)
mountainash-rules-babel	Exporter, Importer, Decomposer, Validator

Declarative-as-Data / Derive-Runtime¶

Core configuration types are frozen dataclasses or Pydantic models. Runtime behaviour is derived from these declarations.

Package	Declaration	Derived Behaviour
mountainash-api-client	ApiEndpoint (frozen dataclass)	Retry, pagination, rate-limiting pipeline
mountainash-rules	Dimension + MatchStrategy	Expression evaluation for rule matching
mountainash-treespec	TreeSpec	Flatten/build operations from schema introspection
mountainash-settings	MountainAshBaseSettings (Pydantic)	Config files + templates + secrets resolved
mountainash-auth-client	AuthSpec discriminated union	Connection kwargs for any auth method
mountainash-data	BackendSpec + ConnectionProfile	Database connection params for 20+ backends

Dialect / Registry Dispatch¶

Both database connectivity and rule format bridging use registry-based dispatch to route to backend-specific implementations.

mountainash-data: DialectSpec registry with 23 entries; IbisBackend routes through dialect.connection_builder. Iceberg catalog registry maps type strings to connection subclasses.
mountainash-rules-babel: Entry point groups for exporters/importers/decomposers/validators; plugin discovery via importlib.metadata.
mountainash: @register_expression_system and @register_relation_system decorators for backend registration.

Physical + Logical Validation¶

Data quality operates at two levels, both compiling to the same expression engine:

Physical: TypeSpec validates column names, types, nullability, primary keys — aligned with Frictionless Table Schema
Logical: Data contracts validate expression-backed business rules with context-aware exclusions
Conform: 7-stage Frictionless-compliant type coercion (missingValues, boolean, numeric, temporal, categories, list delimiters)

Integration Seams¶

How packages connect at their boundaries:

Boundary	Contract	Shared Standard
mountainash ↔ mountainash-data	mountainash-data provides `IbisBackend` returning `ibis.Table`; mountainash wraps via `relation()` for expression evaluation	Ibis
mountainash ↔ mountainash-rules	`Relation` wraps the rules DataFrame; expressions compile dimension match logic; three-valued logic flows through both	Polars syntax, Narwhals/Ibis backends
mountainash-rules ↔ mountainash-rules-babel	Lattice, Dimension, MatchStrategy types consumed by babel exporters; 11 strategies mapped to FEEL expressions	OMG DMN 1.3
mountainash-data ↔ mountainash-settings ↔ mountainash-auth-client	AuthSpec (13 types) flows from auth-client through settings into data's 20 ConnectionProfile classes	OAuth 2.0/1.0a, Pydantic
mountainash-treespec ↔ mountainash	TreeSpec flattens to Polars DataFrames; mountainash wraps via `relation()` for conformance and validation	Frictionless Data, Parquet

Standards Layering¶

How interoperability standards are composed through the architecture:

Layer	Standards	Role
Expression compilation	Ibis, Narwhals, Substrait, Polars	Universal computation substrate
Schema and validation	Frictionless Data, Pydantic	Schema definitions, type coercion, validation modelling
Storage and lakehouse	Apache Iceberg, Parquet, DuckDB	Persistent storage for data, rules, validation results
Decision management	OMG DMN 1.3	Standards-compliant rule export for regulatory workflows
Authentication	OAuth 2.0, OAuth 1.0a	Auth flows for API and service connectivity

Textbook Generation Pipeline¶

The manuals were generated through a multi-stage pipeline. Migrated books keep these artifacts in their source repository under docs-site/; books awaiting migration retain their existing central locations. Publishing builds the committed site without rerunning generation or implying a content refresh.

Source Code (mountainash-*/src/)
    │
    ▼
Code Profile (docs-site/profile/ in migrated repositories)
    │  manifest.json + per-module profiles
    │  Tracks: public API, classes, functions, dependencies
    │
    ▼
Learning Graph (docs-site/learning-graph/ in migrated repositories)
    │  learning-graph.json — concept DAG
    │  Enriched with: source_module, source_path, chapter mappings
    │
    ▼
Textbook Site (docs-site/site/ in migrated repositories)
    ├── Chapter structure (book-chapter-generator)
    ├── Chapter content (chapter-content-generator)
    ├── MicroSims (inherited; interactive availability varies)
    ├── FAQ (faq-generator)
    ├── API reference (committed documentation, not live source generation)
    └── refresh-state.json (change tracking)

Project Structure¶

The portal and migrated textbooks publish independently. They share a hostname, not a combined build, filesystem, or search index.

mountainash-io.github.io/
└── docs-site/site/             ← this portal, linking to books

mountainash-rules/
└── docs-site/
    ├── profile/               ← source-derived profiles
    ├── learning-graph/        ← canonical concept graph
    └── site/                  ← independent MkDocs Material project

mountainash-central/           ← retained during staged migration
├── 03.profile/<project>/
├── 05.learning-graph/<project>/
└── 06.textbook-sites/<project>/

Each migrated repository builds its own literal main and develop snapshots using that branch's committed inputs. Production and development builds occupy separate output directories before being combined into that repository's Pages artifact. Production is served at the repository root URL; development is served under its dev/ prefix. Both builds must succeed before either is published.

The portal lives at https://docs.mountainash.io/, with its preview at https://docs.mountainash.io/dev/. Rules is the first migrated book, with portal links selecting its matching production or development environment.

Project	Textbook publishing
mountainash	Transitional: live central site in both portal environments
mountainash-data	Transitional: live central site in both portal environments
mountainash-settings	Transitional: live central site in both portal environments
mountainash-rules	Independent per-repository production and development
mountainash-treespec	Transitional: live central site in both portal environments
mountainash-utils-secrets	Transitional: live central site in both portal environments
mountainash-pointbreak	Transitional: live central site in both portal environments
mountainash-rules-babel	Deferred: textbook unavailable
mountainash-api-client (source now mountainash-http-client)	Deferred: textbook unavailable
mountainash-auth-client	Deferred: textbook unavailable
mountainash-transport	Deferred: textbook unavailable
mountainash-wearables	Deferred: textbook unavailable

The six transitional books keep their existing central destinations until their individual cutovers are accepted. The Project Library retains every entry, including source-repository links for deferred books. Migration does not remove central originals before cutover or regenerate educational content.

Refresh Process¶

When source code changes, the textbook-refresh skill performs targeted updates:

Detect — git diff from baseline commit to HEAD
Map — trace changed files through enriched learning graph nodes to affected chapters
Classify — categorise changes (new symbols, removed symbols, signature changes)
Plan — determine which chapter sections need regeneration
Regenerate — use  markers for section-level precision
Verify — update content hashes and refresh state

Most refreshes only touch a few sections in a few chapters — far cheaper than full regeneration.