# axoniq/axonframework architecture

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

- Interactive diagram: https://gitdiagram.com/axoniq/axonframework
- Repository: https://github.com/axoniq/axonframework

## Overview

Axon Framework supplies building blocks for event-driven, CQRS, and event-sourced applications. A representative query workflow starts with an application issuing a query, which is handled through query messaging; event-sourced models use repositories and state management, with events persisted by an event store. The README also describes command, event, saga, and distributed messaging capabilities, though the supplied tree does not expose their implementation paths. The graph combines documented capabilities with sampled module evidence; dashed, uncited links indicate relationships not verified in the excerpts.

Main entry points: [`messaging/src/main/java/org/axonframework/messaging/queryhandling/gateway/QueryGateway.java`](https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/queryhandling/gateway/QueryGateway.java) (Query gateway), [`messaging/src/main/java/org/axonframework/messaging/queryhandling/QueryHandlerRegistry.java`](https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/queryhandling/QueryHandlerRegistry.java) (Query registry), [`eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/StorageEngineBackedEventStore.java`](https://github.com/axoniq/axonframework/blob/main/eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/StorageEngineBackedEventStore.java) (Event store), [`messaging/src/main/java/org/axonframework/messaging/core/Message.java`](https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/core/Message.java) (Message model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_messaging["Messaging"]
  node_querygateway["Query gateway<br/>[QueryGateway.java]"]
  node_querymessage["Query message<br/>[QueryMessage.java]"]
  node_queryregistry["Query registry"]
  node_querydefinition["Query definitions"]
  node_queryinterceptor["Query interception"]
  node_monitoring["Query monitoring"]
  node_message["Message model<br/>[Message.java]"]
  node_stream["Message streams<br/>[MessageStream.java]"]
  node_context["Processing context"]
  node_commands["Command handling"]
  node_distributed["Distributed buses"]
end

subgraph group_model["Model handling"]
  node_repository["Entity repository"]
  node_state["State manager<br/>[StateManager.java]"]
  node_sagas["Saga handling"]
end

subgraph group_events["Event sourcing"]
  node_eventmessage["Event messages<br/>[EventMessage.java]"]
  node_eventstore["Event store"]
  node_storageengine["Storage engine"]
  node_jpastorage[("JPA storage")]
  node_appendcondition["Append conditions"]
  node_trackingtoken["Tracking tokens<br/>[TrackingToken.java]"]
end

subgraph group_foundation["Framework foundation"]
  node_configuration["Configuration<br/>[Configuration.java]"]
  node_descriptor["Component description"]
  node_type["Type references<br/>[TypeReference.java]"]
end

node_app(("Application"))

node_app -.->|"issues query"| node_querygateway
node_querygateway -.->|"creates message"| node_querymessage
node_querygateway -.->|"dispatches query"| node_queryregistry
node_queryregistry -.->|"resolves handlers"| node_querydefinition
node_queryregistry -.->|"intercepts handling"| node_queryinterceptor
node_queryinterceptor -->|"applies monitoring"| node_monitoring
node_querymessage -->|"extends"| node_message
node_message -->|"stores in"| node_context
node_stream -->|"streams entries"| node_message
node_state -->|"registers and loads"| node_repository
node_repository -.->|"uses for sourcing"| node_eventstore
node_eventstore -->|"delegates storage"| node_storageengine
node_storageengine -->|"checks append"| node_appendcondition
node_jpastorage -->|"implements"| node_storageengine
node_eventstore -.->|"stores events"| node_eventmessage
node_trackingtoken -->|"exposes position in"| node_context
node_configuration -.->|"describes components"| node_descriptor
node_app -.->|"sends commands"| node_commands
node_app -.->|"uses sagas"| node_sagas
node_distributed -.->|"can distribute buses"| node_querygateway

click node_querygateway "https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/queryhandling/gateway/QueryGateway.java"
click node_querymessage "https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/queryhandling/QueryMessage.java"
click node_queryregistry "https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/queryhandling/QueryHandlerRegistry.java"
click node_querydefinition "https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/queryhandling/annotation/MethodQueryHandlerDefinition.java"
click node_queryinterceptor "https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/queryhandling/interception/QueryMessageHandlerInterceptorChain.java"
click node_monitoring "https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/monitoring/interception/MonitoringQueryHandlerInterceptor.java"
click node_message "https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/core/Message.java"
click node_stream "https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/core/MessageStream.java"
click node_context "https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/core/unitofwork/ProcessingContext.java"
click node_repository "https://github.com/axoniq/axonframework/blob/main/modelling/src/main/java/org/axonframework/modelling/repository/SimpleRepository.java"
click node_state "https://github.com/axoniq/axonframework/blob/main/modelling/src/main/java/org/axonframework/modelling/StateManager.java"
click node_eventmessage "https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/eventhandling/EventMessage.java"
click node_eventstore "https://github.com/axoniq/axonframework/blob/main/eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/StorageEngineBackedEventStore.java"
click node_storageengine "https://github.com/axoniq/axonframework/blob/main/eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/EventStorageEngine.java"
click node_jpastorage "https://github.com/axoniq/axonframework/blob/main/eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/jpa/AggregateBasedJpaEventStorageEngine.java"
click node_appendcondition "https://github.com/axoniq/axonframework/blob/main/eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/AppendCondition.java"
click node_trackingtoken "https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/eventhandling/processing/streaming/token/TrackingToken.java"
click node_configuration "https://github.com/axoniq/axonframework/blob/main/common/src/main/java/org/axonframework/common/configuration/Configuration.java"
click node_descriptor "https://github.com/axoniq/axonframework/blob/main/common/src/main/java/org/axonframework/common/infra/ComponentDescriptor.java"
click node_type "https://github.com/axoniq/axonframework/blob/main/common/src/main/java/org/axonframework/common/TypeReference.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_querygateway,node_querymessage,node_queryregistry,node_querydefinition,node_queryinterceptor,node_monitoring,node_message,node_stream,node_context,node_commands,node_distributed toneBlue
class node_repository,node_state,node_sagas toneAmber
class node_eventmessage,node_eventstore,node_storageengine,node_jpastorage,node_appendcondition,node_trackingtoken toneMint
class node_configuration,node_descriptor,node_type toneRose
class node_app toneIndigo
```

## Components

### Messaging

- [Query gateway](https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/queryhandling/gateway/QueryGateway.java): `messaging/src/main/java/org/axonframework/messaging/queryhandling/gateway/QueryGateway.java`
- [Query message](https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/queryhandling/QueryMessage.java): `messaging/src/main/java/org/axonframework/messaging/queryhandling/QueryMessage.java`
- [Query registry](https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/queryhandling/QueryHandlerRegistry.java): `messaging/src/main/java/org/axonframework/messaging/queryhandling/QueryHandlerRegistry.java`
- [Query definitions](https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/queryhandling/annotation/MethodQueryHandlerDefinition.java): `messaging/src/main/java/org/axonframework/messaging/queryhandling/annotation/MethodQueryHandlerDefinition.java`
- [Query interception](https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/queryhandling/interception/QueryMessageHandlerInterceptorChain.java): `messaging/src/main/java/org/axonframework/messaging/queryhandling/interception/QueryMessageHandlerInterceptorChain.java`
- [Query monitoring](https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/monitoring/interception/MonitoringQueryHandlerInterceptor.java): `messaging/src/main/java/org/axonframework/messaging/monitoring/interception/MonitoringQueryHandlerInterceptor.java`
- [Message model](https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/core/Message.java): `messaging/src/main/java/org/axonframework/messaging/core/Message.java`
- [Message streams](https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/core/MessageStream.java): `messaging/src/main/java/org/axonframework/messaging/core/MessageStream.java`
- [Processing context](https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/core/unitofwork/ProcessingContext.java): `messaging/src/main/java/org/axonframework/messaging/core/unitofwork/ProcessingContext.java`
- **Command handling**
- **Distributed buses**

### Model handling

- [Entity repository](https://github.com/axoniq/axonframework/blob/main/modelling/src/main/java/org/axonframework/modelling/repository/SimpleRepository.java): `modelling/src/main/java/org/axonframework/modelling/repository/SimpleRepository.java`
- [State manager](https://github.com/axoniq/axonframework/blob/main/modelling/src/main/java/org/axonframework/modelling/StateManager.java): `modelling/src/main/java/org/axonframework/modelling/StateManager.java`
- **Saga handling**

### Event sourcing

- [Event messages](https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/eventhandling/EventMessage.java): `messaging/src/main/java/org/axonframework/messaging/eventhandling/EventMessage.java`
- [Event store](https://github.com/axoniq/axonframework/blob/main/eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/StorageEngineBackedEventStore.java): `eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/StorageEngineBackedEventStore.java`
- [Storage engine](https://github.com/axoniq/axonframework/blob/main/eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/EventStorageEngine.java): `eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/EventStorageEngine.java`
- [JPA storage](https://github.com/axoniq/axonframework/blob/main/eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/jpa/AggregateBasedJpaEventStorageEngine.java): `eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/jpa/AggregateBasedJpaEventStorageEngine.java`
- [Append conditions](https://github.com/axoniq/axonframework/blob/main/eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/AppendCondition.java): `eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/AppendCondition.java`
- [Tracking tokens](https://github.com/axoniq/axonframework/blob/main/messaging/src/main/java/org/axonframework/messaging/eventhandling/processing/streaming/token/TrackingToken.java): `messaging/src/main/java/org/axonframework/messaging/eventhandling/processing/streaming/token/TrackingToken.java`

### Framework foundation

- [Configuration](https://github.com/axoniq/axonframework/blob/main/common/src/main/java/org/axonframework/common/configuration/Configuration.java): `common/src/main/java/org/axonframework/common/configuration/Configuration.java`
- [Component description](https://github.com/axoniq/axonframework/blob/main/common/src/main/java/org/axonframework/common/infra/ComponentDescriptor.java): `common/src/main/java/org/axonframework/common/infra/ComponentDescriptor.java`
- [Type references](https://github.com/axoniq/axonframework/blob/main/common/src/main/java/org/axonframework/common/TypeReference.java): `common/src/main/java/org/axonframework/common/TypeReference.java`

### Other components

- **Application**

## Connections

- Application → Query gateway: issues query
- Query gateway → Query message: creates message
- Query gateway → Query registry: dispatches query
- Query registry → Query definitions: resolves handlers
- Query registry → Query interception: intercepts handling
- Query interception → Query monitoring: applies monitoring (evidence: `messaging/src/main/java/org/axonframework/messaging/monitoring/interception/MonitoringQueryHandlerInterceptor.java`)
- Query message → Message model: extends (evidence: `messaging/src/main/java/org/axonframework/messaging/queryhandling/QueryMessage.java`)
- Message model → Processing context: stores in (evidence: `messaging/src/main/java/org/axonframework/messaging/core/Message.java`)
- Message streams → Message model: streams entries (evidence: `messaging/src/main/java/org/axonframework/messaging/core/MessageStream.java`)
- State manager → Entity repository: registers and loads (evidence: `modelling/src/main/java/org/axonframework/modelling/StateManager.java`)
- Entity repository → Event store: uses for sourcing
- Event store → Storage engine: delegates storage (evidence: `eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/EventStorageEngine.java`)
- Storage engine → Append conditions: checks append (evidence: `eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/EventStorageEngine.java`)
- JPA storage → Storage engine: implements (evidence: `eventsourcing/src/main/java/org/axonframework/eventsourcing/eventstore/jpa/AggregateBasedJpaEventStorageEngine.java`)
- Event store → Event messages: stores events
- Tracking tokens → Processing context: exposes position in (evidence: `messaging/src/main/java/org/axonframework/messaging/eventhandling/processing/streaming/token/TrackingToken.java`)
- Configuration → Component description: describes components
- Application → Command handling: sends commands (evidence: `README.md`)
- Application → Saga handling: uses sagas (evidence: `README.md`)
- Distributed buses → Query gateway: can distribute buses (evidence: `README.md`)