ekbatan AGENTS.md

Agents Guide

This document provides detailed architectural context for AI agents working on the Ekbatan codebase.

Project Overview

Ekbatan is a Java persistence and action framework built as an alternative to Spring Data. It is a library, not a standalone application. Its central idea is that in most business applications, you don't just want to save data — you want to save what happened alongside the data itself, atomically, so that the database always tells a complete and consistent story.

The framework is structured around the concept of an Action — a unit of business work. An Action doesn't write anything to the database directly. Instead, it declares its intent: what should be created, what should be updated. These declarations accumulate in an ActionPlan — a staging area that holds all planned changes without touching the database. Only after the action's logic completes successfully does the ActionExecutor step in, open a single database transaction, and flush everything at once: the domain objects to their tables, and the event records to the eventlog schema. If any part fails, nothing is written. This all-or-nothing guarantee means the eventlog.events table naturally becomes a reliable outbox — a stream of committed business facts that can be tailed by a CDC connector or polled and forwarded to Kafka, Pulsar, or any message broker, enabling event-driven architectures without dual-write problems.

The framework draws a deliberate line between two kinds of persistent objects. A Model is a domain aggregate whose changes matter — every mutation produces a ModelEvent that gets persisted in the eventlog alongside the action that caused it. You extend Model when downstream systems need to know what happened: a wallet was created, money was deposited, an order was shipped. An Entity is simpler — it gets persisted and version-tracked, but its changes are not recorded as events. You extend Entity for supporting data where the history of individual mutations is irrelevant: lookup tables, configuration records, auxiliary references that participate in an action but don't need their own event trail.