Project Layout

Project Layout

What this page covers: the repository's module map — the four Gradle modules (core / libby / manager / manager-jedis) and what each produces — plus the package tree inside :core so you can find any feature fast.

---

The module map at a glance

EveryDatabase/
├── core/           everydatabase-core          the library + every backend (RECOMMENDED flavor)
├── libby/          everydatabase-libby         runtime-download coordinator (thin)
├── manager/        everydatabase-manager       OPTIONAL add-on: typed refs + caching
├── manager-jedis/  everydatabase-manager-jedis OPTIONAL add-on: Jedis (Redis/Valkey) cache-sync transport
├── docker-compose.yml                          MariaDB / PostgreSQL / MongoDB / Valkey / Redis for the integration suites
└── wiki/                                        this developer wiki

All four modules publish under group br.com.finalcraft.everydatabase, version 1.0.9. The Gradle paths are :core, :libby, :manager, :manager-jedis (declared in settings.gradle).

🧭 Decision — core and libby are two packagings of the same code (pick exactly one as a consumer — see Distribution Flavors and Installation). manager is a separate optional feature layer, not a flavor: you add it on top of a core flavor.

---

What each module is

core/ — everydatabase-core

The library itself, the recommended flavor: all production code, every backend dependency declared as a normal POM dependency. The only module with a full source tree; the others package or extend it. Compiled to Java 8 bytecode via the Jabel dual-target (Building from Source).

libby/ — everydatabase-libby

A thin coordinator that downloads the full dependency set at runtime via Libby. Its only sources are the coordinator classes in package br.com.finalcraft.everydatabase.libby — DependencyManager, EveryDatabaseDependencies, util.LibraryFactory. Its POM depends on :core non-transitively, so the heavy deps never enter the consumer's build-time graph. Test: LibbySmokeTest.

manager/ — everydatabase-manager

The optional add-on: typed references (Ref<K, V>) plus per-type caching managers that sit in front of :core. Depends on :core (compileOnly — kept out of the published POM, so a consumer adds both everydatabase-manager and everydatabase-core explicitly); in the dual-target Java-8 list. Full guide: Caching & References.

manager-jedis/ — everydatabase-manager-jedis

An optional add-on to the add-on: a Jedis-based implementation of the manager's CacheSyncTransport SPI, publishing cache-invalidation signals over a Redis/Valkey pub/sub channel (one client speaks to both). Its sources live in package br.com.finalcraft.everydatabase.manager.sync.jedis (JedisCacheSyncConfig, JedisCacheSyncTransport). It depends on :manager and :core (compileOnly, kept out of the published POM) and brings in redis.clients:jedis — so a consumer wanting Redis-backed cache sync adds everydatabase-manager-jedis on top of core + manager. In the dual-target Java-8 list.

📌 Note — :core must not depend on :manager. That one-way dependency is why the ref-aware codec lives in the manager module (vended by RefRegistry.codec(...)) rather than being baked into core's codecs. See Codecs.

---

Inside :core — the package tree

All production code lives under core/src/main/java/br/com/finalcraft/everydatabase/:

br/com/finalcraft/everydatabase/
├── (root)            Storage, Repository, EntityDescriptor, Storages, StorageConfig,
│                     StorageExecutors, StorageKeys, HealthStatus
├── codec/            Codec<V>, JacksonJsonCodec (compact / pretty), JacksonYamlCodec
├── query/            IndexHint, @Indexed, Query, Condition
├── versioned/        @OptimisticLock, Versioned, OptimisticLockException, OptimisticLockScanner
├── tx/               TransactionalStorage, TransactionScope
├── schema/           SchemaAwareStorage, Migration, MigrationContext
├── changefeed/       ChangeFeedStorage, ChangeEvent, ChangeFeedSupport
├── log/              StorageLogConfig, StorageLog, topics / levels / sinks
├── transfer/         StorageTransfer, TransferReport, ErrorPolicy
└── modules/          the backend implementations:
    ├── sql/          SqlStorage / SqlConfig / SqlRepository / SqlMigration (MySQL/MariaDB dialect)
    │   ├── postgresql/   PostgreSqlStorage (dialect overrides; ChangeFeedStorage via LISTEN/NOTIFY)
    │   └── h2/           H2SqlStorage (dialect overrides; opts out of versioning)
    ├── mongo/        MongoStorage / MongoConfig / MongoRepository / MongoMigration
    ├── localfile/    LocalFileStorage / LocalFileConfig / LocalFileMigration
    ├── groupedfile/  GroupedFileStorage / GroupedFileConfig / GroupedFileMigration
    └── memory/       InMemoryStorage / InMemoryConfig

