# google/dpsynth architecture

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

- Interactive diagram: https://gitdiagram.com/google/dpsynth
- Repository: https://github.com/google/dpsynth

## Overview

DPSynth generates differentially private synthetic tabular data through three documented routes: in-memory synthesis, a scalable pipeline, and post-processing of existing noisy marginals. The main workflow describes a schema, measures or supplies marginals, fits a discrete model, and decodes synthetic records. The graph also preserves documented evaluation and relational/typed-data capabilities. The excerpts confirm parts of local synthesis, Beam encoding, and relational processing; links for unsampled subsystems follow README descriptions and are limited to documented responsibilities.

Main entry points: [`dpsynth/data_generation_v3.py`](https://github.com/google/dpsynth/blob/main/dpsynth/data_generation_v3.py) (Local Generation), [`dpsynth/data_generation.py`](https://github.com/google/dpsynth/blob/main/dpsynth/data_generation.py) (Pipeline Generation), [`dpsynth/pipeline_transformations`](https://github.com/google/dpsynth/tree/main/dpsynth/pipeline_transformations) (Pipeline Transformations), [`dpsynth/relational/synthesizer.py`](https://github.com/google/dpsynth/blob/main/dpsynth/relational/synthesizer.py) (Relational Synthesis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_schema["Schema and Encoding"]
  node_domain["Domain Schema<br/>[domain.py]"]
  node_constraints["Constraints<br/>[constraints.py]"]
  node_transformations["Domain Transformations<br/>[transformations.py]"]
end

subgraph group_local["Local Synthesis"]
  node_local_api["TabularConfig<br/>[__init__.py]"]
  node_local_generation["Local Generation"]
  node_local_primitives["Local Primitives<br/>[primitives.py]"]
  node_mechanisms["Discrete Mechanisms"]
  node_postprocessing["Marginal Postprocessing<br/>[postprocessing.py]"]
end

subgraph group_pipeline["Scalable Pipeline"]
  node_pipeline_api["Pipeline Generation<br/>[data_generation.py]"]
  node_descriptors["Dataset Descriptors"]
  node_pipeline_ops["Pipeline Transformations"]
  node_beam_adapter["Beam Adapter<br/>[beam.py]"]
  node_marginal_ops["Marginal Computation"]
end

subgraph group_extended["Extended Synthesis"]
  node_relational["Relational Synthesis<br/>[synthesizer.py]"]
  node_relational_processing["Relational Postprocessing<br/>[post_processing.py]"]
  node_nested["Nested Synthesis<br/>[nested.py]"]
  node_text["Private Text Tools"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_api["Tabular Evaluation<br/>[tabular_eval.py]"]
  node_eval_stats["Dataset Statistics"]
end

node_user(("Data User"))
node_eval_input(("Real or Synthetic Data"))

node_user -->|"configures"| node_local_api
node_local_api -->|"calibrates"| node_local_generation
node_domain -->|"defines schema"| node_local_generation
node_constraints -->|"constrains"| node_local_generation
node_local_generation -->|"encodes data"| node_transformations
node_local_generation -->|"runs mechanism"| node_mechanisms
node_local_generation -->|"uses primitives"| node_local_primitives
node_local_generation -->|"returns synthetic data"| node_user
node_user -->|"configures"| node_pipeline_api
node_pipeline_api -->|"uses descriptors"| node_descriptors
node_pipeline_api -->|"runs operations"| node_pipeline_ops
node_pipeline_ops -->|"dispatches Beam"| node_beam_adapter
node_pipeline_ops -->|"computes marginals"| node_marginal_ops
node_pipeline_api -->|"produces dataset"| node_user
node_user -->|"supplies marginals"| node_postprocessing
node_postprocessing -->|"returns synthetic data"| node_user
node_user -->|"supplies tables"| node_relational
node_relational -->|"creates initializers"| node_local_generation
node_relational -->|"postprocesses tables"| node_relational_processing
node_user -->|"configures synthesis"| node_nested
node_nested -->|"synthesizes components"| node_local_generation
node_user -.->|"uses text tools"| node_text
node_eval_input -->|"provides dataset"| node_eval_api
node_eval_api -->|"computes statistics"| node_eval_stats
node_eval_api -->|"returns evaluation"| node_user

click node_domain "https://github.com/google/dpsynth/blob/main/dpsynth/domain.py"
click node_constraints "https://github.com/google/dpsynth/blob/main/dpsynth/constraints.py"
click node_transformations "https://github.com/google/dpsynth/blob/main/dpsynth/transformations.py"
click node_local_api "https://github.com/google/dpsynth/blob/main/dpsynth/__init__.py"
click node_local_generation "https://github.com/google/dpsynth/blob/main/dpsynth/data_generation_v3.py"
click node_local_primitives "https://github.com/google/dpsynth/blob/main/dpsynth/local_mode/primitives.py"
click node_mechanisms "https://github.com/google/dpsynth/tree/main/dpsynth/discrete_mechanisms"
click node_postprocessing "https://github.com/google/dpsynth/blob/main/dpsynth/postprocessing.py"
click node_pipeline_api "https://github.com/google/dpsynth/blob/main/dpsynth/data_generation.py"
click node_descriptors "https://github.com/google/dpsynth/tree/main/dpsynth/dataset_descriptors"
click node_pipeline_ops "https://github.com/google/dpsynth/tree/main/dpsynth/pipeline_transformations"
click node_beam_adapter "https://github.com/google/dpsynth/blob/main/dpsynth/adapters/beam.py"
click node_marginal_ops "https://github.com/google/dpsynth/blob/main/dpsynth/pipeline_transformations/marginals_computations.py"
click node_relational "https://github.com/google/dpsynth/blob/main/dpsynth/relational/synthesizer.py"
click node_relational_processing "https://github.com/google/dpsynth/blob/main/dpsynth/relational/post_processing.py"
click node_nested "https://github.com/google/dpsynth/blob/main/dpsynth/experimental/nested.py"
click node_text "https://github.com/google/dpsynth/tree/main/dpsynth/text"
click node_eval_api "https://github.com/google/dpsynth/blob/main/dpsynth/eval/tabular_eval.py"
click node_eval_stats "https://github.com/google/dpsynth/blob/main/dpsynth/eval/attribute_statistics.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_domain,node_constraints,node_transformations,node_user toneBlue
class node_local_api,node_local_generation,node_local_primitives,node_mechanisms,node_postprocessing toneAmber
class node_pipeline_api,node_descriptors,node_pipeline_ops,node_beam_adapter,node_marginal_ops toneMint
class node_relational,node_relational_processing,node_nested,node_text toneRose
class node_eval_api,node_eval_stats,node_eval_input toneIndigo
```

## Components

### Schema and Encoding

- [Domain Schema](https://github.com/google/dpsynth/blob/main/dpsynth/domain.py): `dpsynth/domain.py`
- [Constraints](https://github.com/google/dpsynth/blob/main/dpsynth/constraints.py): `dpsynth/constraints.py`
- [Domain Transformations](https://github.com/google/dpsynth/blob/main/dpsynth/transformations.py): `dpsynth/transformations.py`

### Local Synthesis

- [TabularConfig](https://github.com/google/dpsynth/blob/main/dpsynth/__init__.py): `dpsynth/__init__.py`
- [Local Generation](https://github.com/google/dpsynth/blob/main/dpsynth/data_generation_v3.py): `dpsynth/data_generation_v3.py`
- [Local Primitives](https://github.com/google/dpsynth/blob/main/dpsynth/local_mode/primitives.py): `dpsynth/local_mode/primitives.py`
- [Discrete Mechanisms](https://github.com/google/dpsynth/tree/main/dpsynth/discrete_mechanisms): `dpsynth/discrete_mechanisms`
- [Marginal Postprocessing](https://github.com/google/dpsynth/blob/main/dpsynth/postprocessing.py): `dpsynth/postprocessing.py`

### Scalable Pipeline

- [Pipeline Generation](https://github.com/google/dpsynth/blob/main/dpsynth/data_generation.py): `dpsynth/data_generation.py`
- [Dataset Descriptors](https://github.com/google/dpsynth/tree/main/dpsynth/dataset_descriptors): `dpsynth/dataset_descriptors`
- [Pipeline Transformations](https://github.com/google/dpsynth/tree/main/dpsynth/pipeline_transformations): `dpsynth/pipeline_transformations`
- [Beam Adapter](https://github.com/google/dpsynth/blob/main/dpsynth/adapters/beam.py): `dpsynth/adapters/beam.py`
- [Marginal Computation](https://github.com/google/dpsynth/blob/main/dpsynth/pipeline_transformations/marginals_computations.py): `dpsynth/pipeline_transformations/marginals_computations.py`

### Extended Synthesis

- [Relational Synthesis](https://github.com/google/dpsynth/blob/main/dpsynth/relational/synthesizer.py): `dpsynth/relational/synthesizer.py`
- [Relational Postprocessing](https://github.com/google/dpsynth/blob/main/dpsynth/relational/post_processing.py): `dpsynth/relational/post_processing.py`
- [Nested Synthesis](https://github.com/google/dpsynth/blob/main/dpsynth/experimental/nested.py): `dpsynth/experimental/nested.py`
- [Private Text Tools](https://github.com/google/dpsynth/tree/main/dpsynth/text): `dpsynth/text`

### Evaluation

- [Tabular Evaluation](https://github.com/google/dpsynth/blob/main/dpsynth/eval/tabular_eval.py): `dpsynth/eval/tabular_eval.py`
- [Dataset Statistics](https://github.com/google/dpsynth/blob/main/dpsynth/eval/attribute_statistics.py): `dpsynth/eval/attribute_statistics.py`

### Other components

- **Data User**
- **Real or Synthetic Data**

## Connections

- Data User → TabularConfig: configures
- TabularConfig → Local Generation: calibrates
- Domain Schema → Local Generation: defines schema
- Constraints → Local Generation: constrains
- Local Generation → Domain Transformations: encodes data
- Local Generation → Discrete Mechanisms: runs mechanism
- Local Generation → Local Primitives: uses primitives
- Local Generation → Data User: returns synthetic data
- Data User → Pipeline Generation: configures
- Pipeline Generation → Dataset Descriptors: uses descriptors
- Pipeline Generation → Pipeline Transformations: runs operations
- Pipeline Transformations → Beam Adapter: dispatches Beam
- Pipeline Transformations → Marginal Computation: computes marginals
- Pipeline Generation → Data User: produces dataset
- Data User → Marginal Postprocessing: supplies marginals
- Marginal Postprocessing → Data User: returns synthetic data
- Data User → Relational Synthesis: supplies tables
- Relational Synthesis → Local Generation: creates initializers
- Relational Synthesis → Relational Postprocessing: postprocesses tables
- Data User → Nested Synthesis: configures synthesis
- Nested Synthesis → Local Generation: synthesizes components
- Data User → Private Text Tools: uses text tools
- Real or Synthetic Data → Tabular Evaluation: provides dataset
- Tabular Evaluation → Dataset Statistics: computes statistics
- Tabular Evaluation → Data User: returns evaluation