# shuttle-hq/synth architecture

> Architecture diagram of the GitHub repository shuttle-hq/synth, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shuttle-hq/synth
- Repository: https://github.com/shuttle-hq/synth

## Overview

##### Project Type and Purpose
- This is an open-source, declarative data-generation tool (“Synth”) implemented in Rust.
- It provides a CLI for importing schemas (from Postgres/MySQL/Mongo), inferring/generating data, and exporting to stdout or databases.
- It also includes support libraries, test harnesses, examples, a Docusaurus-based documentation site, and a Next.js “www” marketing site.

##### File-Structure Analysis
- Top-level Rust crates:
- core/ : the heart of schema compilation, graph representations, and inference logic
- gen/  : data-serialization, code generation utilities
- synth/: the CLI binary, command parsing, import/export commands, driver modules
- test_macros/: custom procedural macros for testing
- Support directories:
- examples/ : sample schemas and code
- docs/     : Docusaurus-based static documentation
- www/      : Next.js marketing & install site
- dist/playground/ : packaged playground example
- synth/testing_harness/: end-to-end tests against live databases
- DevOps/config:
- .github/workflows/, nix/, tools/: CI, packaging scripts, reproducible builds

##### Key Insights from README
- Synth is database-agnostic, supports import from SQL/NoSQL, and outputs realistic, constraint-based synthetic data.
- Core features: declarative schema, data inference, multi-database drivers, semantically rich types.
- Built in Rust for performance and safety.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Binary"
        synth["synth src/main.rs\nCLI Binary"]:::crate
        cli_mod["Command Parsing & Commands"]:::crate
        sampler["Sampling Engine"]:::crate
        error_cli["CLI Error Types"]:::crate
        datasrc_mod["Datasource Abstractions"]:::crate
        pg_cli["Postgres Driver"]:::driver
        mysql_cli["MySQL Driver"]:::driver
        mongo_cli["MongoDB Driver"]:::driver
        pg_ds["Postgres Datasource Plugin"]:::driver
        mysql_ds["MySQL Datasource Plugin"]:::driver
        rel_ds["Relational Datasource Helper"]:::driver
    end

    %% Core and Generator Libraries
    subgraph "Core Library"
        core_lib["core/src/lib.rs\nSchema Compiler & Graph"]:::crate
        core_error["Core Error Types"]:::crate
    end

    subgraph "Generator Library"
        gen_lib["gen/src/lib.rs\nSerialization & Codegen"]:::crate
    end

    %% External Databases
    PGDB[(Postgres DB)]:::external
    MYSQLDB[(MySQL DB)]:::external
    MONGODB[(MongoDB)]:::external

    %% Support & Examples
    subgraph "Support & Examples"
        test_harness["Test Harness"]:::support
        examples["Examples"]:::support
        playground["Packaged Playground"]:::support
    end

    %% Websites
    subgraph "Websites"
        docs["Documentation Site"]:::site
        www["Marketing Site"]:::site
    end

    %% DevOps
    subgraph "DevOps"
        ci["CI/CD Workflows"]:::devops
        nix["Nix Build & Packaging"]:::devops
        tools["Dev Tools & Scripts"]:::devops
    end

    %% Data Flow
    synth --> cli_mod
    cli_mod --> datasrc_mod
    datasrc_mod --> pg_ds
    datasrc_mod --> mysql_ds
    datasrc_mod --> rel_ds

    cli_mod --> pg_cli
    cli_mod --> mysql_cli
    cli_mod --> mongo_cli

    pg_cli --> PGDB
    mysql_cli --> MYSQLDB
    mongo_cli --> MONGODB

    cli_mod --> sampler
    sampler --> core_lib
    core_lib --> gen_lib
    sampler --> gen_lib

    %% Import Workflow
    pg_cli -->|"import metadata"| core_lib
    mysql_cli -->|"import metadata"| core_lib
    mongo_cli -->|"import metadata"| core_lib

    %% Export Workflow
    sampler -->|"JSON/CSV"| gen_lib
    gen_lib --> synth

    %% Support & Testing
    test_harness --> synth
    test_harness --> PGDB
    test_harness --> MYSQLDB
    test_harness --> MONGODB
    examples --> synth
    playground --> synth

    %% Websites
    docs -->|"static content"| docs
    www -->|"Next.js UI"| www

    %% DevOps Connections
    ci --> synth
    ci --> docs
    ci --> www
    ci --> nix
    nix --> synth
    tools --> synth

    %% Click Events
    click synth "https://github.com/shuttle-hq/synth/blob/master/synth/src/main.rs"
    click cli_mod "https://github.com/shuttle-hq/synth/blob/master/synth/src/cli/mod.rs"
    click sampler "https://github.com/shuttle-hq/synth/blob/master/synth/src/sampler.rs"
    click error_cli "https://github.com/shuttle-hq/synth/blob/master/synth/src/error.rs"
    click datasrc_mod "https://github.com/shuttle-hq/synth/blob/master/synth/src/datasource/mod.rs"
    click pg_cli "https://github.com/shuttle-hq/synth/blob/master/synth/src/cli/postgres.rs"
    click mysql_cli "https://github.com/shuttle-hq/synth/blob/master/synth/src/cli/mysql.rs"
    click mongo_cli "https://github.com/shuttle-hq/synth/blob/master/synth/src/cli/mongo.rs"
    click pg_ds "https://github.com/shuttle-hq/synth/blob/master/synth/src/datasource/postgres_datasource.rs"
    click mysql_ds "https://github.com/shuttle-hq/synth/blob/master/synth/src/datasource/mysql_datasource.rs"
    click rel_ds "https://github.com/shuttle-hq/synth/blob/master/synth/src/datasource/relational_datasource.rs"
    click core_lib "https://github.com/shuttle-hq/synth/blob/master/core/src/lib.rs"
    click core_error "https://github.com/shuttle-hq/synth/blob/master/core/src/error.rs"
    click gen_lib "https://github.com/shuttle-hq/synth/blob/master/gen/src/lib.rs"
    click test_harness "https://github.com/shuttle-hq/synth/tree/master/synth/testing_harness/"
    click examples "https://github.com/shuttle-hq/synth/tree/master/examples/"
    click playground "https://github.com/shuttle-hq/synth/blob/master/dist/playground/src/main.rs"
    click docs "https://github.com/shuttle-hq/synth/tree/master/docs/"
    click www "https://github.com/shuttle-hq/synth/tree/master/www/"
    click ci "https://github.com/shuttle-hq/synth/tree/master/.github/workflows/"
    click nix "https://github.com/shuttle-hq/synth/tree/master/nix/"
    click tools "https://github.com/shuttle-hq/synth/tree/master/tools/"

    %% Styles
    classDef crate fill:#a8d0e6,stroke:#1b1e23,color:#1b1e23;
    classDef driver fill:#f8c291,stroke:#1b1e23,color:#1b1e23;
    classDef external fill:#ffbe76,stroke:#1b1e23,color:#1b1e23;
    classDef support fill:#dfe4ea,stroke:#1b1e23,color:#1b1e23;
    classDef site fill:#c7ecee,stroke:#1b1e23,color:#1b1e23;
    classDef devops fill:#ddd6f3,stroke:#1b1e23,color:#1b1e23;
```
