Home

Evento Framework Wiki

Evento is a Java framework for building distributed, event-sourced CQRS systems on the RECQ (Reactive, Event-driven Commands & Queries) architecture pattern.

This wiki is the engineering reference: how the framework is built, why it is built that way, and what an operator needs to know to run it. For tutorials, API guides and the getting-started path, see the user documentation at docs.eventoframework.com.

Current release	v2.4.0
Toolchain	JDK 25 · Gradle 9.6.1 · Spring Boot 4.1.0
Licence	AGPL-3.0 or commercial — see LICENSE.txt
Artifacts	Maven Central · Docker Hub

---

The two runtime components

Component	Role
Evento Server	Central broker — bundle registry, event store, command routing, query routing, performance store
Evento Bundle	Application unit — hosts domain components (@Aggregate, @Projector, @Saga, @Service, @Observer, @Projection, @Invoker) and connects to the server over TCP

Bundles register their handler types with the server at startup. All inter-bundle communication — commands, queries, events — flows through the server broker; bundles never talk directly to each other.

---

Start here

• New to the codebase? → Architecture Overview
• Writing your first bundle? → Getting Started
• Running Evento in production? → Server Configuration, Throughput and Capacity, Observability
• Coming from v1? → Migrating from v1
• Contributing? → Building and Testing, Contributing and Conventions

---

Page index

Concepts and internals

Page	What it covers
Architecture Overview	Module map, layer boundaries, the ten load-bearing design decisions
Wire Protocol	CBOR framing, the sealed Message hierarchy, chunking, the handshake
Server Bus	BusLifecycle and the registries, routing, correlation, exactly-once QoS
Bundle Client	Client state machine, reconnect, inbound dispatch, dedup
Consumer Engines	Projector / saga / observer engines and the five consumer SPIs
Parallel Consumers	Opt-in parallel consumption, what it trades away, and how to buy it back
Consumer State Store	JDBC schema, locking, and connection-pool sizing

Operations

Page	What it covers
Server Configuration	Spring properties, Docker image, deployment shape
Throughput and Capacity	The capacity model, congestion collapse, and the detection playbook
Observability	Micrometer meters, health checks, structured log events
Security Model	Handshake authentication, TLS, deserialization hardening, REST auth
Server REST API	Controller surface behind the GUI
Troubleshooting	Symptom-first index of the known failure modes

Project

Page	What it covers
Building and Testing	Toolchain, the full test command, integration-test harnesses
Contributing and Conventions	Commit format, code conventions, PR process
Migrating from v1	Everything that broke in 2.0 and what replaced it
Release History	Version timeline and what each release introduced
Glossary	Terms used throughout the framework and this wiki

---

Where the sources of truth live

This wiki summarises and organises material maintained in the repository. When the two disagree, the repository wins:

Topic	Authoritative file
Architecture, design decisions, conventions	.claude/ARCHITECTURE.md
Release-by-release changes	CHANGELOG.md
Contribution process	CONTRIBUTING.md
Security policy and disclosure	SECURITY.md
Governance and maintainers	GOVERNANCE.md · MAINTAINERS.md

---

Getting help

• Questions and usage help → SUPPORT.md
• Bugs and feature requests → Issues
• Security vulnerabilities → do not open an issue; follow SECURITY.md