_____.__                _____.__
_/ ____\__|______   _____/ ____\  | ___.__.
\   __\|  \_  __ \_/ __ \   __\|  |<   |  |
 |  |  |  ||  | \/\  ___/|  |  |  |_\___  |
 |__|  |__||__|    \___  >__|  |____/ ____|
                       \/           \/

A production-grade platform for building reactive, event-driven, resilient microservices on Go 1.24+.

The Firefly Framework provides the cross-cutting machinery that every non-trivial business service needs — RFC 7807 error envelopes, idempotency, correlation propagation, CQRS, event-driven messaging, event sourcing, sagas, configuration servers, identity adapters, document management, notifications, callbacks, webhooks — behind a single, opinionated composition pattern.

This repository is the official Go port of the Java/Spring Boot org.fireflyframework platform and its sibling .NET 10 port. It preserves every public contract, configuration key and wire format from the Java release line, re-implemented with idiomatic Go tooling (stdlib log/slog, OpenTelemetry, pgx/v5, go-redis/v9, franz-go, amqp091-go, failsafe-go). A service running version X on Java, .NET, or Go consumes the same contracts and emits the same wire format.

Modern back-office systems aren't bottlenecked by writing the next controller. They're bottlenecked by getting the same controller, the same error response, the same correlation id, the same saga compensation, the same observability story across every service in the platform. Every team that re-invents these picks slightly different conventions and the platform fragments.

Firefly Framework treats those concerns as solved problems on Go too:

• Composed, not constructed. A single startercore.New(cfg) / starterapplication.New(cfg) / starterdomain.New(cfg) / starterdata.New(cfg) call wires the whole infrastructure tier. Authors write commands, queries, handlers, and endpoints — nothing more.
• Symmetric across runtimes. The wire contract, the application/problem+json shape, the Idempotency-Key semantics, the saga step definitions, the event envelopes — all identical to the Java and .NET sides.
• Pluggable at the adapter layer. Each integration point (IDP, ECM, storage, e-signature, notification channel, message broker) is a port with multiple adapter implementations selected at registration time.
• Observable by default. OpenTelemetry traces and metrics, slog structured logging with correlation-id enrichment, RFC 7807 error envelopes, and a startup banner that names the application, version and runtime are all on out of the box.
• Honest about boundaries. Every public method either runs real code or returns a sentinel error with an actionable message documenting why the underlying provider is not yet wired. There are no silent stubs. See docs/AUDIT.md for per-module status.

The framework is organised into four strictly-layered tiers, with a left-to-right dependency direction:

┌────────────────┐   ┌──────────────────┐   ┌───────────────┐   ┌──────────────────┐
│  FOUNDATIONAL  │ → │     PLATFORM     │ → │   ADAPTERS    │ → │     STARTERS     │
│                │   │                  │   │               │   │                  │
│  kernel        │   │  cache           │   │  client       │   │  startercore     │
│  utils         │   │  observability   │   │  idp.*        │   │  starterapp.     │
│  validators    │   │  data            │   │  ecm.*        │   │  starterdomain   │
│  web           │   │  cqrs            │   │  notifications│   │  starterdata     │
│  config        │   │  eda             │   │  callbacks    │   │  backoffice      │
│  i18n          │   │  eventsourcing   │   │  webhooks     │   │                  │
│                │   │  orchestration   │   │  configserver │   │                  │
│                │   │  ruleengine.*    │   │               │   │                  │
│                │   │  plugins         │   │               │   │                  │
│                │   │  lifecycle       │   │               │   │                  │
│                │   │  actuator        │   │               │   │                  │
│                │   │  scheduling      │   │               │   │                  │
│                │   │  resilience      │   │               │   │                  │
│                │   │  security        │   │               │   │                  │
│                │   │  migrations      │   │               │   │                  │
│                │   │  openapi         │   │               │   │                  │
│                │   │  sse             │   │               │   │                  │
│                │   │  transactional   │   │               │   │                  │
│                │   │  testkit         │   │               │   │                  │
└────────────────┘   └──────────────────┘   └───────────────┘   └──────────────────┘

Each tier may depend on the tiers to its left, never to its right. The Go module graph (go.work) enforces the layering.

See docs/MODULES.md for the full per-module catalogue with Java / .NET cross-references.

Every microservice built on Firefly follows the same scaffolding, mirroring the multi-module Maven layout used by Java services across the Firefly platform:

your-service/
├── interfaces/   # public DTOs, enums, V1-namespaced wire contract
├── models/       # persistence entities + repository contracts
├── core/         # commands, queries, handlers, mappers
├── web/          # runnable net/http host
└── sdk/          # typed client consuming only interfaces

sdk references only interfaces, so cross-service callers pull in the wire contract and nothing else — no persistence types, no business logic.

A complete reference implementation lives at samples/orders/. The pattern, naming conventions and rationale are documented in docs/SERVICE-SCAFFOLDING.md.

# Go 1.24+ required.
go run ./samples/orders/web

Place an order:

curl -X POST http://localhost:8080/api/v1/orders \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1' \
  -d '{"customer":"alice","sku":"SKU-1","quantity":2,"total":19.99}'

Repeat the same request with the same Idempotency-Key — the framework replays the recorded response with Idempotent-Replay: true.

Read the order back:

curl http://localhost:8080/api/v1/orders/<id>

Subsequent reads within 30 s are served from the CQRS query cache.

make ci          # gofmt + go vet + go build + go test across the workspace
make build       # build every module
make test        # go test ./... per module
make sample      # run the Orders sample

Everything is a stdlib-friendly Go workspace — no external build tool.

The framework currently ships 52 modules across the four tiers. As of v26.04.02 every module passes go test, go test -race, and go vet, and the workspace is gofmt-clean.

See docs/AUDIT.md for a per-module green/yellow/grey status board. Foundational, platform and starter tiers are production-ready. Adapter-tier integrations against external SaaS providers (Keycloak admin REST, Azure Graph, AWS Cognito, DocuSign / Adobe Sign / Logalty, SendGrid / Resend / Twilio / Firebase, S3 / Azure Blob, Kafka via franz-go, RabbitMQ via amqp091-go) ship in this release as port-only stubs returning a typed Err…NotImplemented sentinel — the contract is locked, the wire is in scope for a follow-up release.

Apache 2.0 — see LICENSE.