A CQRS / event-sourced reference application you can watch work — and a demonstration of an agent-assisted, spec-driven way to build it.
It is not a toy CRUD app. It is a complete event-sourced system: schedule a showcase and it drives itself through its lifecycle — starting at the right time, finishing after its duration, streaming every event live to a browser UI that updates as it happens. And the way the code is written and reviewed is itself a demonstration: behavior is captured in specs, changes are proposed, applied, reviewed, and archived by an automated agent pipeline. That pipeline also learns from itself: every unit records the process defects it observes, and you turn those records into rules when they are due. The pipeline reads those rules on the next change (see The Self-Learning Loop). It can even bootstrap its own tooling — ask it to set up the MCP servers and it detects, wires, and installs what it can for you (see Tooling MCP Servers).
It is a reference application, not a supported product: there is no security team and no response-time commitment (SECURITY.md), the gateway accepts unauthenticated requests by design, and the projection is best-effort at its edges — a terminal item failure loses the fields that event carried (ADR-0022). Treat the design as something to learn from and copy, and bring your own authentication, secrets, and failure handling before running it for anyone else.
It is also a personal vehicle for learning agentic development: the process is as much the point as the product.
axon-showcase/
├── Services and gateway
│ ├── showcase-api-gateway/ # REST (/showcases), SSE (/events), client telemetry (/telemetry)
│ ├── showcase-command-service/ # Write side: Axon aggregate, saga, distributed bus
│ ├── showcase-projection-service/ # Consumes Kafka, writes read models to OpenSearch
│ ├── showcase-query-service/ # Read side: queries OpenSearch, gRPC query transport
│ └── showcase-web-ui/ # Standalone browser UI (React + Vite, Feature-Sliced Design)
├── API and clients
│ ├── showcase-command-api/ # Command-side API interfaces
│ ├── showcase-command-client/ # Reactive command client
│ ├── showcase-query-api/ # Query-side API interfaces
│ ├── showcase-query-client/ # Reactive query client
│ └── showcase-query-proto/ # Protobuf + gRPC definitions for queries
├── Shared libraries
│ ├── showcase-projection-model/ # Shared query model definitions
│ ├── showcase-identifier-extension/ # KSUID identifier support
│ ├── showcase-mapstruct-extension/ # MapStruct extensions
│ ├── showcase-resilience4j-extension/ # Resilience4j integration
│ └── showcase-test/ # Shared test utilities
├── Build and deployment
│ ├── build-logic/ # Gradle convention plugins
│ ├── gradle/ # Version catalog (libs.versions.toml)
│ ├── platform/ # Shared BOM and dependency management
│ ├── helm/ # Helm charts for Kubernetes deployment
│ │ └── chart/ # Main chart for the application
│ ├── docker-compose.yml # Local development with Docker Compose
│ └── load-tests/ # Gatling-based load tests
├── Documentation and process
│ ├── docs/adr/ # Architecture decision records
│ └── openspec/ # Spec-driven behavior specs and changes
├── Scripts
│ ├── db.sh # Database setup (init / drop / reset)
│ ├── setup-hosts.sh # Manage /etc/hosts entries for the local ingress
│ └── scripts/ # Dev tooling: checkers, dev scripts, and guards
The domain is deliberately simple — a "showcase" is a scheduled, timed event with a lifecycle. The value is in what the plumbing does with it:
flowchart TB
SCHEDULED([SCHEDULED]) -->|"user: start"| STARTED([STARTED])
SCHEDULED -.->|"saga deadline: startTime"| STARTED
STARTED -->|"user: finish"| FINISHED([FINISHED])
STARTED -.->|"saga deadline: +duration"| FINISHED
SCHEDULED -->|"user: remove"| REMOVED([REMOVED])
STARTED -->|"user: remove<br/>(finishes first)"| REMOVED
FINISHED -->|"user: remove"| REMOVED
Plain-text version (for renderers without Mermaid)
┌───────────────┐
│ SCHEDULED │───────────────┐
└───────┬───────┘ │
│ user: start │
│ ┄ saga: startTime │
┌───────────────┐ │
│ STARTED │───────────────┤
└───────┬───────┘ │
│ user: finish │
│ ┄ saga: +duration │
┌───────────────┐ │
│ FINISHED │───────────────┤
└───────────────┘ │
│ user: remove
│ (a started showcase is
│ finished before removal)
┌───────────────────────┘
▼
┌───────────────┐
│ REMOVED │
└───────────────┘
You can also drive the lifecycle by hand — start or finish a showcase before the saga does, or remove it at any time.
- The saga runs the show. When you schedule a showcase, an Axon saga (in
ShowcaseSaga) sets a deadline to start it at the scheduled time, then another to finish it after the configured duration. You can schedule a showcase and literally watch it auto-start and auto-finish without touching anything. - Everything is an event. Every transition is an Axon domain event, stored in the PostgreSQL event store, published
to Kafka, projected into OpenSearch, and streamed live to browsers over SSE (
/events). - The command side scales. The command service runs a distributed command bus (JGroups). In the local deployment its two replicas and the API gateway form one JGroups cluster — peers discover each other through the Kubernetes API (KUBE_PING) and commands route across all nodes — so the write side scales out like a real system. Every service can be autoscaled (HPA/VPA) and protected with Pod Disruption Budgets.
- The read side speaks gRPC. The gateway reads through the query service over a generic gRPC RPC — one method
carries any query, and the query service dispatches it on its own
QueryBus. It fills the distributed-query-bus role without Axon Server (seedocs/adr/0017), just as the command side uses a JGroups command bus. - A real browser UI shows it live. The React UI renders the event timeline, listens to the SSE stream, and reconciles against the eventually consistent read model — so you see the saga's transitions appear live.
- Resilience is built in. The command and query clients apply Resilience4j circuit breakers, time limiters, and retries, and the gateway serves repeated reads from a read-through cache.
- It is observable. Tempo traces, Prometheus metrics (including web-UI nginx metrics), a dedicated Grafana
dashboard, health checks, and Gatling load tests are wired in — the same observability a production service needs. The
projection service exposes its observed lifecycle state, last resolved batch time, and outstanding consumer backlog
(
showcaseProjector.state, and a backlog sampled by its own admin client so a consumer that stopped polling is still measured); readiness reportsDOWNbefore initial assignment and during stream-restart waits, and can remainUPwhile Kafka is unreachable after assignment. Observability is available in the Kubernetes deployment (Prometheus, Grafana, and Tempo run in themonitoringnamespace); the local docker-compose stack runs without it. - Identifiers are KSUIDs (sortable, collision-resistant), enforced through a custom identifier extension.
The application follows CQRS (Command Query Responsibility Segregation) with four services and the web UI:
| Component | Role |
|---|---|
| API Gateway | REST entry point (/showcases), SSE live events (/events), client telemetry (/telemetry) |
| Command Service | Write side: Axon aggregate, saga, distributed command bus (JGroups), PostgreSQL event store |
| Projection Service | Consumes events from Kafka, writes read models to OpenSearch |
| Query Service | Read side: queries OpenSearch, gRPC query transport |
flowchart TB
Client([Client])
GW[API Gateway]
CS[Command Service]
Kafka[(Kafka)]
PS[Projection Service]
OS[(OpenSearch)]
PG[(PostgreSQL<br/>event store)]
QS[Query Service]
Client -->|"POST /showcases"| GW
GW -->|command| CS
CS -->|events| Kafka
CS -.->|persists| PG
Kafka -->|events| PS
Kafka -.->|"events for SSE"| GW
PS -->|"read model"| OS
GW -->|query| QS
QS -->|search| OS
GW -.->|"SSE /events"| Client
Plain-text version (for renderers without Mermaid)
┌───────────────────┐
╎╌╌╌╌╌SSE /events╌╌╌╌╌►│ Client │
╎ └───────────────────┘
╎ │ POST /showcases
╎ ▼
╎ ┌───────────────────┐
╎╌╌╌events for SSE╌╌╌╌►│ API Gateway │
╎ └───────────────────┘
╎ │
╎ ┌─────────────────┴─────────────────┐
╎ command │ │ query
╎ ▼ ▼
╎ ┌───────────────────┐ ┌───────────────────┐
╎ │ Command Service │ │ Query Service │
╎ └───────────────────┘ └───────────────────┘
╎ │ events │ search
╎ ├─────────────────────┐ │
╎ │ │ persists │
╎ ▼ ▼ │
╎ ┌───────────────────┐ ┌───────────────────┐ │
╎╌╌╌╌│ Kafka │ │ PostgreSQL │ │
└───────────────────┘ │ event store │ │
│ events └───────────────────┘ │
▼ │
┌───────────────────┐ │
│ Projection Service│ │
└───────────────────┘ │
│ read model │
└─────────────────┬─────────────────┘
▼
┌───────────────────┐
│ OpenSearch │
└───────────────────┘
A scheduled showcase flows through the whole pipeline: the command service stores the event and publishes it, the
projection service builds the read model, the query service serves it, and the gateway streams the event live to any
subscribed browser — all from one POST /showcases.
The command's answer is not the read model's. A successful POST /showcases returns 201 Created once command handling
completes; it does not wait for the read model to catch up, which the projection service builds from Kafka afterwards.
The UI leans on the difference: the live timeline appends each event the SSE stream delivers, while the list makes
bounded refetch attempts to observe their effects — so a read can briefly return the previous state, and an event can
appear in the timeline before the list catches up. Historical markers (scheduled, started, finished) come from the read
model, not from the event store.
The local stack's defaults are demonstration defaults: Compose runs with built-in credentials and with OpenSearch security disabled. Replace both before exposing the stack to anyone else, and add authentication to the gateway intake the intro describes.
- Java 21 and Spring Boot 3.5.16 (a Spring Boot 4 migration is deferred — see
docs/adr/0004) - Axon Framework — aggregates, sagas and deadlines, command/query buses, and a JGroups distributed command bus;
deliberately run without Axon Server (a project intention — see
docs/adr/0009), with queries crossing to the query service over a generic gRPC transport that fills the distributed query bus role (docs/adr/0017) - PostgreSQL — the Axon event store
- Apache Kafka — event streaming between services
- OpenSearch — the read-side projection store
- React + Vite + TypeScript — web UI (TanStack Query, Redux Toolkit, React Hook Form + Zod, Vitest, Playwright), Feature-Sliced Design
- KSUID identifiers, MapStruct mapping, Resilience4j resilience, Protobuf + gRPC inter-service queries
- Helm + Kubernetes — deployment (HPA/VPA/PDB, network policies, ingress)
- Prometheus / Grafana / Tempo — metrics, a custom observability dashboard, and distributed tracing (in the Kubernetes deployment)
- Gatling — load tests
- Gradle (Kotlin DSL) with build-logic convention plugins and a version catalog
- Spotless — palantir-java-format for Java, ktfmt for Kotlin/Gradle DSL, Prettier for markdown
- Checkstyle, SpotBugs, ErrorProne (NullAway + JSpecify), JaCoCo coverage gate — all in
check, no IDE required (the web UI has its own Vitest coverage gate) - actionlint — lints the GitHub Actions workflows
- Snyk and
npm audit— dependency security scanning (JVM classpaths and web-UI npm packages); gitleaks — a source-secret scan in the merge gate - OpenSpec — spec-driven behavior capture (
propose → apply → archive) - OpenCode — the agentic coding tool driving the process: slash-commands, spec-aware subagents, a self-learning loop that records process defects and generalizes them, on-request setup of its own tooling (Tooling MCP Servers), and a project practice of reporting a dependency's gap back upstream — with a reproduction — instead of only working around it
- GitHub Actions — CI (with a gitleaks source-secret scan), e2e, dependency, Helm, buildpack and tooling updates, security scans
Just want to run the project? Skip to Getting Started.
Work is organized into units of work: one branch, intended for one pull request. The unit lifecycle is the enclosing
process; an OpenSpec change is one form a unit may take. Behavior is captured in openspec/specs/ (the behavioral
source of truth) and changes are planned under openspec/changes/. AGENTS.md owns the lifecycle model, the entry
points to its stage procedures, and the repository's conventions — read it before contributing.
On the normal proposal-led route, a unit follows Begin → Plan → Proposal review → Implement → Implementation review →
Deliver → Settle. Discussion alone does not start a unit: the owner authorizes the work. The lifecycle also covers
units without an OpenSpec change directory, which have no archive step; its exceptional routes, including work
authorized as named direct edits, are described in AGENTS.md.
The nested OpenSpec path. For a unit carrying a change, planning runs in Plan, applying in Implement, and archiving in Deliver. The diagram below shows that change path — not the whole unit lifecycle:
flowchart TB
subgraph r1[" "]
direction LR
Idea --> Explore --> Propose
end
subgraph r2[" "]
direction LR
Apply -->|"ship"| PR -->|"CI"| Archive
end
subgraph r3[" "]
direction LR
Merge
end
r1 -->|"approve"| r2
r2 -->|"spec → main"| r3
style r1 fill:none,stroke:none
style r2 fill:none,stroke:none
style r3 fill:none,stroke:none
Plain-text version (for renderers without Mermaid)
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Idea │───────────►│ Explore │───────────►│ Propose │
└─────────┘ └─────────┘ └─────────┘
│ approve
▼─────────────────────────────────────────────┘
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Apply │────ship───►│ PR │─────CI────►│ Archive │
└─────────┘ └─────────┘ └─────────┘
│ spec → main
▼──────────────────────┘
┌─────────┐
│ Merge │
└─────────┘
Within Plan, an OpenSpec change captures the proposal (what and why), a capability-scoped spec delta, a design (how), and tasks; within Implement, applying follows the approved tasks to produce and verify the implementation. A unit without a change directory plans and implements without those OpenSpec artifacts.
At each review boundary the unit has, an auto-review (the review-quick subagent, repeated until it finds nothing
new) precedes your manual review; the review gate decides whether a deep review-thorough pass is also required.
You review the proposal before implementation and the finished work before delivery; the lifecycle's named-direct-edit
route skips the proposal review and keeps the implementation one. Before your manual review the agent refreshes the
branch against origin/main so you read the diff against current main, and stages the unit's new files so they appear
in your IDE's Changes panel. What the reviews produce stays in the unit's own record as one event sequence:
sessions.tsv orders every stateful review invocation, rounds.tsv and findings/ beside it keep the quick loop's
outcome and what each round found, and deep-review.md holds the deep review's routing decision, its passes, and its
findings' statuses.
The unit is intended to ship in one PR; a draft PR can share the plan after the proposal review. Implementation
approval alone does not start delivery — the owner must also request it. During Deliver, the agent publishes the
work and follows CI: a unit carrying a change directory is archived after green CI and before the merge, as a commit in
the same PR (the directory moves to openspec/changes/archive/ and its delta specs are folded into the main specs),
while a unit without one skips that step. So the main spec always describes behavior the code has been verified against.
Merge is followed by Settle, which accounts for the outcome and the remaining work before the workspace is released.
A vague idea is usually sharpened first in explore mode (/opsx-explore) — a thinking stance that investigates the
codebase and clarifies what to build, without writing code. Only when the idea is concrete enough does it become a
proposal.
The lifecycle is iterative, not a strict pipeline: a material scope change returns the unit through the planning and
approval boundary it invalidates. A question in review can send you back to the proposal, a realization
mid-implementation to the spec delta; the agent revises the affected artifacts (/opsx-update reworks a change's
planning artifacts) and re-verifies. The archive is a snapshot of the verified change, not the end of a one-way flow.
The specs are organized by architectural role (gateway, write-side, read-side, clients, extensions,
deployment, quality) — a capability spec per capability, grouped into these role areas, covering everything from the
REST API and the event pipeline to the identifier extension and the dependency-management policy. Every implemented
change is archived under openspec/changes/archive/, so the spec structure itself tells the project's history: the main
spec is always in sync with behavior the code has been verified against, and a change's delta spec shows what a specific
feature introduced.
The corpus is kept mutually consistent by the specs-auditor subagent (/audit-specs, on demand), which reports the
structural drift openspec validate does not catch — a dead reference or a duplicate — with its evidence line and a
suggested rewrite, and never edits the specs itself.
Emerging ideas are parked in docs/ideas.md — a lightweight, date-grouped scratchpad (ideas are added via /ideas,
promoted by name or --top to an issue, or implemented as a change when the work is ready now, pruned in batches via
/ideas cleanup, and removed once implemented or decided against) rather than a backlog of planned work. A parked idea
is the usual starting point for an explore session that decides whether it deserves a proposal.
An idea isn't the only entry point, though: a session can start just as well from a reported issue, a failing CI job, or
any other observation — you describe it in a prompt; the agent investigates (reading the issue or the failing check
through the GitHub MCP) and proposes from there. The source of the request does not change the unit's authorization or
review boundaries; docs/ideas.md holds ideas not yet acted on — it is not a required entry point.
Cross-cutting architecture decisions and their rationale are recorded as Architecture Decision Records under
docs/adr/. OpenSpec captures what the system does and how a change is planned; ADRs capture why the system is shaped
the way it is. An architecture-auditor subagent (/audit-architecture, on demand) checks that those decisions still
describe the system — an ADR the code has outgrown, a boundary that drifted, or a decision made in code without an ADR —
and surfaces design observations separately for your judgment, including where a deliberate choice's rationale was never
written down and a deferral whose recorded condition now looks met. It resolves a disagreement between records by
authority (reporting an unresolvable one as an observation rather than a defect), judges a dependency edge only against
a recorded rule, and states no conclusion it cannot verify.
This repository is developed through a spec-first, agent-assisted workflow powered by OpenCode — an AI coding agent you drive interactively from its TUI (terminal) or Desktop app. You describe what you want in plain language, and the agent does the work: it proposes a plan, writes the code, runs the gates, reviews itself, and opens the PR. You steer and approve; the agent implements.
Talk to the agents in your own language and receive replies in it, while repository artifacts stay in English (see the
output-language convention in AGENTS.md).
It also runs on GitHub: commenting /oc … on an issue or pull request runs the same agent in GitHub Actions, where it
opens a PR (or commits to the current one) — the remote path to the same workflow, so a phone comment can start a
change.
The repo's .opencode/ config pins most agents to opencode-go/* models, available through an OpenCode Go
subscription — and the vision agent is pinned to opencode-go/claude-haiku-5-5, a multimodal model on that plan. The
technical-advisor is the exception: it is pinned to openai/gpt-6.1-sol#high (see
OpenAI sign-in for /consult). Install OpenCode (see Prerequisites),
subscribe, and /connect to it to follow along with the worked scenarios.
Two upstream skill sets are vendored under .opencode/skills/ and load on demand: the AxonIQ Axon 4→5 migration
recipes, and ast-grep's structural-search skill, which the agent reaches
for when a question is about code shape — a method annotated @Test that also calls block(), a class annotated
@ConfigurationProperties — while rg keeps answering searches for text, identifiers, and paths.
The OpenCode agents under .opencode/agent/ form a layered quality pipeline:
| Agent | Role |
|---|---|
experience-analyzer |
Periodic retrospectives that root-cause failures, evaluate the previous window, and propose verified improvements (system & process) — /retrospective |
agents-auditor |
Audits the project-owned agent tooling for drift, duplication, and the always-loaded instruction budget — /audit-agents |
specs-auditor |
Audits the openspec/specs/ corpus for structure & consistency — /audit-specs |
architecture-auditor |
Audits the architecture (ADRs + boundaries + spec decomposition) for drift, unrecorded intent, and a deferral whose condition is due — /audit-architecture |
readme-auditor |
Audits the human-facing README for accuracy, design-intent fidelity, grammatical correctness, and human-visible-capability coverage — /audit-readme |
lesson-capture |
Turns process-defect records into rules, merging into the owning destination rather than accreting — /generalize-process-defects |
review-quick |
Fast bounded screen after proposal & implementation, repeated until clean (automatic) |
review-thorough |
Deep risk-routed review (drift, correctness, architecture) — the review gate's routing decision, or /review-thorough |
technical-advisor |
Independent technical consultation on a decision question — read-only, advisory, and on demand via /consult |
vision |
Structured visual review of screenshots and diagram renders for the text-only main agent |
diagrammer |
Draws/fixes ASCII and Mermaid diagrams with the pro model and returns a visual-review handoff for a Mermaid render, which /diagram has vision inspect |
Independent consultation. The technical-advisor evaluates a proposal, implementation, disagreement, or next step
and recommends a direction — for example,
/consult should the projection service batch writes or write one event at a time?. It runs read-only in a fresh child
session with a focused handoff; a follow-up on the same decision continues that session. Its default reasoning effort is
high; ask for xhigh explicitly to raise it. This advisor configuration is supported on OpenCode V2; V1 does not
enforce its permissions field or interpret the provider/model#variant effort selection equivalently. The invocation
contract is .opencode/commands/consult.md.
The technical advisor uses the openai provider, which is separate from the OpenCode Go plan the other agents use.
OpenCode supports two OpenAI sign-in routes; connect one with /connect (or opencode auth login openai) and choose
the ChatGPT sign-in or API-key method your installed version lists.
| Route | What it uses | When to choose it |
|---|---|---|
| ChatGPT sign-in (OAuth) | Included ChatGPT plan usage; additional ChatGPT credits where your plan offers them and connected-app credit use is enabled, after the included usage limit | First if you already have an eligible ChatGPT plan and it includes the advisor's model |
| OpenAI API key | Separately billed OpenAI API usage at standard API rates; a ChatGPT subscription does not include API-key usage | If you do not have an eligible ChatGPT plan, or it does not include the model |
Additional ChatGPT credits are separate from OpenAI API-key billing. If your plan offers credits, ChatGPT's "Allow other apps to use credits after reaching your usage limit" setting controls whether connected applications may use them; enabling it lets a request draw on credits rather than only included usage.
The method labels are version-specific. After connecting, /models lists the catalog, but a model's presence does not
by itself prove your plan includes it; a successful call confirms access for that request, but does not establish
whether it consumed included usage or additional credits. See
Sign in with ChatGPT,
OpenCode providers — OpenAI,
OpenCode v2 provider connections, and
OpenAI authentication.
- Proposing and applying changes: the
opsx-*commands scaffold a change (proposal, design, tasks, spec delta), implement it, and prepare it for review. - Pausing and resuming a unit:
/pause-unitrecords the unit'sResume checkpointin its record atdocs/units/<unit>/unit.mdand ends the turn — nothing is committed, stashed, or torn down, so a laptop can close mid-unit, and the agent takes this route itself when it judges it cannot reliably continue the session instead of asking you to confirm each next step; the pause report hands you/resume-unit <unit>./resume-unitcontinues it later, from that session or a new one: the named unit is resolved across the repository's worktrees, and a bare invocation finds the paused units itself, continuing the only one and offering you the choice when there are several. Either way it verifies the recorded and live state, hands the writer role over, and restores whatever the unit was waiting on; the session's title becomes the unit's name, as it does when/begin-unitestablishes a unit. Continuing the same main session keeps the unit's recorded reviewer and consultation sessions; a new session records each one'sparent-session-changedreplacement and restarts it from the recorded hand-over. - Code review: every unit is auto-reviewed after its proposal and after its implementation; the quick-review loop is
a bounded screen that repeats until it finds nothing new, and each delegation is preceded by a presence check of the
round's hand-over section (
commit-hygiene.py --handover <unit>:<round>), which stops the call when the section is missing. After implementation one routing decision selects a deepreview-thoroughpass — required, recommended for an explicit resolution, or not needed — and a manual/review-thoroughrun is always available. Each deep pass and unit-bound consultation is recorded in the unit's agent-session register and reused across passes, with its hand-over written before the call; that register is the unit's review-event spine, the review ledger keeps the quick loop's outcome, and the unit'sdeep-review.mdholds the deep decision, its passes, and its findings' statuses. The quick gates still read the ledger as before; the deep budget's full passes moved to the unit's record, and no gate widened. - Recording, then generalizing: every unit records the process defects it observes in
docs/units/<unit>/process-defects.mdas it works, and/flag-process-defectadds one you report only after the agent verifies the episode, rather than taking the report on trust;/generalize-process-defectslater turns those records into rules — gotchas and conventions forAGENTS.mdor the owning subject pack, each merged into an existing bullet or reported as uncovered, the rules the work obsoletes reported as retirement candidates, and a lesson whose cause is an authoring mechanism routed to that mechanism rather than to the guidance file — so the file shrinks as well as grows, and a mistake is recorded where it can be prevented instead of only where it is read. - Retrospectives:
/retrospectivegathers the last week of PRs and the git log, plus the archived changes, the accumulated gotchas, and the process-defect records the window touched, and produces a sprint retrospective that root-causes each significant failure to the stage that could have caught it, evaluates the previous window's recommendations, and proposes improvements with a verifiable outcome. - Formatting, gates, CI, PRs: formatting and quality gates run in the build; the agent opens PRs, watches CI, and merges once green when you give the go-ahead.
Developing on this repo is mostly a prompting exercise: you tell the agent what to build, and it plans, codes, tests, reviews, and ships. You almost never edit files by hand — the manual work is deciding and approving:
- Scope and direction: what to build, and what an idea becomes.
- Approval at each step: the agent proposes; you approve the proposal and the implementation, and you give the go-ahead to ship.
- Archiving: a change is archived only after CI is green and you give the go-ahead to ship.
- Applying suggestions: retrospective improvements and generalized process rules are proposed by the agent and applied according to your judgment.
- Merging: on this repo, the owner merges PRs directly (admin) once CI is green; a non-admin follows the normal review-required flow.
Here is what implementing a feature actually looks like — say you want showcases to support a custom title color. You sit in the OpenCode TUI (or Desktop) and type:
Add a custom title color to showcases. The API should accept an optional color in the create request, the command
service should validate it, and the UI should render the title in that color.
That one prompt starts a unit. Before planning, the agent establishes the authorized unit's workspace. Then:
- Proposes (
/opsx-propose): scaffolds the change underopenspec/changes/— a proposal, design, tasks, and a spec delta that states the new behavior — then runs the quick auto-review of the plan and shows it to you. - You approve the proposal: reply "looks good", and the agent starts implementing.
- Implements (
/opsx-apply): follows the design's tasks — the new API field, the validation, the UI color — writes the code and the tests, and runs the gates (spotlessApply, the module'scheck). - Auto-reviews: after the implementation it runs the quick-review again, fixes anything it finds, and reports back what changed and what is verified.
- You review the diff: you look at the actual changes and ask for tweaks ("also validate the hex format"). The agent applies them — and if a tweak changes the intended behavior, the spec delta is reworked to match, not just the code.
- Ships: on your go-ahead it pushes a branch and opens a PR and watches CI until green.
- You approve archiving (
/opsx-archive): the change dir moves to the archive and the main spec is updated to match — as a commit in the same PR — and then the PR is merged. The feature is now part of the source of truth. On this repo the owner's merge is direct (admin); the agent only merges with your approval. After the merge, Settle accounts for the outcome and releases the workspace safely.
Throughout, the only manual work was the initial prompt and a few approvals. The agent wrote the plan, the code, the tests, and the PR; you steered.
The process is designed to learn from itself — and that is the mechanic, not a metaphor:
AGENTS.mdis the agent's persistent memory. It is loaded as instructions at the start of every session, so a lesson written there does not merely document the past — it changes how the agent behaves on the next change.- Every unit records the process defects it observes. The unit writes them down — a rule it missed, an action that
failed — to
docs/units/<unit>/process-defects.mdas it works, so nothing an implementation taught is lost to a session and your review never waits on the analysis. The improvement those records lead to is a unit of its own, which you run when they are due: it turns the records that hold up into rules the agent reads on the next change, and a record that adds nothing ends as an explicitno-change. A defect a merge alone reveals is appended to the merged unit's record, so it reaches that pass too. A defect you notice but the unit missed reaches that pass through/flag-process-defect, which records it only after the agent verifies that episode — comparing what the rule required against what happened, bounded to that episode — and reports a proven outcome: confirmed, refuted by the available evidence, or not establishable from it. - Mistakes compound into rules. The repo's strictest conventions were captured this way — archive a change in the
same PR, interrogate the premise before moving existing configuration, never
reset --harda branch carrying uncommitted work — rules that exist because a real run got them wrong once and now steer every future run. - The guidance and tooling are audited, not just appended to.
/audit-agentschecks the project-owned agent tooling (its definition owns the authoritative scope): each consistency or conciseness finding comes with its evidence line and a suggested rewrite, and the report measures the always-loaded instruction budgetAGENTS.mdconsumes in every session. Separately it reports a third-party file our usage contradicts and a meta rule that accreted with the origin that introduced it — decisions for you rather than defects — and, for an authoring-system gap that keeps producing a defect, proposes the smallest correction at the mechanism that produced it./audit-specsand/audit-architecturecheck the spec corpus and the architecture the same way, so the guidance and tooling stay consistent, concise, and affordable instead of only growing. A report's reduction candidates do not age: the standing, owner-gated/apply-audit-reductionsunit applies them under the review gate. - The human-facing README is audited too.
/audit-readmeruns an on-demand, pro-model audit ofREADME.md— its claims against the repository, its shape against the README convention, its grammar, and its coverage of what a person can actually experience — because no gate checks the showcase's content. - The audits also run unattended. A weekly
auditworkflow runs the three audits and opens a pull request with their findings, mentioning the owner so the report is not missed — the/audit-*commands remain the on-demand path. - Periodic retrospectives zoom out.
/retrospectiveturns a window of merged PRs, archived changes, and accumulated gotchas into a retrospective that traces each significant failure to its root cause and evaluates the previous window's recommendations, classifying its suggestions asprocessorsystem.
A mistake, once recorded and generalized, becomes a rule the agent follows thereafter — so the process gets a little better with every unit that teaches it something.
Part of the agent's reach comes from MCP servers — and the easiest way to set them up is to ask the agent: just
tell it to set up the tooling (or run /setup-agent-tools). It detects what you already have, wires your global config,
and installs the gh-mcp extension, handing back only what it can't do for you — like gh auth login, or installing
gh itself. Prefer this over wiring them by hand, which is fiddly and easy to get wrong.
The one to set up first is GitHub (the agent reads PRs, issues, and CI checks); Playwright is already configured
in the project, so there's nothing to set up. IntelliJ IDEA's built-in MCP server is optional: it lets the agent
work through your running IDE, and /setup-agent-tools helps you connect it.
For manual setup, the auth-bound server (GitHub) goes under the flat mcp map of your global config
(~/.config/opencode/opencode.jsonc), not the project config — a project entry can't use your credentials, and the flat
map (not the mcp.servers nesting) is what both OpenCode lines load: the 1.x agent IntelliJ IDEA's AI launches rejects
mcp.servers, and the flat map loads under both.
- Playwright (project) — the agent's browser: it drives the running web UI and captures screenshots for the
visionsubagent. It needs only Node/npx(no credentials). - GitHub — read PRs, issues, and CI checks. Run
gh auth login(the server reuses yourghcredentials), install thegh-mcpextension (gh extension install shuymn/gh-mcp), then add it to that map:"github": { "type": "local", "command": ["gh", "mcp"] }. - IntelliJ IDEA's built-in MCP server (optional, IDEA only) — gives the agent your IDE's code intelligence:
inspections, refactoring, formatting, builds, run configurations, and its debugger. It ships with the IDE and needs no
separate install; ask
/setup-agent-toolsto connect it.
MCP config is read at startup, so restart OpenCode after adding one.
A server can also fail to connect without the config changing — a laptop that wakes before the network is up is the
common case, because npx resolves the Playwright package against the registry while the connect attempt runs. A failed
server stays failed until it is repaired: /reconnect-mcp (or python3 scripts/reconnect-mcp.py) prints every server's
status without changing anything, and /reconnect-mcp --all — or one server name — reconnects the failed ones and
confirms each reached connected, without restarting OpenCode.
Begin establishes an authorized unit's workspace before its first content edit, and /begin-unit is its entry
point: the primary checkout carries the sequential unit, while a new unit takes a prepared sibling worktree beside
it — ../axon-showcase-<unit> — when the primary belongs to another unit. Each unit records the tree it owns, so
parallel work never writes into the same tree.
Settle releases that workspace only after the outcome and any remaining work are accounted for; a sibling worktree
can then be removed, and the primary checkout is handed to the next sequential unit and never removed. The workspace
safety and release rules live in AGENTS.md.
If you run the agent inside JetBrains Air, check its session model picker before submitting a session's first prompt — and again after changing agent or model: the picker may override the repository's pinned model, and nothing in the build notices a change.
| Command | What it does |
|---|---|
/opsx-propose |
Scaffolds a new change: proposal, design, tasks, and spec delta |
/opsx-apply |
Implements the change's tasks |
/opsx-archive |
Archives a completed change and syncs the main spec |
/opsx-sync |
Syncs a change's delta spec to the main spec — internal to /opsx-archive, not run standalone |
/opsx-update |
Revises a change's planning artifacts |
/opsx-explore |
Explores an idea before proposing it |
/setup-agent-tools |
Sets up the GitHub MCP, and offers the optional connection to IntelliJ IDEA's built-in MCP server |
/reconnect-mcp |
Reports every MCP server's status, or reconnects one named server or the whole failed set, verifying each reached connected — without restarting OpenCode |
/setup-idea |
Sets up the project's IntelliJ configuration (settings + formatters incl. web Prettier + Python analysis) |
/begin-unit |
Establishes a unit's workspace — the primary checkout or a prepared sibling worktree — writes its record and claim before the first content edit, and sets the session's title to the unit's name |
/check-tooling |
Checks whether this machine has the prerequisites (Java, Docker, Python, and the optional tools) |
/review-thorough |
Deep risk-routed review of a change (the review gate's routing decision, or this explicit run) |
/pause-unit |
Records the current unit's Resume checkpoint and ends the turn: no commit, stash, push, or teardown |
/resume-unit [unit] |
Continues an unfinished unit — by name, or the only paused unit it finds, or a choice among several: verifies the available state, hands the writer role over, restores what it awaited, and sets the session's title to the unit's name |
/consult |
Asks the technical advisor for an independent recommendation on a question, the current objective, or the next step |
/audit-agents |
Audits the project-owned agent tooling for drift, duplication, and the always-loaded instruction budget (pro-model auditor) |
/audit-specs |
Audits the spec corpus for structure and consistency (pro-model auditor) |
/audit-architecture |
Audits the architecture for recorded-decision drift, unrecorded intent, and a deferral whose condition is due (pro-model auditor) |
/audit-readme |
Audits the human-facing README for accuracy, design-intent fidelity, grammar, and human-visible-capability coverage (pro-model auditor) |
/apply-audit-reductions |
Applies an audit report's reduction candidates under the review gate, routing a content move to the change workflow |
/diagram |
Draws or fixes an ASCII or Mermaid diagram with the pro-model diagrammer, then visually reviews a Mermaid render with vision |
/generalize-process-defects |
Turns the accumulated process-defect records into rules and improvements, recording a decision per record |
/flag-process-defect |
Verifies a process defect the owner reports, and records it only when the episode evidence establishes it |
/retrospective |
Periodic retrospective that root-causes failures and proposes verified improvements |
/dependency-updates |
Runs and summarizes the Gradle, web-UI, and build-logic pin dependency update reports |
/gradle-update |
Updates the Gradle wrapper to the latest stable |
/dependency-security-check |
Runs the Snyk and web-UI npm dependency security scans |
/opsx-tool-update |
Regenerates the OpenSpec command/skill files after an openspec CLI release |
/ideas |
Manages docs/ideas.md: append a note, list the file, promote one entry (by name or --top), or clean up its oldest batch |
/seed-claims |
Scans the unit's diff, and the saved draft body a unit with no change dir passes with --include, for claim shapes and hands the candidates to the pre-write pass's claims table |
/sync-branch |
Checks the current branch against origin/main and, on request, refreshes it by the rule AGENTS.md states — an open pull request's branch included — resolving a local conflict for both sides |
Three ways in, depending on what you want:
- See it run — Run the Stack with Docker starts the whole system with one command, and is where most readers should start.
- Study the design — The Cool Story and Architecture need nothing installed.
- Follow the process — Development Workflow explains how a change is proposed, reviewed, and archived; OpenCode is optional for the application itself.
Most verification runs entirely in the Gradle build, so the tool list is small. Gradle itself is not on it — the wrapper pins Gradle 9.8.2 and downloads it on first use.
Run ./scripts/doctor.sh (or the agent's /check-tooling command) to check your machine: it probes each tool below,
the version floors, and the repo state, and prints the install command for anything missing on your platform. The table
is the documented list; the doctor is the mechanical check of it (scripts/test-doctor.sh keeps the two in step and
asserts each probe's required/optional class against the spec's build-and-test path, and each documented probe's install
hint against its row's column).
| Tool | Needed for | Install (macOS) | Install (Debian/Ubuntu) |
|---|---|---|---|
| Java 21+ | Building and running everything | brew install --cask temurin@21, or SDKMAN |
sudo apt install openjdk-21-jdk, or SDKMAN |
| Docker | Infrastructure (PostgreSQL, Kafka, OpenSearch) and the stack | Docker Desktop, or brew install colima docker |
sudo apt install docker.io |
| Compose | The Compose v2 plugin, for the local infrastructure stack | Docker Desktop, or brew install docker-compose, symlinked to ~/.docker/cli-plugins/docker-compose |
sudo apt install docker-compose-v2 |
| actionlint | The workflow-lint gate in check |
brew install actionlint |
go install github.com/rhysd/actionlint/cmd/actionlint@latest, or a release binary |
pack CLI |
Building the web-UI image | brew install buildpacks/tap/pack |
a release binary from buildpacks/pack |
| Helm 4.x | Kubernetes deployment | brew install helm |
sudo snap install helm --classic, or a release binary |
| Kubernetes cluster | The helmInstallToLocal target |
kind, minikube, or colima with k3s | kind or minikube |
| OpenCode (v2 recommended) | The agentic development workflow (TUI or Desktop) | brew install anomalyco/tap/opencode-v2, or https://opencode.ai/v2 |
curl -fsSL https://opencode.ai/install | bash, or https://opencode.ai/v2 |
| Snyk CLI | dependencySecurityCheck |
brew install snyk/tap/snyk |
npm install -g snyk, or curl https://static.snyk.io/cli/latest/snyk-linux -o snyk |
| ast-grep | The agent's structural code search (ast-grep skill) |
brew install ast-grep |
npm install -g @ast-grep/cli, or a release binary from ast-grep/ast-grep |
| Python 3.12+ | The Python tooling and repository setup: scripts/setup-idea.sh, the commit-hygiene guard/check, claim-scan.py, review-rounds.py, review-routing.py and reconnect-mcp.py |
brew install python3 |
sudo apt install python3 on Ubuntu 24.04+, or a 3.12 build for your release |
Only Java, Docker, and Compose are required to run the application. actionlint and Python 3.12+ are needed for the
full check; pack only when building the web-UI image; Helm, a cluster, and Snyk are only for deployment and security
scanning; OpenCode and ast-grep are only for the agentic development workflow.
git clone https://github.com/aanbrn/axon-showcase.git
cd axon-showcaseThen activate the repository's git hooks once per clone:
./scripts/install-git-hooks.shThis points core.hooksPath at scripts/git-hooks so the pre-commit guard runs on your commits; bypass a deliberate
exception with git commit --no-verify. Activating the hooks is recommended rather than required — the guard's
captured: marker check also runs in ./gradlew check.
The tracked .java-version is an optional version-manager convention for local JDK selection. Support depends on the
manager and its configuration; the file alone does not switch Java.
- If your manager exports its selection as
JAVA_HOME,./gradlewuses that JDK for its launcher JVM. - The compile/test toolchain is configured separately through
gradle/libs.versions.toml. - CI selects its JDK independently through
actions/setup-java. - Check
java -versionand./gradlew --versionin the shell running the build.
JAVA_HOME and PATH can select different JDKs, so the two commands need not report the same Java version.
./gradlew buildbuild compiles everything, runs the quality gates, and runs the test suite. Without Docker, use the fast gate —
./gradlew check -PskipITs -Pcoverage.gate.enabled=false skips the Testcontainers integration tests and disables the
coverage gate they calibrate.
./gradlew composeBuildAndUpThis is the fastest way to see the whole system work: it builds all five service images and starts the complete stack —
PostgreSQL, Kafka, OpenSearch, the four services, and the web UI. The Gradle compose tasks set PROJECT_VERSION and the
image tags automatically, so no environment variables are needed.
Measured once, on a 32 GB arm64 machine and with the stack idle: with the images built, the stack answers on the gateway
in about half a minute and holds about 3.4 GiB of memory (OpenSearch alone about 1.4 GiB); a first run pulls or builds
about 6 GB of images, 3 GB of them the application's five.
docs/decisions/2026-10-30-first-run-resource-passport.md
records the measurement, its conditions, and what it does not cover — a first build's time, a minimum machine
specification, and the disk a first run actually adds.
Open http://localhost:8084 for the web UI, or http://localhost:8080 for the API. Stop everything with
./gradlew composeDown.
Other stack tasks:
./gradlew composeUp # start the stack (images must already be built)
./gradlew composeStop # stop the stack without removing it
./gradlew composeRestart # restart the stack
./gradlew composeBuildAndRestart # rebuild the images, then restart
./gradlew :showcase-api-gateway:composeRestart # restart just one serviceEach <module> compose task is scoped to that module's service: :showcase-api-gateway:composeUp brings up
api-gateway with its Compose dependency graph, and :showcase-api-gateway:composeDown stops and removes just that
container.
Releases cut by the release workflow publish the five service images to the GitHub Container Registry, tagged with the
release version and latest:
docker pull ghcr.io/aanbrn/axon-showcase-api-gateway:<version>The five repositories are
ghcr.io/aanbrn/axon-showcase-{command-service,api-gateway,query-service,projection-service,web-ui}, and each publishes
a linux/amd64 image. The packages are public and can be pulled anonymously: a package published by this repository's
workflow inherits the repository's visibility (still a per-package setting, so verify after a first publish). A release
that predates the publishing workflow (e.g. v0.1.0) can be backfilled by dispatching the workflow with publish_tag.
These are the artifacts the published chart deploys, and
Install from the Published Chart is the only path that starts them. Both
source-building paths — Run the Stack with Docker and
Kubernetes Deployment — build the same images from your working tree instead.
Releases also publish the Helm chart to the GitHub Container Registry as an OCI artifact, versioned with the release:
helm install axon-showcase oci://ghcr.io/aanbrn/charts/axon-showcase --version <version> \
-f values-external.yamlThe chart carries the application only and its defaults point at the local development releases, so an install needs a
values file. helm/chart/examples/values-external.yaml is a commented
example: copy it, fill in your endpoints and hostnames, and install with -f. The prerequisites are:
- Infrastructure — PostgreSQL (the event store), Kafka, and OpenSearch reachable from the cluster (the local target's Bitnami releases are in Kubernetes Deployment).
- Secrets — one holding the PostgreSQL password, and one for OpenSearch if it is secured (the example shows the
kubectl create secretcommands). - The UI's URL —
webUi.apiBaseUrl(the browser's externally visible gateway URL; the UI image fails fast if it is empty) andapiGateway.cors.allowedOrigins(the UI's origin, since an empty list denies all browser origins).
Its service images resolve from ghcr.io by default. The example leaves ServiceMonitors off (they need the
Prometheus-operator CRDs); enable them and the observability endpoints if you run that stack.
The compose stack runs the application as pre-built containers. To develop a service with hot reload, run that service from source instead, after two steps:
- Stop any container whose published port would collide: only the API gateway publishes its HTTP port (
8080, the portbootRuntakes), so for the other three there is nothing to stop. The per-modulecomposeDownabove stops one service. - Provide PostgreSQL, Kafka, and OpenSearch reachable from your host on the ports the service's configuration names — the Compose file publishes no infrastructure port.
./gradlew :showcase-api-gateway:bootRun # :8080
./gradlew :showcase-command-service:bootRun # :8081
./gradlew :showcase-projection-service:bootRun # :8082
./gradlew :showcase-query-service:bootRun # :8083 (gRPC :9090)Each service runs on its own HTTP port. The web UI runs on the Vite dev server (hot reload, proxies /showcases,
/events, and /telemetry to the gateway on :8080):
./gradlew :showcase-web-ui:viteDevOpen http://localhost:5173.
The command service stores events in PostgreSQL. When running it standalone against a native local PostgreSQL instance (instead of the Docker stack), initialize the event store first:
./db.sh init # initialize the event store (idempotent)
./db.sh drop # drop the event store database
./db.sh reset # drop and recreate the event store databaseThe web UI is the easiest way in: create a showcase, then watch the saga auto-start and auto-finish it — every transition appears live in the event timeline. The same flow works over the API:
# Watch events stream in real time (SSE)
curl -N http://localhost:8080/events
# Schedule a showcase — the saga starts it at startTime and finishes it after the duration.
# Use a future startTime (e.g. a few minutes from now) so you can watch the saga auto-start it.
curl -X POST http://localhost:8080/showcases \
-H "Content-Type: application/json" \
-d '{
"title": "My Showcase",
"startTime": "<future ISO-8601 timestamp, e.g. 2026-10-01T10:00:00Z>",
"duration": "PT5M30S"
}'
# Drive it through its lifecycle
curl -X PUT http://localhost:8080/showcases/{showcaseId}/start
curl -X PUT http://localhost:8080/showcases/{showcaseId}/finish
curl -X DELETE http://localhost:8080/showcases/{showcaseId}
# Browse
curl "http://localhost:8080/showcases?title=My&status=SCHEDULED&size=10"
curl http://localhost:8080/showcases/{showcaseId}A POST answers 201 Created with a Location header once the command has completed; when the command's own wait
times out it answers 202 Accepted with an Idempotency-Key header, and a request may carry its own key (a KSUID),
which the command then uses as the showcase ID — that is what makes a retry safe.
The query service exposes a single generic gRPC RPC (ShowcaseQueryTransport.Dispatch, with
QueryRequest → stream QueryResponse) on port 9090, consumed by the query-client (showcase-query-client) for
inter-service communication — the gateway queries the query service through that client over gRPC, and the query service
in turn queries OpenSearch. The RPC is name-routed and carries any Axon query, so it stands in for Axon's distributed
query bus without Axon Server (see docs/adr/0017).
Tests are organized into four tiers, run in order:
| Tier | Command | Notes |
|---|---|---|
| Unit | ./gradlew :<module>:test |
isolated, no Spring context |
| Component | ./gradlew :<module>:componentTest |
real in-process collaborators |
| Integration | ./gradlew :<module>:integrationTest |
Testcontainers (needs Docker) |
| End-to-end | ./gradlew :<module>:e2eTest |
real deployed service + infra |
The gateway e2e boots the full four-service pipeline with Testcontainers and verifies cross-service propagation. The web
UI e2e (./gradlew :showcase-web-ui:e2eTest) boots the same pipeline via docker compose, serves the built UI with Vite
preview, and drives it with Playwright — creating a showcase, starting it, observing a saga-triggered transition over
SSE, live events appending to the timeline, and a duplicate title surfacing the gateway error.
./gradlew :<module>:check runs the module's gates — compilation, formatting and static analysis, and every test tier
except the opt-in end-to-end suite — and the root ./gradlew check adds the repository-wide verification tasks, the
chart packaging, and the workflow lint; the check block in build.gradle.kts is the list. Add
-PskipITs -Pcoverage.gate.enabled=false for a Docker-free check: the first flag drops the integration tier, the second
disables the coverage gate that would otherwise fail without its data. All of it runs in the Gradle build, so no IDE is
required to verify a change; an IDE is an optional convenience for editing, debugging, and inspection.
A pre-commit guard (scripts/git-hooks/pre-commit) refuses a commit whose staged set is mechanically defective — a
stale index, a misplaced captured: marker, an openspec archive move without its spec sync, an unticked task in an
archived change, a unit record or a tasks.md reference that is missing or malformed, an emptied dated ideas section
ideas file, a change directory that is not the commit's own, and the rest of the set its own header and AGENTS.md's
staging gotcha enumerate. Several of its checks have build-side counterparts in ./gradlew check — spotlessCheck for
the formatter, verifyCapturedMarkers, verifyConflictMarkers, verifyTrackedIgnoredFiles for the force-staged
artifact, verifyIdeasSections for the ideas sections, verifyWorkspaceRecords for the workspace record,
verifyAgentSessionContinuity for the agent-session register, and the review-round ledger's tasks — so they hold even
without the hook. The rest read the commit's own boundary — the index diverging from a later edit, an unpaired archive
move, an unticked archived task, a foreign change directory, and an ideas file removed from the index while the
working-tree copy remains — which no build task sees. Install it once per clone (see
Get the Sources); bypass a deliberate exception with git commit --no-verify.
# Reports — run by the scheduled workflows (not part of check)
./gradlew dependencyUpdates # the catalog's coordinates
./gradlew buildLogicUpdates # the included build-logic build's plugin pins
./gradlew :showcase-web-ui:npmOutdated # the web UI's npm dependencies
./gradlew helmUpdates # the Helm CLI and chart pins
./gradlew buildpackUpdates # the Paketo builder and buildpacks
./gradlew toolingUpdates # the CLIs pinned in workflow files
./gradlew upstreamReferences # the state of cited upstream references
# Security scans (not part of check)
./gradlew dependencySecurityCheck # Snyk, needs the Snyk CLI
./gradlew :showcase-web-ui:npmAudit # npm audit for the web UIScheduled workflows open or update a tracker issue with a report's findings; security scans fail on findings their
policies reject. dependencyUpdates covers the coordinates the catalog declares with an exact version.ref, so a
BOM-inherited version is not reported, and it honours the suppression and hold-back lists under
config/dependency-updates/ — each entry's rationale is the showcase/quality/dependency-management spec's. The web
UI's report has its own list (config/web-ui-updates/major-disabled.txt). buildLogicUpdates exists because the
included build-logic build's plugin pins resolve on its own buildscript classpath, where dependencyUpdates cannot
see them. A calendar-versioned coordinate (a YYYY.MINOR.MICRO Spring train) treats a change in the train pair as a
major update, matching Spring's release-train definition.
Three decisions bound what these reports show: ADR-0004 defers the Spring Boot 4 migration, ADR-0014 explains why the web UI uses npm's own audit rather than Snyk, and ADR-0021 filters the spurious row a build-environment constraint produces when the tooling's own floor is read as the "current version".
The /dependency-updates command runs the Gradle, web-UI, and build-logic reports and summarizes them; /gradle-update
bumps the Gradle wrapper to the latest stable version.
Formatting is enforced by Spotless — palantir-java-format for Java, ktfmt for Gradle Kotlin DSL (*.gradle.kts) and
build-logic Kotlin (build-logic/src/**/*.kt), Prettier for markdown (docs/, AGENTS.md, README.md,
openspec/specs/, openspec/changes/*/, SECURITY.md, the .github/ markdown, and the project-authored .opencode/
markdown) and for the .opencode/ config JSON: ./gradlew spotlessApply formats, spotlessCheck verifies, and the
build never depends on an IDE. The generated OpenSpec instruction files and the vendored agent skills are excluded —
they are not the repository's to reformat. Line endings are normalized by the committed .gitattributes
(* text=auto eol=lf, with *.bat text eol=crlf so gradlew.bat is checked out CRLF), so a text file is stored as LF
in the index regardless of a machine's core.autocrlf. For the web module, ./gradlew :showcase-web-ui:npmFormat
applies Prettier and :showcase-web-ui:npmFormatCheck (run by check) verifies it. IntelliJ's built-in formatter uses
its own code style and would reformat files differently, so configure the IDE to stay in sync:
-
The repo's IntelliJ config is not versioned —
.idea/is git-ignored. Run the setup script any time the configuration drifts: it merges the committed settings fromconfig/idea/into.idea/(restoring the palantir-java-format and ktfmt settings and the test-tier naming inspection, leaving IntelliJ-managed content untouched), reconciles the module that gives IntelliJ Python analysis forscripts/*.py(see the Python-analysis bullet below), and installs the palantir-java-format and ktfmt plugins. The plugin install needs IntelliJ closed (it warns and skips that step otherwise); the configuration merge does not, so a re-run repairs the config even with the IDE open:./scripts/setup-idea.sh
IntelliJ reads these settings at startup, so apply the merged config with File → Reload All from Disk (or restart the IDE) — the test-tier naming inspection, in particular, only takes effect then. The Python-analysis module (see the bullet below) is different: it appears when the project is opened after a setup run made while the project was closed, and reloading an open project does not add it — if the project was open during the run, close its window, run the setup again, then open the project. You can also ask the agent to do it (
/setup-idea), which additionally handles quitting a running IDE for the plugin install.The ktfmt template uses the plugin's Custom style to reproduce ktfmt's kotlinlang style at 120 columns with unused-import removal (the plugin's
Kotlinlangmode hard-codes ktfmt's 100-column default and ignores the line-length option). Where a plugin is disabled by default (palantir only auto-enables with thecom.palantir.java-formatGradle plugin, which this project does not use), enable it via Settings → Other Settings → palantir-java-format Settings. When enabled it replacesReformat Code(Ctrl+Alt+L) with the palantir formatter. -
The plugin only replaces
Reformat Code; import order is a separate mechanism — IntelliJ'sOptimize Imports(Ctrl+Alt+O) is governed by.editorconfig, which the repo ships with the palantir layout (ij_java_imports_layout = $*,|,*— import static all other imports, blank line, import all other imports) soOptimize ImportsmatchesspotlessApplyautomatically. If the layout is not picked up, set it manually: Settings → Editor → Code Style → Java → Imports, Import Layout panel → clear the rows and add: import static all other imports, blank line, import all other imports (single imports, no wildcards). -
With the plugins enabled and the
.editorconfigimport layout in effect, IntelliJ'sReformat CodeandOptimize Importsproduce spotless-compatible output, so the automatic reformat triggers are safe to keep on: Actions on Save → Reformat code / Optimize imports, and Auto Import → Optimize imports on the fly. If the plugin is not active on a machine, disable those triggers instead to avoid drift;spotlessCheckincheckis the backstop either way. -
For Python analysis of
scripts/*.py, the same setup writes the IntelliJ module that gives those files an interpreter, so each clone and eachgit worktreegets it in one./scripts/setup-idea.shrun made while the project is closed — the module appears when the project is then opened, and the Gradle import IntelliJ offers keeps it. A tree the process creates from a configured primary inherits its.python-versionfirst, so the run resolves the same interpreter wherePATHreaches it through that selection's selector. The interpreter is the one the build uses — the firstpython3onPATH, at 3.12 or newer — and the script prints the path and version it selected; the selection still does not change what./gradlew checkor the Git hooks run.Its Python line reports
CONFIGUREDwhen the module is in place,SKIPPEDwhen no IntelliJ configuration was found, andNEEDS_ACTION(exiting non-zero) when the contributor has to act. Its report is a short first line followed by an indented block that puts the remedies first. When the tree's interpreter is not registered, the block says to register the printed interpreter once per configuration (Settings → Build, Execution, Deployment → Python Interpreter, or Project Structure → SDKs, Add Interpreter → System, then save) or to run the tree on one that is already registered (for examplepyenv local <installed-version>, so thatpython3resolves to that interpreter), and lists beneath them the registered SDKs with their interpreter paths and the configurations searched. On macOS the script reads the installed IntelliJ IDEA bundle's product and version and reads that configuration — an upgrade leaves the previous version's configuration beside the new one, and the installed bundle names the live one; the line states which configuration and version it matched. When the identified configuration registers no SDK for the interpreter, or no configuration exists for the installed version yet, the block names that configuration and the registration it owes rather than reading another one, since the module references an SDK name only that configuration can resolve. When several configurations or SDK entries match with no installed bundle to choose between them, the block names the matching entries and that case's remedy: narrow the search with--idea-config-dir <path>, or delete all but one entry. Automatic selection assumes IntelliJ's default configuration location; a customidea.config.pathis not detected, so pass that flag. Re-run the setup afterwards: it reads the SDK name IntelliJ recorded and references exactly that entry. A different patch version per working tree is expected:.python-versionis a personal, ignored setting. -
An interpreter manager is optional, and the repository itself selects
python3fromPATH. A personal.python-versionmatters only where the local environment integrates it into that selection — pyenv's shims do (pyenv local <installed-version>for an installed Python 3.12+), and uv's own commands read the same file (uv python pin <installed-version>) — and a pin does not by itself change whichpython3the shell resolves. It is ignored rather than a shared repository runtime pin. Verifypython3 --versionin the environment running the tooling. -
For the web module (
showcase-web-ui), the same setup enables IntelliJ's built-in Prettier integration — Automatic configuration, run on reformat and on save — soReformat Codeformats TS/TSX, CSS, and HTML with the project'sprettierand.prettierrc, matching theprettier --checkgate; the Prettier scope is extended (myFilesPattern) because IDEA's default covers neither CSS nor HTML, and the JS/TS indentation comes from.editorconfig. IDEA's Optimize Imports is safe here too — it only removes unused/duplicate imports and reorders them, and no gate enforces import order. No plugin install is needed — IntelliJ bundles JavaScript/TypeScript and its Prettier integration is free from IntelliJ IDEA 2026.1 (on the earlier unified 2025.3–2026.0 it needs the Ultimate subscription). -
When in doubt, format with
./gradlew spotlessApply(JVM and markdown) or./gradlew :showcase-web-ui:npmFormat(the web module) — the build owns formatting either way.
Use the bundled Helm release — it builds all five images and deploys the monitoring stack, infrastructure, and the application to your local cluster in dependency order:
./gradlew helmInstallToLocalThe local release target deploys to your local cluster: it uses the helm.local.kubeContext Gradle property when set
(in ~/.gradle/gradle.properties or via -P), otherwise your current kube context. Set helm.local.kubeContext only
if you have multiple kube contexts and need to pin the local one — e.g. macOS colima users may add
helm.local.kubeContext=colima.
Custom values can be placed in helm/values/axon-showcase/values-local.yaml. Per-release install/uninstall tasks follow
helmInstall<Release>ToLocal / helmUninstall<Release>FromLocal (e.g. helmInstallKpsToLocal), for installing or
verifying a single chart without building images.
The deployment exposes the API gateway, the web UI, and Grafana through the cluster's ingress controller at the
hostnames axon-showcase-api, axon-showcase-ui, and axon-showcase-grafana. To reach them by hostname instead of a
Host:-header curl workaround, manage the /etc/hosts entries once per cluster (requires sudo):
./setup-hosts.sh setupThe script detects the ingress controller's LoadBalancer address generically against your current kube context (colima
with Traefik, kind/minikube with ingress-nginx, and similar). After it runs, open http://axon-showcase-ui in the browser
for the web UI, use http://axon-showcase-api for the API (e.g. curl http://axon-showcase-api/showcases), and open
http://axon-showcase-grafana for Grafana. The address can change on cluster restart — re-run ./setup-hosts.sh setup to
refresh, or ./setup-hosts.sh remove to clean up.
.github/workflows/ci.yml gates every pull request and push to main with a single build check. Pull requests run
the Docker-free fast gate (check -PskipITs with the coverage gate disabled), while pushes to main run the full gate
(check with integration tests and coverage); both validate the OpenSpec specs and check that the CLI reads the
OpenSpec config's declared list surfaces (its artifact rules and its operation guidance). A pull request that changes
any .opencode/ path (or the workflow itself) additionally checks that the config loads under the consumer the
opencode action installs and that every agent, command, and skill definition resolves with its metadata intact. The
Gradle cache is restored across runs via gradle/actions/setup-gradle. The main-required-checks ruleset requires the
build check for all merges into main, with no bypass actors.
Scheduled runs are paused (2026-11-09). The nine schedule-triggered workflows described below are disabled in the
repository's Actions settings while active work on the project is paused, so none of them runs on its schedule — and a
disabled workflow cannot be dispatched either. Re-enable one with gh workflow enable <file>; Dependabot's weekly
version updates are suspended too, and docs/ideas.md carries the whole resume action. The CI gates above are not
affected.
.github/workflows/e2e.yml runs the end-to-end suites (:showcase-api-gateway:e2eTest, which builds all four service
images and boots the full pipeline, and :showcase-web-ui:e2eTest, which drives the browser against the same pipeline
with Playwright) on a nightly schedule and via workflow_dispatch — observational, never a merge gate, and no
repository secret is passed to it.
.github/workflows/deployment-smoke.yml goes a step further nightly: it installs the application, its infrastructure,
and an ingress controller on a throwaway kind cluster through the ci release target — a trimmed install that fits
the runner, leaving observability out — enables the deployment's ingress, and drives load at the gateway through that
ingress, so a deployment that installs but does not serve is noticed without anyone running it by hand.
.github/workflows/dependency-security.yml runs the dependency security scans — the Snyk scan
(dependencySecurityCheck, all sub-projects with the root .snyk policy, authenticated with the SNYK_TOKEN secret)
and the web-UI npm audit (:showcase-web-ui:npmAudit) — on a weekly schedule and via workflow_dispatch —
observational, never a merge gate.
.github/workflows/dependency-updates.yml runs the Gradle, web-UI, and build-logic pin dependency update reports
(dependencyUpdates, :showcase-web-ui:npmOutdated, and buildLogicUpdates) on a weekly schedule and via
workflow_dispatch, opening or updating the "Dependency updates" issue with only the actionable sections (stable
catalog updates + Gradle wrapper status + web UI npm updates + build-logic plugin pins) using the GITHUB_TOKEN
(issues: write). When there are actionable updates it posts a comment mentioning the repository owner (so they are
notified); runs with no updates update the issue silently — observational, never a merge gate.
.github/workflows/helm-updates.yml runs the Helm update check (helmUpdates) on a weekly schedule and via
workflow_dispatch, opening or updating the "Helm updates" issue with the actionable coordinates (the Helm CLI and
pinned chart versions that have a newer version) — observational, never a merge gate.
.github/workflows/tooling-updates.yml runs the workflow-pinned tool update check (toolingUpdates) on a weekly
schedule and via workflow_dispatch, opening or updating the "Tooling updates" issue with the OpenSpec, Snyk, pack,
and gitleaks CLI versions whose pin lags the latest release — observational, never a merge gate.
.github/workflows/audit.yml runs the three repository audits (agent tooling, spec corpus, architecture) on a weekly
schedule and via manual dispatch, opening a pull request with their combined findings and mentioning the repository
owner — or committing nothing when they report nothing.
.github/workflows/buildpack-updates.yml runs the Paketo buildpack update check (buildpackUpdates) on a weekly
schedule and via workflow_dispatch, opening or updating the "Buildpack updates" issue with each pinned Paketo builder
and buildpack coordinate that has a newer version — observational, never a merge gate.
.github/workflows/upstream-references.yml runs the upstream-reference check (upstreamReferences) on a weekly
schedule and via workflow_dispatch, opening or updating the "Upstream references" issue with each owner/repo#NNN
reference the durable artifacts cite, its state (open / closed with the closure reason the API reports / unresolved),
and where it is cited — so a closure is surfaced as a trigger to check rather than declared actionable, and a duplicate
or a declined closure reads differently from a completed one — observational, never a merge gate.
.github/workflows/release.yml cuts a release: dispatch it from main with a version (e.g. 0.1.0), and it builds the
five service images, publishes them to the GitHub Container Registry (ghcr.io/aanbrn/axon-showcase-*, tagged with the
version and latest), then creates the tag v<version> at the head of main and publishes a GitHub Release whose
notes GitHub generates from the pull requests merged since the previous release. It refuses a version that does not
match the declaration in gradle.properties (without its -SNAPSHOT suffix) and refuses a tag that already exists.
Dispatch it with the dry_run input to build and push the images under a throwaway tag without creating a tag or
release. It also publishes the Helm chart to oci://ghcr.io/aanbrn/charts/axon-showcase, versioned with the release (a
dry_run pushes a throwaway chart version; a publish_tag backfill publishes no chart). To publish the images for an
existing release that predates this workflow, dispatch it with publish_tag (e.g. -f publish_tag=v0.1.0): it builds
from that tag and pushes only its version tag, leaving latest unchanged and creating no tag or release. The images are
linux/amd64, and the packages are public — a workflow-published package inherits the repository's visibility, though
visibility stays a per-package setting. Afterward, bump gradle.properties to the next development version in a
follow-up pull request, so the next release has a base. The release workflow is not a merge gate.
./gradlew :load-tests:gatlingRun -Pprofile=smoke
# Read the committed baselines as a chronological series
./gradlew :load-tests:baselineTrendGatling-based load tests drive the deployed system through three concurrent streams — reads, a write lifecycle, and
a live /events SSE connection — with a configurable read/write ratio and branch mix, so the load looks like real use.
Beyond the quick smoke run and the knee-relative performance profiles (average, soak, stress, spike,
breakpoint, scaled from a kneeRate), the calibrate profile ramps to find the load knee and baseline holds a
plateau below it; ./scripts/load-test-baseline.sh raises the calibration ceiling until a real knee is measured (or the
CALIBRATE_MAX_RATE cap is reached), runs the baseline, and (with PROFILE=<name>) a performance profile at the
derived knee — the measured knee, or the ceiling when none was measured — against the local Helm cluster (installed by
./gradlew helmInstallToLocal), and writes a baseline report — response times plus per-service CPU/memory — to
load-tests/build/load-tests/report.md. An unsupported profile name fails the run rather than silently falling back
to smoke, and a PROFILE run's own Gatling report lands under load-tests/build/reports/gatling/. The below-knee
profiles assert thresholds derived from the last recorded baseline — max(floor, factor × baseline) per request —
so a fast host's regression is caught instead of hiding under fixed absolutes, and a reference recorded for another
target is ignored, so the profiles fall back to those fixed absolutes. A run writes its own reference — the operating
point it ran at plus the per-request figures (baseline.properties, or baseline-<slug>.properties for another target;
-PbaselineFile selects it) — and a ready-to-annotate record under docs/load-tests/, for the operator to annotate and
commit. So that a slow-but-passing plateau cannot quietly become the new normal, a baseline run first compares its
plateau's per-request mean and 95th/99th percentiles against the recorded reference — the comparison is made only when
the reference's target matches and the measured operating point is within a tenth of the reference's, so a plateau run
at a different load is not misread as a regression — and reports every delta. A mean or 95th-percentile figure beyond
TOLERANCE (a percent, default 50) fails the run and leaves the reference unchanged, while a 99th-percentile excursion
withholds it without failing and asks for a re-run at the same operating point to confirm it — set REFRESH_BASELINE=1
to accept either deliberately — while a measurement that recorded no figures fails the run and leaves the reference
unchanged even when a refresh is intended, and the dated record is written either way, so the movement stays visible.
./gradlew :load-tests:baselineTrend reads those records back (-Precords=<dir> overrides the default
docs/load-tests/) and prints them as a chronological series: each record's date, target, operating point, and plateau
figures, reporting a record it cannot read as unreadable rather than failing. The calibration deliberately ramps past
the knee and the resource sampling follows the current kube context, so point it at an environment you own.
Observability is part of the Kubernetes deployment — ./gradlew helmInstallToLocal installs Prometheus, Grafana,
and Tempo into the monitoring namespace alongside the application. The local docker-compose stack does not run it.
- Metrics: each service exports Prometheus metrics (HTTP throughput/latency/failure, Axon command bus, event store,
saga, deadlines, projection lag and consumer backlog, cache hits, query performance); the web UI exports nginx
stub_statusvia a sidecar and reports browser-side Core Web Vitals and JavaScript errors through the gateway, which exposes them as Prometheus metrics. ServiceMonitors are wired for all of them. - Grafana: a custom Axon Showcase dashboard is provisioned automatically (46 panels across 8 sections covering
every service, the scrape status and replica capacity of each Deployment, the projector's operating state and consumer
backlog, the browser experience, and the Axon internals), and Grafana is preconfigured with a Tempo data source. The
default login is
adminwith the password from the chart's generated secret. - Tracing: services export OpenTelemetry traces to Grafana Tempo (
tempo.monitoring), viewable in Grafana's Explore. The web UI propagates W3C trace context on its API calls, so a page load's requests join one trace that continues through the gateway into the command and query services. - Build version: every JVM service reports the version it was built from at its management
/actuator/infoendpoint, so a running pod's build is identifiable without inspecting its image tag.
Grafana is reachable through the same ingress at http://axon-showcase-grafana (see Access the Deployed System). Traces are available in the Tempo data source under Grafana → Explore.
This project is a reference application licensed under the MIT License — free to use, copy, and adapt for learning and as a starting point for derived projects.
Alexey Afanasyev — GitHub