MODULES.md

Module index

Top-level index of every module shipped in the Firefly Go workspace. Each module ships its own README.md describing its public surface, design rationale, and a runnable quick-start snippet — click the module name to open it.

01 — Foundational

Module	What it provides
kernel	RFC 7807 ProblemDetail, generic Result[T], Clock, FireflyError hierarchy
utils	Try, Retry.Do, slug, AES-256-GCM, templates
validators	IBAN, BIC, Luhn, currency, phone, password, sort code, VAT, Spanish IDs
web	Problem renderer, correlation, idempotency, PII masking
config	Typed YAML+env+flag binding with profile selection
i18n	Locale-aware message bundles + Accept-Language picker

02 — Platform

Module	What it provides
cache	Adapter port + Memory / NoOp / Fallback + typed Typed[T]
observability	slog + correlation, health composite, startup banner
data	Filter DSL, Page[T], Repository[T,K]
cqrs	Command + query bus with validation + caching middleware
eda	Event envelope, Publisher/Subscriber, in-memory broker, Kafka/RabbitMQ scaffolds
eventsourcing	AggregateRoot + EventStore + Snapshots + Projections
orchestration	Saga, Workflow (DAG), TCC engines
ruleengine	YAML DSL → AST → evaluator (sub-packages: interfaces, models, core, web, sdk)
plugins	Lifecycle SPI + composite Registry
lifecycle	Application.Run(ctx) orchestrator with signal trap + drain
actuator	/actuator/{health,info,metrics,env,goroutines,version}
scheduling	Cron + FixedRate + FixedDelay scheduler
resilience	CircuitBreaker, RateLimiter, Bulkhead, Timeout, Chain
security	Authentication ctx, BearerMiddleware, RBAC FilterChain
migrations	Versioned SQL migrations (V001__init.sql)
openapi	OpenAPI 3.1 generator + Swagger-UI shim
sse	Server-Sent Events writer w/ heartbeat + Last-Event-Id
transactional	WithTx(ctx, db, fn) over database/sql
testkit	HMAC signers, SpyBroker, JSON test helpers

03 — Adapters

Service client + config server

Module	What it provides
client	REST builder with retry, problem decode, correlation propagation; SOAP/gRPC/WS scaffolds
configserver	Spring-Cloud-Config-compatible REST endpoint

Identity providers

Module	Backing
idp	Common Adapter port
idpinternaldb	Self-hosted (bcrypt + HS256 JWT) — Full
idpkeycloak	Keycloak OIDC + admin REST — Stub
idpazuread	Azure AD / Entra ID (MSAL + Microsoft Graph) — Stub
idpawscognito	AWS Cognito — Stub

Enterprise content management

Module	Backing
ecm	Adapter framework + LocalStore — Full
ecmstorageaws	AWS S3 — Stub
ecmstorageazure	Azure Blob Storage — Stub
ecmesignaturedocusign	DocuSign — Stub
ecmesignatureadobesign	Adobe Sign — Stub
ecmesignaturelogalty	Logalty — Stub

Notifications

Module	Channel
notifications	Dispatcher + MemoryChannel — Full
notificationssendgrid	SendGrid (email) — Stub
notificationsresend	Resend (email) — Stub
notificationstwilio	Twilio (SMS) — Stub
notificationsfirebase	Firebase (push) — Stub

Webhooks (outbound + inbound)

Module	What it provides
callbacks	Outbound webhook subsystem (HMAC dispatcher + audit + REST admin + SDK)
webhooks	Inbound ingestion (Stripe / GitHub / Twilio / generic HMAC validators + DLQ + SDK)

04 — Starters

Module	What it bundles
startercore	web + cache + observability + eda + cqrs + actuator + lifecycle + scheduling
starterapplication	startercore + plugins.Registry
starterdomain	startercore + in-memory event-sourcing stores
starterdata	startercore (consumer supplies their own DB)
backoffice	starterapplication + back-office context middleware

05 — Tests

Module	Purpose
tests/	Cross-module integration suite (CQRS + callbacks + webhooks + saga roundtrips)

06 — Samples

Path	Purpose
samples/orders/	Five-package reference service demonstrating idempotent POST + cached GET + actuator + lifecycle