Modules¶

Failover is composed of focused modules. The starter pulls everything in — declare individual modules only when you need fine-grained dependency control.

flowchart TD
    STARTER[failover-spring-boot-starter]
    AC[failover-spring-boot-autoconfigure]
    DOMAIN[failover-domain]
    CORE[failover-core]
    ASPECT[failover-aspect]
    IMM[failover-store-inmemory]
    CAF[failover-store-caffeine]
    JDBC[failover-store-jdbc]
    ASYNC[failover-store-async]
    MT[failover-store-multitenant]
    RES[failover-execution-resilience]
    SCHED[failover-scheduler]
    SCAN[failover-scanner]
    LOOKUP[failover-lookup]
    MIC[failover-observable-micrometer]
    DASHSTARTER[failover-dashboard-spring-boot-starter]
    DASH[failover-dashboard]

    STARTER --> AC
    AC --> DOMAIN
    AC --> CORE
    AC --> ASPECT
    AC --> IMM
    AC --> ASYNC
    AC --> SCHED
    AC --> SCAN
    AC --> LOOKUP
    MIC --> SCAN
    DASHSTARTER --> DASH
    DASH --> SCAN

The dashboard is a separate, opt-in add-on: the default starter does not depend on it, and it does not depend on failover-spring-boot-autoconfigure.

Core Modules

failover-domain · failover-core · failover-aspect — annotation, interfaces, and the AOP interceptor.

Core internals
JDBC Store

Production-grade persistence — H2, PostgreSQL, MySQL, MariaDB, Oracle, SQL Server.

JDBC store
Caffeine Store

Fast in-process cache backed by Caffeine — ideal for single-node deployments.

Caffeine store
Async Store

Non-blocking write decorator using virtual-thread executor — zero read-path latency.

Async store
Multi-Tenant Store

TABLE_PREFIX or SCHEMA strategy routes each request to the correct tenant store.

Multi-tenant
Resilience

Resilience4j circuit-breaker wraps upstream calls. Trips fast on repeated failures.

Resilience integration
Scheduler

Expiry-cleanup (hourly) and observable-report (daily) scheduled tasks.

Scheduler
Observability

Startup scanner, Micrometer counters, and health indicator — zero extra config.

Observability
Dashboard

Opt-in, secure-by-default embedded UI over the existing config and meters — KPI cards and charts.

Dashboard

Full module reference table

Module	Purpose
`failover-domain`	`@Failover` annotation, `Referential`, `ReferentialAware`, `Metadata`
`failover-core`	All interfaces + default implementations
`failover-aspect`	Spring AOP `@Around` interceptor
`failover-store-inmemory`	`ConcurrentHashMap` store — dev/test only
`failover-store-caffeine`	Caffeine-backed in-process store
`failover-store-jdbc`	JDBC store — H2, PostgreSQL, MySQL, Oracle, MariaDB
`failover-store-async`	Non-blocking write decorator (virtual-thread executor)
`failover-store-multitenant`	TABLE_PREFIX / SCHEMA per-tenant routing
`failover-execution-resilience`	Resilience4j circuit-breaker integration
`failover-scheduler`	Expiry-cleanup + observable-report schedulers
`failover-scanner`	Startup scanner for `@Failover` methods
`failover-lookup`	Spring `BeanFactory` lookups for named `KeyGenerator` / `ExpiryPolicy` / `PayloadSplitter` beans
`failover-observable-micrometer`	Micrometer counters + health indicator
`failover-dashboard`	Opt-in embedded observability UI + read-only JSON API (local / Prometheus / shared-store cluster modes)
`failover-dashboard-snapshotstore-jdbc`	Optional durable JDBC `SnapshotStore` for the dashboard `shared-store` cluster mode
`failover-dashboard-spring-boot-starter`	The only artifact a consumer adds to obtain the dashboard

Next Steps¶

Core — key interfaces and the default handler chain
Store Types — choosing a backing store