How the packages map to the docs:

Package	What it owns	Guide
(root)	the core contract + the Storages factory	Architecture Overview · The Async API
codec/	serialization strategy	Codecs
query/	secondary indexes + queries	Indexing & Queries
versioned/	optimistic locking	Optimistic Locking
tx/	transactional capability	Transactions
schema/	migration capability	Schema Migrations
log/	logging config + sinks	Logging & Diagnostics
transfer/	cross-backend copy	Moving Data Between Backends
modules/*	per-backend implementations	Choosing a Backend and the per-backend pages

💡 Tip — the optional capabilities (tx, schema) are interfaces a Storage may implement, discovered with instanceof — not flags. A backend in modules/* implements exactly the capability interfaces it can honor. This idiom is the spine of the design; see Architecture Overview.

Each modules/* backend ships its own *Config, *Storage, *Repository (and *Migration where applicable). The sql base carries the MySQL/MariaDB dialect; sql/postgresql and sql/h2 are subclasses that override identifier quoting, column types, and upsert SQL.

---

Inside :manager — the package tree

Under manager/src/main/java/br/com/finalcraft/everydatabase/manager/:

manager/
├── Ref.java                 the typed reference (serializes as its key)
├── RefRegistry.java         per-context registry: vends codec(...) / manager(...) / ref(...)
├── RefResolver.java         the resolution SPI a CachingManager implements
├── CachingManager.java      cache-backed façade over one Repository (stats() → observ)
├── RefPolicy.java           the @RefPolicy field annotation
├── BatchSaveReport.java     flushDirty() result
├── cache/                   CacheEntry (cell + stamps), CachePolicy, CacheOptions, LruCacheStore,
│                            IDirtyable / @DirtyFlag (write-back)
├── jackson/                 RefModule, RefSerializer, RefDeserializer, RefCodecs
├── observ/                  CacheStats, CacheSyncStats, CacheSyncObserver
└── sync/                    CacheSync, PollingCacheSync, CacheSyncTransport, KeyParsers

See Caching & References for the runnable guide and the cell/stamp model.

---

Tests

• :core tests live under core/src/test/java/... — the abstract contract suites (AbstractStorageTest, AbstractTransactionalStorageTest, AbstractVersionedStorageTest), per-backend concrete classes, the @Tag("stress") suites, and shared helpers in testutil/ (ThrowawayDatabaseSupport, DotEnvTestUtil, CapturingSink). Test entities are in data/.
• :libby has LibbySmokeTest.
• :manager tests run on the embedded backends, with entities under testdata/ and testdata.multibackend/.
• :manager-jedis tests exercise the Jedis pub/sub transport against Valkey/Redis (Docker; self-skip when down), reusing :manager's test entities.

Running any of these is covered on Running the Tests.

---

See also

• Building from Source — JDK 25 launcher, the Jabel dual-target, gradlew tasks.
• Running the Tests — Docker compose, throwaway DBs, the switches.
• Distribution Flavors — the deep comparison of core / libby.
• Architecture Overview — how the root-package types and the capability interfaces fit together.
• Caching & References — the :manager add-on in full.