> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bensevern.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How the six Golden Suite tools compose into one pipeline across Python, TypeScript, Rust, dbt, and GitHub Actions.

The Golden Suite is built so each tool stands alone but composes into a single pipeline. You can pick just the piece you need, or run the full chain end to end.

## The pipeline flow

```mermaid theme={null}
flowchart LR
  A[Raw rows] --> B[InferMap]
  B --> C[GoldenCheck]
  C --> D[GoldenFlow]
  D --> E[GoldenMatch]
  E --> F[Golden records]
```

<Steps>
  <Step title="InferMap aligns schemas">
    Auto-maps messy source columns to a known target schema with confidence scores and human-readable reasoning.
  </Step>

  <Step title="GoldenCheck profiles and validates">
    Discovers quality rules from the data itself: encoding, format, nullability, anomalies.
  </Step>

  <Step title="GoldenFlow standardizes">
    Normalizes phone numbers, dates, addresses, and categorical spelling with 92 built-in transforms.
  </Step>

  <Step title="GoldenMatch deduplicates">
    Blocks, scores, clusters, and synthesizes golden records using fuzzy, exact, probabilistic, and LLM scoring.
  </Step>

  <Step title="GoldenPipe orchestrates">
    Runs the whole chain with adaptive logic. It skips transformation if no issues are found and explains every decision.
  </Step>

  <Step title="GoldenAnalysis reports">
    Runs read-only analyzers over any stage's outputs — match rates, cluster distribution, quality rollups — with cross-run trend and regression detection.
  </Step>
</Steps>

## Polyglot by design

The same engine is implemented across languages so you can run it wherever your data lives.

| Surface        | What it covers                                                                                                                                |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Python         | Headline runtime. Full feature set, `pip install`, native Postgres and DuckDB support.                                                        |
| TypeScript     | Parity core. Edge-safe (Vercel Edge, Cloudflare Workers, Deno). Matches Python scorer outputs to four decimals.                               |
| Rust           | Postgres extension (pgrx) and DuckDB UDFs for SQL-native matching.                                                                            |
| dbt            | `dbt-goldensuite` package — entity-resolution materialization, quality-gate tests, transforms, and identity-graph reads for warehouse models. |
| GitHub Actions | `goldencheck-action` gates pull requests on data-quality regressions.                                                                         |

Every surface is exercised in CI: the Python test matrix (3.11 to 3.13), the TypeScript parity suite (scorer outputs matched to four decimals), and the Rust extension crates. The Postgres extension is built and smoke-tested against PostgreSQL 15, 16, and 17, the native acceleration kernels are parity-checked against the pure-Python path, and per-crate Rust line coverage is measured in CI.

## AI-native surface

Every package ships an MCP server; the service-shaped packages also ship a REST API and an agent surface. Across the suite there are \~110 MCP tools (GoldenMatch alone has 69). The `AutoConfigController` is visible from every interface: the web `ControllerPanel`, the TUI (`Ctrl+A`), the CLI, REST endpoints, Postgres functions, DuckDB UDFs, and MCP/agent tools.

Add the remote MCP server to Claude Desktop or Claude Code:

```json theme={null}
{
  "mcpServers": {
    "goldenmatch": {
      "url": "https://goldenmatch-mcp-production.up.railway.app/mcp/"
    }
  }
}
```

## Repository layout

The suite is a single monorepo:

```text theme={null}
packages/
├── python/       goldenmatch, goldencheck, goldenflow, goldenpipe, goldenanalysis, infermap, goldensuite-mcp
├── typescript/   goldenmatch, goldencheck, goldenflow, goldenanalysis, infermap
├── rust/         extensions (Postgres pgrx + DuckDB UDFs, incl. analysis-core/native)
├── dbt/          goldensuite
└── actions/      goldencheck GitHub Action
examples/         Python, TypeScript, and Airflow DAG demos
```

## Production paths

* Postgres sync and daemon mode for continuous deduplication.
* Review queues for human-in-the-loop correction.
* dbt integration for warehouse-native pipelines.
* GitHub Actions for pull-request data-quality gates.
* Airflow DAGs (drop-in examples, TaskFlow API, Airflow 2.7+).
* The Rust extension layer for matching directly inside Postgres or DuckDB.