Documentation · Get started · Module catalog · Maven · Framework by Firefly
Jafly is the Java framework in Framework by Firefly. It brings command and query buses, saga and TCC coordination, event transports, service clients, policy-based security, and observability to applications built with Spring Boot, WebFlux, and Reactor.
Spring continues to host your application, route HTTP requests, manage dependencies, and provide data access. Jafly connects application operations and provider adapters through shared contracts. Your team writes the business rules and chooses authorization, transaction boundaries, and recovery behavior.
Choose the libraries your service needs; the parent and BOM keep their versions aligned. The current platform uses Java 25, Spring Boot 4.1.1, and Spring Cloud 2025.1.3.
| Start here | What you get |
|---|---|
| Documentation site | Published guides, architecture, Maven, releases, and the full module catalog |
| Getting started | First onboarding service: HTTP → command → storage → query |
| Module catalog | Every component, grouped by capability, with configuration and examples |
| Architecture | Boundaries between handlers, ports, and provider adapters |
| Maven parent and BOM | How applications consume the train |
| Installation | JDK, Maven wrapper, Docker, and local setup |
| Examples and tutorials | Onboarding paths and integration samples |
| Development · Docs workflow · Versioning · Releases | Contribute, build docs, and publish |
Source-backed copies of the same pages live under docs/site/. The MkDocs site is the preferred reading experience.
The documentation follows the same eight capability areas as Jafly on Framework by Firefly.
| Capability | What you can build with it |
|---|---|
| Security and identity | Map JWTs to principals, protect methods and routes, and connect identity and policy providers through shared ports. |
| Business operations | Dispatch commands and queries to typed handlers, apply configured validation and authorization, and evaluate business rules. |
| External services | Call REST, SOAP, and gRPC services, send notifications, manage callbacks, and connect to the separate Agentic runtime. |
| Event-driven integration | Publish and consume through Spring events, Kafka, RabbitMQ, or PostgreSQL; receive webhooks with provider-specific processing. |
| Domain and data | Use reactive PostgreSQL access, filtering and pagination, query caches, content storage, and optional event sourcing. |
| Business coordination | Coordinate saga steps and compensations, try-confirm-cancel participants, and workflows with explicit application recovery policies. |
| Service operations | Configure metrics, traces, health checks, HTTP conventions, and shared configuration for your services. |
| Team-wide architecture | Adopt the parent or BOM, service-layer starters, shared kernel contracts, and plugin interfaces across a team's applications. |
Use the module catalog to pick a concrete library (for example CQRS, a Kafka EDA adapter, or a security IDP). Each catalog entry links to its guide, source tree under modules/, and tests.
The tutorials follow a customer application through three separate projects. Each has its own executable tests and states its storage and provider boundaries.
| Project | What you learn |
|---|---|
| Accept an application | Validate HTTP input, dispatch commands and queries, and retrieve an application from an in-memory repository. |
| Retain its event history | Append typed events to PostgreSQL, reconstruct an aggregate, reject a stale writer, and roll back an invalid batch. |
| Coordinate a review | Compensate a failed Saga, confirm or cancel TCC reservations, and order Workflow steps with explicit recovery. |
Continue with examples and tutorials for the next integration. The three projects share the onboarding story; each runs independently so its failure and transaction behavior can be tested directly.
Use JDK 25, Python 3, Git, and a running Docker engine for container-backed integration tests. The checked-in wrapper downloads checksum-pinned Maven 3.9.16.
git clone https://github.com/fireflyframework/fireflyframework-jafly.git
cd fireflyframework-jafly
./mvnw -B -ntp clean verifyBuild one component together with its prerequisites:
./mvnw -B -ntp -pl :fireflyframework-cqrs -am verifyInstall the framework locally before consuming the development train from a separate application:
./mvnw -B -ntp installWindows users can use mvnw.cmd. See installation for prerequisites and setup troubleshooting, or the first application tutorial for a complete small application POM.
Use the framework parent when you want its build and dependency management:
<parent>
<groupId>org.fireflyframework</groupId>
<artifactId>fireflyframework-parent</artifactId>
<version>26.10.21-SNAPSHOT</version>
<relativePath/>
</parent>Or retain your existing parent and import the independent BOM:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.fireflyframework</groupId>
<artifactId>fireflyframework-bom</artifactId>
<version>26.10.21-SNAPSHOT</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>Then declare the libraries you need (see the module catalog for artifact IDs):
<dependency>
<groupId>org.fireflyframework</groupId>
<artifactId>fireflyframework-cqrs</artifactId>
</dependency>The parent and BOM manage the same framework artifact versions. Your application keeps its own version and declares its runtime dependencies. Details: Maven integration.
Published coordinates use org.fireflyframework. Stable releases go to Maven Central; development snapshots publish to the Jafly GitHub Packages repository (maven.pkg.github.com/fireflyframework/fireflyframework-jafly).
pom.xml Reactor aggregation POM (not a consumer parent)
build/parent/ Published fireflyframework-parent
build/bom/ Published fireflyframework-bom
modules/ Framework components (source, tests, examples, guides)
docs/site/ Documentation source for the published site
scripts/ Version, release, docs, and publishing tools
tests/ Repository contract tests
Active CI and release workflows live at the repository root. Nested workflow files under modules/ are inactive historical copies and are not the publishing entry point.
Sibling language frameworks (pyfly, larafly, rsfly, netfly) and products such as Agentic, Forge, and Weave keep their own repositories. The Java Agentic Bridge in this tree integrates Java services with the separate Agentic runtime.
python3 -m unittest discover -s tests -v
python3 -m unittest discover -s tests/release -v
python3 scripts/release_tools.py check
./mvnw -B -ntp clean verify- Development workflow — focused builds, tests, and module boundaries
- Documentation workflow — pinned MkDocs environment and catalog completeness checks
- Versioning — one
YY.MM.PATCHtrain - Release workflow — verified GitHub Packages and Maven Central publication
Framework source code is licensed under the Apache License 2.0.
Copyright © Firefly Software Solutions Inc. and contributors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Official Jafly and Firefly artwork and the self-hosted Manrope font retain separate brand provenance and notices. Those assets are not covered by the Apache 2.0 grant for the framework code.