# viaduct-dev/pg-persistence architecture

> Architecture diagram of the GitHub repository viaduct-dev/pg-persistence, 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/viaduct-dev/pg-persistence
- Repository: https://github.com/viaduct-dev/pg-persistence

## Overview

PG Persistence spans build-time schema modeling and SQL generation, plus a runtime library that delegates Viaduct resolver reads and writes to PostgreSQL’s pg_graphql API. The primary path is schema and persistence policy → validated persistence model → Hibernate effective model → migration and pg_graphql metadata artifacts; at runtime, resolver selections flow through DbClient to pg_graphql and results are hydrated into Viaduct types. The runtime entry point and key model transformations are evidenced by the README and sampled source references; finer Gradle-task and renderer wiring is not fully shown.

Main entry points: [`runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt`](https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt) (DbClient), [`plugin/src/main/kotlin/dev/viaduct/persistence/hibernate/EffectiveHibernateModelBuilder.kt`](https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/hibernate/EffectiveHibernateModelBuilder.kt) (Effective model), [`runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbFetcher.kt`](https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbFetcher.kt) (Fetch and batch), [`plugin/src/main/kotlin/dev/viaduct/persistence/model`](https://github.com/viaduct-dev/pg-persistence/tree/main/plugin/src/main/kotlin/dev/viaduct/persistence/model) (Schema and policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build_model["Build-time modeling"]
  node_schema_policy["Schema and policy"]
  node_persistence_model["Persistence model"]
  node_hibernate_metadata["Hibernate metadata"]
  node_effective_model["Effective model"]
  node_gradle_plugin["Gradle integration"]
end

subgraph group_build_sql["Schema and migrations"]
  node_migration_plan["Migration plan"]
  node_postgres_renderers["PostgreSQL SQL"]
  node_pg_overlay["pg_graphql overlay"]
  node_constraint_names["Constraint comments"]
  node_liquibase["Schema diff"]
end

subgraph group_runtime_query["Runtime data access"]
  node_db_client["DbClient<br/>[DbClient.kt]"]
  node_query_planner["Query planner<br/>[DbQueryPlanner.kt]"]
  node_db_fetchers["Fetch and batch<br/>[DbFetcher.kt]"]
  node_mutations["Mutation client"]
  node_transport["GraphQL transport"]
end

subgraph group_runtime_shape["Runtime mapping"]
  node_connections["Connection pagination"]
  node_node_refs["Node references"]
  node_reflection["Generated-type reflection"]
  node_result_mapping["Result mapping"]
end

node_developer(("Application developer"))
node_resolver(("Viaduct resolvers"))
node_pggraphql{{"pg_graphql API"}}
node_postgres[("PostgreSQL tables")]

node_developer -->|"defines"| node_schema_policy
node_gradle_plugin -.->|"loads"| node_schema_policy
node_schema_policy -.->|"builds"| node_persistence_model
node_persistence_model -.->|"configures"| node_hibernate_metadata
node_hibernate_metadata -->|"projects"| node_effective_model
node_gradle_plugin -->|"generates"| node_effective_model
node_effective_model -->|"maps"| node_migration_plan
node_migration_plan -.->|"renders"| node_postgres_renderers
node_effective_model -.->|"renders metadata"| node_pg_overlay
node_effective_model -->|"names constraints"| node_constraint_names
node_effective_model -->|"diffs against"| node_liquibase
node_resolver -->|"delegates"| node_db_client
node_db_client -->|"plans reads"| node_query_planner
node_db_client -->|"fetches"| node_db_fetchers
node_db_client -->|"delegates writes"| node_mutations
node_query_planner -->|"uses"| node_reflection
node_db_fetchers -.->|"sends queries"| node_transport
node_mutations -->|"executes"| node_transport
node_transport -->|"sends GraphQL"| node_pggraphql
node_pggraphql -->|"queries tables"| node_postgres
node_db_client -->|"fetches pages"| node_connections
node_db_client -->|"hydrates references"| node_node_refs
node_node_refs -->|"uses"| node_reflection
node_connections -->|"classifies shapes"| node_reflection
node_db_fetchers -.->|"decodes results"| node_result_mapping
node_result_mapping -->|"returns Viaduct types"| node_resolver

click node_schema_policy "https://github.com/viaduct-dev/pg-persistence/tree/main/plugin/src/main/kotlin/dev/viaduct/persistence/model"
click node_persistence_model "https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/model/PersistenceModel.kt"
click node_hibernate_metadata "https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/hibernate/HibernateMetadataBootstrap.kt"
click node_effective_model "https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/hibernate/EffectiveHibernateModelBuilder.kt"
click node_gradle_plugin "https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/gradle/ViaductPgPersistencePlugin.kt"
click node_migration_plan "https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/postgresql/EffectiveModelToMigrationPlanMapper.kt"
click node_postgres_renderers "https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/postgresql/PostgresqlMigrationRenderer.kt"
click node_pg_overlay "https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/pggraphql/overlay/PgGraphqlOverlay.kt"
click node_constraint_names "https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/pggraphql/overlay/PgGraphqlConstraintRenderer.kt"
click node_liquibase "https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/liquibase/ViaductHibernateDatabase.kt"
click node_db_client "https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt"
click node_query_planner "https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbQueryPlanner.kt"
click node_db_fetchers "https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbFetcher.kt"
click node_mutations "https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/PgGraphqlMutationClient.kt"
click node_transport "https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/graphql/GraphqlTransport.kt"
click node_connections "https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/connection/ConnectionQueryPlanner.kt"
click node_node_refs "https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/node/NodeReferenceHydrator.kt"
click node_reflection "https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/reflection/GeneratedTypeReflection.kt"
click node_result_mapping "https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbResponseReader.kt"

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_schema_policy,node_persistence_model,node_hibernate_metadata,node_effective_model,node_gradle_plugin toneBlue
class node_migration_plan,node_postgres_renderers,node_pg_overlay,node_constraint_names,node_liquibase,node_postgres toneAmber
class node_db_client,node_query_planner,node_db_fetchers,node_mutations,node_transport,node_pggraphql toneMint
class node_connections,node_node_refs,node_reflection,node_result_mapping toneRose
class node_developer,node_resolver toneIndigo
```

## Components

### Build-time modeling

- [Schema and policy](https://github.com/viaduct-dev/pg-persistence/tree/main/plugin/src/main/kotlin/dev/viaduct/persistence/model): `plugin/src/main/kotlin/dev/viaduct/persistence/model`
- [Persistence model](https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/model/PersistenceModel.kt): `plugin/src/main/kotlin/dev/viaduct/persistence/model/PersistenceModel.kt`
- [Hibernate metadata](https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/hibernate/HibernateMetadataBootstrap.kt): `plugin/src/main/kotlin/dev/viaduct/persistence/hibernate/HibernateMetadataBootstrap.kt`
- [Effective model](https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/hibernate/EffectiveHibernateModelBuilder.kt): `plugin/src/main/kotlin/dev/viaduct/persistence/hibernate/EffectiveHibernateModelBuilder.kt`
- [Gradle integration](https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/gradle/ViaductPgPersistencePlugin.kt): `plugin/src/main/kotlin/dev/viaduct/persistence/gradle/ViaductPgPersistencePlugin.kt`

### Schema and migrations

- [Migration plan](https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/postgresql/EffectiveModelToMigrationPlanMapper.kt): `plugin/src/main/kotlin/dev/viaduct/persistence/postgresql/EffectiveModelToMigrationPlanMapper.kt`
- [PostgreSQL SQL](https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/postgresql/PostgresqlMigrationRenderer.kt): `plugin/src/main/kotlin/dev/viaduct/persistence/postgresql/PostgresqlMigrationRenderer.kt`
- [pg_graphql overlay](https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/pggraphql/overlay/PgGraphqlOverlay.kt): `plugin/src/main/kotlin/dev/viaduct/persistence/pggraphql/overlay/PgGraphqlOverlay.kt`
- [Constraint comments](https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/pggraphql/overlay/PgGraphqlConstraintRenderer.kt): `plugin/src/main/kotlin/dev/viaduct/persistence/pggraphql/overlay/PgGraphqlConstraintRenderer.kt`
- [Schema diff](https://github.com/viaduct-dev/pg-persistence/blob/main/plugin/src/main/kotlin/dev/viaduct/persistence/liquibase/ViaductHibernateDatabase.kt): `plugin/src/main/kotlin/dev/viaduct/persistence/liquibase/ViaductHibernateDatabase.kt`

### Runtime data access

- [DbClient](https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt): `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt`
- [Query planner](https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbQueryPlanner.kt): `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbQueryPlanner.kt`
- [Fetch and batch](https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbFetcher.kt): `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbFetcher.kt`
- [Mutation client](https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/PgGraphqlMutationClient.kt): `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/PgGraphqlMutationClient.kt`
- [GraphQL transport](https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/graphql/GraphqlTransport.kt): `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/graphql/GraphqlTransport.kt`

### Runtime mapping

- [Connection pagination](https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/connection/ConnectionQueryPlanner.kt): `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/connection/ConnectionQueryPlanner.kt`
- [Node references](https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/node/NodeReferenceHydrator.kt): `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/node/NodeReferenceHydrator.kt`
- [Generated-type reflection](https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/reflection/GeneratedTypeReflection.kt): `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/reflection/GeneratedTypeReflection.kt`
- [Result mapping](https://github.com/viaduct-dev/pg-persistence/blob/main/runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbResponseReader.kt): `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbResponseReader.kt`

### Other components

- **Application developer**
- **Viaduct resolvers**
- **pg_graphql API**
- **PostgreSQL tables**

## Connections

- Application developer → Schema and policy: defines (evidence: `README.md`)
- Gradle integration → Schema and policy: loads
- Schema and policy → Persistence model: builds
- Persistence model → Hibernate metadata: configures
- Hibernate metadata → Effective model: projects (evidence: `plugin/src/main/kotlin/dev/viaduct/persistence/liquibase/ViaductHibernateDatabase.kt`)
- Gradle integration → Effective model: generates
- Effective model → Migration plan: maps (evidence: `plugin/src/main/kotlin/dev/viaduct/persistence/postgresql/EffectiveModelToMigrationPlanMapper.kt`)
- Migration plan → PostgreSQL SQL: renders
- Effective model → pg_graphql overlay: renders metadata
- Effective model → Constraint comments: names constraints (evidence: `plugin/src/main/kotlin/dev/viaduct/persistence/pggraphql/overlay/PgGraphqlConstraintRenderer.kt`)
- Effective model → Schema diff: diffs against (evidence: `plugin/src/main/kotlin/dev/viaduct/persistence/liquibase/ViaductHibernateDatabase.kt`)
- Viaduct resolvers → DbClient: delegates (evidence: `README.md`)
- DbClient → Query planner: plans reads (evidence: `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt`)
- DbClient → Fetch and batch: fetches (evidence: `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt`)
- DbClient → Mutation client: delegates writes (evidence: `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt`)
- Query planner → Generated-type reflection: uses (evidence: `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbQueryPlanner.kt`)
- Fetch and batch → GraphQL transport: sends queries
- Mutation client → GraphQL transport: executes (evidence: `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/PgGraphqlMutationClient.kt`)
- GraphQL transport → pg_graphql API: sends GraphQL (evidence: `README.md`)
- pg_graphql API → PostgreSQL tables: queries tables (evidence: `README.md`)
- DbClient → Connection pagination: fetches pages (evidence: `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt`)
- DbClient → Node references: hydrates references (evidence: `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt`)
- Node references → Generated-type reflection: uses (evidence: `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/node/NodeReferenceHydrator.kt`)
- Connection pagination → Generated-type reflection: classifies shapes (evidence: `runtime/src/main/kotlin/dev/viaduct/persistence/runtime/reflection/GeneratedTypeReflection.kt`)
- Fetch and batch → Result mapping: decodes results
- Result mapping → Viaduct resolvers: returns Viaduct types (evidence: `README.md`)
