# hibernate/hibernate-orm architecture

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

- Interactive diagram: https://gitdiagram.com/hibernate/hibernate-orm
- Repository: https://github.com/hibernate/hibernate-orm

## Overview

Hibernate ORM maps Java object models to relational data, supporting query execution, transactionally synchronized persistence, and database-specific SQL behavior. The graph highlights the query-engine and dialect path, plus documented event, caching, and connection-provider capabilities. Source excerpts are limited, so links for unsampled runtime subsystems are omitted rather than inferred; broad module paths identify documented capability areas, not inspected implementations.

Main entry points: [`hibernate-core/src/main/java/org/hibernate/query/internal/QueryEngineImpl.java`](https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/query/internal/QueryEngineImpl.java) (Query engine), [`hibernate-community-dialects/src/main/java/org/hibernate/community/dialect`](https://github.com/hibernate/hibernate-orm/tree/main/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect) (Dialect translators), [`hibernate-core/src/main/java/org/hibernate/query/spi/QueryEngine.java`](https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/query/spi/QueryEngine.java) (Query engine API), [`hibernate-core/src/main/java/org/hibernate/event/spi/EventEngine.java`](https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/event/spi/EventEngine.java) (Event engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query["Query processing"]
  node_query_engine["Query engine"]
  node_query_options["Query options"]
  node_query_api["Query engine API<br/>[QueryEngine.java]"]
end

subgraph group_database["Database support"]
  node_community_resolver["Dialect resolver"]
  node_community_translators["Dialect translators"]
  node_database_service["JDBC services"]
  node_relational_db[("Relational database")]
end

subgraph group_runtime["ORM runtime"]
  node_session_factory["Session factory builder"]
  node_event_engine["Event engine<br/>[EventEngine.java]"]
  node_service_registry["Service registry<br/>[Service.java]"]
  node_query_cache_writer["Query cache writer"]
  node_query_cache[("Query results cache")]
  node_timezone_mapping["Time-zone mapping"]
end

subgraph group_connections["Connection providers"]
  node_agroal_provider["Agroal provider"]
  node_c3p0_provider["C3P0 provider"]
  node_jdbc["JDBC connections"]
end

node_application(("Java application"))

node_application -->|"submits queries"| node_query_api
node_query_api -->|"delegates to"| node_query_engine
node_query_engine -->|"uses options"| node_query_options
node_query_engine -->|"gets dialect"| node_database_service
node_community_resolver -->|"selects dialect"| node_community_translators
node_query_engine -->|"translates queries"| node_community_translators
node_community_translators -->|"produces SQL"| node_relational_db
node_session_factory -->|"builds runtime"| node_event_engine
node_event_engine -->|"loads contributors"| node_service_registry
node_query_cache_writer -->|"writes results"| node_query_cache
node_agroal_provider -->|"provides connections"| node_jdbc
node_c3p0_provider -->|"provides connections"| node_jdbc
node_jdbc -->|"connects to"| node_relational_db
node_timezone_mapping -->|"maps temporal data"| node_relational_db

click node_query_engine "https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/query/internal/QueryEngineImpl.java"
click node_query_options "https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/query/spi/QueryEngineOptions.java"
click node_query_api "https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/query/spi/QueryEngine.java"
click node_community_resolver "https://github.com/hibernate/hibernate-orm/blob/main/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/CommunityDialectResolver.java"
click node_community_translators "https://github.com/hibernate/hibernate-orm/tree/main/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect"
click node_session_factory "https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/boot/internal/DefaultSessionFactoryBuilderService.java"
click node_event_engine "https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/event/spi/EventEngine.java"
click node_service_registry "https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/service/Service.java"
click node_query_cache_writer "https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/sql/results/caching/internal/QueryCachePutManagerEnabledImpl.java"
click node_timezone_mapping "https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/annotations/TimeZoneStorageType.java"
click node_agroal_provider "https://github.com/hibernate/hibernate-orm/blob/main/hibernate-agroal/src/main/java/org/hibernate/agroal/internal/AgroalConnectionProvider.java"
click node_c3p0_provider "https://github.com/hibernate/hibernate-orm/blob/main/hibernate-c3p0/src/main/java/org/hibernate/c3p0/internal/C3P0ConnectionProvider.java"

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_query_engine,node_query_options,node_query_api toneBlue
class node_community_resolver,node_community_translators,node_database_service,node_relational_db toneAmber
class node_session_factory,node_event_engine,node_service_registry,node_query_cache_writer,node_query_cache,node_timezone_mapping toneMint
class node_agroal_provider,node_c3p0_provider,node_jdbc toneRose
class node_application toneIndigo
```

## Components

### Query processing

- [Query engine](https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/query/internal/QueryEngineImpl.java): `hibernate-core/src/main/java/org/hibernate/query/internal/QueryEngineImpl.java`
- [Query options](https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/query/spi/QueryEngineOptions.java): `hibernate-core/src/main/java/org/hibernate/query/spi/QueryEngineOptions.java`
- [Query engine API](https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/query/spi/QueryEngine.java): `hibernate-core/src/main/java/org/hibernate/query/spi/QueryEngine.java`

### Database support

- [Dialect resolver](https://github.com/hibernate/hibernate-orm/blob/main/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/CommunityDialectResolver.java): `hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/CommunityDialectResolver.java`
- [Dialect translators](https://github.com/hibernate/hibernate-orm/tree/main/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect): `hibernate-community-dialects/src/main/java/org/hibernate/community/dialect`
- **JDBC services**
- **Relational database**

### ORM runtime

- [Session factory builder](https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/boot/internal/DefaultSessionFactoryBuilderService.java): `hibernate-core/src/main/java/org/hibernate/boot/internal/DefaultSessionFactoryBuilderService.java`
- [Event engine](https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/event/spi/EventEngine.java): `hibernate-core/src/main/java/org/hibernate/event/spi/EventEngine.java`
- [Service registry](https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/service/Service.java): `hibernate-core/src/main/java/org/hibernate/service/Service.java`
- [Query cache writer](https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/sql/results/caching/internal/QueryCachePutManagerEnabledImpl.java): `hibernate-core/src/main/java/org/hibernate/sql/results/caching/internal/QueryCachePutManagerEnabledImpl.java`
- **Query results cache**
- [Time-zone mapping](https://github.com/hibernate/hibernate-orm/blob/main/hibernate-core/src/main/java/org/hibernate/annotations/TimeZoneStorageType.java): `hibernate-core/src/main/java/org/hibernate/annotations/TimeZoneStorageType.java`

### Connection providers

- [Agroal provider](https://github.com/hibernate/hibernate-orm/blob/main/hibernate-agroal/src/main/java/org/hibernate/agroal/internal/AgroalConnectionProvider.java): `hibernate-agroal/src/main/java/org/hibernate/agroal/internal/AgroalConnectionProvider.java`
- [C3P0 provider](https://github.com/hibernate/hibernate-orm/blob/main/hibernate-c3p0/src/main/java/org/hibernate/c3p0/internal/C3P0ConnectionProvider.java): `hibernate-c3p0/src/main/java/org/hibernate/c3p0/internal/C3P0ConnectionProvider.java`
- **JDBC connections**

### Other components

- **Java application**

## Connections

- Java application → Query engine API: submits queries
- Query engine API → Query engine: delegates to
- Query engine → Query options: uses options
- Query engine → JDBC services: gets dialect
- Dialect resolver → Dialect translators: selects dialect
- Query engine → Dialect translators: translates queries
- Dialect translators → Relational database: produces SQL
- Session factory builder → Event engine: builds runtime
- Event engine → Service registry: loads contributors
- Query cache writer → Query results cache: writes results
- Agroal provider → JDBC connections: provides connections
- C3P0 provider → JDBC connections: provides connections
- JDBC connections → Relational database: connects to
- Time-zone mapping → Relational database: maps temporal data