Skip to content

bird-platform

A Kotlin + Spring Boot reference platform, built to make production-grade patterns tangible.

An open-source backend built as an interview-grade reference: a deliberate tour of production-grade patterns, from hexagonal architecture and DDD bounded contexts to a transactional outbox, event sourcing, optimistic-locking concurrency and compensating sagas, each applied where the domain actually warrants it, not as pattern cosplay.

KotlinSpring BootPostgresElasticsearchView on GitHub (opens in new tab)

The idea

Most reference platforms are either a to-do list with one clever bit bolted on, or a pattern zoo where every technique is crammed in whether the problem needs it or not; bird-platform sits in the middle: a coherent domain rich enough that each pattern earns its place, and disciplined enough that the boundaries stay clean.

It is explicitly a showcase, not a product. Interview-worthy patterns are valued over realistic business value; the point is to demonstrate the patterns cleanly, and to show the judgement of where each one belongs.

Try it live

This one you can poke, not just read about. The frontend is a small single-page app hand-built on ripple, the signals library from the same set, with no framework: species search, the booking flow, and a two-panel version-race that fires two confirms at one booking so you can watch the optimistic lock pick a winner and hand the loser a 409.

The behaviour is real, only the engine is swapped. Hosted, the UI runs against an in-browser model that mirrors the backend’s rules exactly: the same compare-and-swap, idempotency and state machine. To put the actual Kotlin service on Postgres behind the same UI, run the demo container:

git clone https://github.com/raby/bird-platform
cd bird-platform
docker compose -f docker-compose.demo.yml up --build
# then open http://localhost:8080

Why a birdwatching domain

Picture a rare warbler turning up at a reserve overnight. By dawn the local recording group has seen the alert, and thirty people want one of the six seats in the hide before breakfast. Somewhere behind that scramble sits a database row, and exactly one system gets to decide, correctly, who is actually let in.

DigitalBluebird is a citizen-science platform for bird observers: log sightings against a searchable global species catalogue, find the nearest reserves and book their limited-capacity hides and guided expeditions, claim a breeding-survey plot for a season, request access permits during rare-bird events, and sync sightings out to eBird and iNaturalist.

Ornithology turns out to be an unusually rich bounded-context playground, because every technical choice has a plain, tellable domain reason behind it:

Real-world needTechnical analogue
Species taxonomy + fuzzy searchRead-optimised search store (Elasticsearch)
Legally binding sighting recordsTransactional, audit-friendly SQL (Postgres)
Limited hide capacity on a migration dawnConcurrency control + seat-reservation
Survey-plot ownership across a seasonExclusive claim + event-sourced provenance
Observers to tell when a booking lands or falls throughIdempotent, event-driven notifications (the inbox pattern)
A guided outing across several hides, all or nothingMulti-step orchestration + compensation (a process manager)
Which reserves are near where I amGeospatial search (PostGIS)
eBird / iNaturalist syncAnti-corruption layer + resilient (circuit-breaker) outbound sync
Looking up taxonomy from a rate-limited authorityRead-through cache (TTL + serve-stale)

That mapping is the spine of the whole project: no pattern is present unless a real ornithological need pulls it in.

The architecture

Hexagonal, with DDD bounded contexts. Each of the eleven contexts (named in the diagram below) is a self-contained module with the same internal shape: a pure domain, inbound and outbound ports, an application layer, and adapters for web and persistence. The boundaries are enforced by Spring Modulith, so a context can only reach another through a declared interface.

Purity is a test, not a hope. An ArchUnit rule set, run in CI, fails the build if the domain layer ever imports Spring, Jakarta, JDBC, or an adapter, so the hexagon’s dependency rule cannot quietly rot as the code grows.

Errors are values, not exceptions. Every domain operation returns Arrow’s Either<DomainError, T>. Failure is part of the type signature, callers must handle it, and the happy path stays uncluttered by try/catch.

bird-platform: the hexagonal architecture of a bounded contextA web adapter sends requests through an inbound port into the application layer, which surrounds a pure domain core. The application reaches persistence (Postgres and Elasticsearch) through an outbound port. All eleven bounded contexts share this shape and are isolated by Spring Modulith; an ArchUnit rule keeps the domain free of framework imports.applicationdomainpure coreWeb adapterRESTinbound portPersistencePostgres · Elasticsearchoutbound portEleven bounded contexts, each this exact shape, isolated by Spring Modulithobservations · bookings · species · permits · surveys · expeditions · reserves · identity · notifications · ebird · taxonomy
Every bounded context shares this hexagonal shape: a request enters through a web adapter, the application orchestrates a pure domain, and persistence is reached through an outbound port. An ArchUnit rule set, run in CI, fails the build if the domain layer ever imports Spring, Jakarta or JDBC, so the dependency rule cannot quietly rot.

The concurrency showpiece: hide bookings

The centrepiece is the bookings context, where a real constraint (a hide holds six to twelve people, and on a rare-bird morning far more than that try to book at once) forces genuine concurrency control. Four mechanisms combine:

  • An explicit state machine. A booking is REQUESTED, CONFIRMED, or CANCELLED, and the legal transitions are codified, not implied. An illegal transition is a typed error, never a silent no-op.
  • Optimistic locking. Each booking carries a version; a concurrent update against a stale version loses cleanly rather than double-booking a seat.
  • Idempotency keys. A retried request (the classic double-tap on a slow network) is de-duplicated, so the same booking is never created twice.
  • Slot exclusivity, guaranteed by the database. A Postgres GiST exclusion constraint makes two overlapping active bookings on a hide impossible at the storage layer. The service pre-checks for a fast, friendly rejection, but the constraint is the authority: under a real race the loser is turned away by the database itself, not by a check that happened to run a moment too early.

The aggregate stays pure and immutable: a transition returns a new Booking or a typed error, and never throws:

enum class BookingStatus {
    REQUESTED, CONFIRMED, CANCELLED;
    fun canTransitionTo(next: BookingStatus) = when (this) {
        REQUESTED -> next == CONFIRMED || next == CANCELLED
        CONFIRMED -> next == CANCELLED
        CANCELLED -> false
    }
}

data class Booking(/* … */ val status: BookingStatus, val version: Long) {
    fun confirm(now: Instant): Either<BookingError, Booking> =
        transition(BookingStatus.CONFIRMED, now)   // invalid → StateTransitionNotAllowed
}

The rest of the tour

Each context demonstrates a different pattern, kept behind its boundary:

  • Observations. A transactional outbox: a sighting and its “sighting recorded” event commit in the same transaction, so the event publishes reliably without a distributed transaction.
  • Species catalogue. A read model in Elasticsearch for fuzzy taxonomy search, kept behind an anti-corruption layer so the external Avibase taxonomy never leaks into the domain.
  • Surveys, event-sourced. A plot’s ownership is an append-only stream of claim and release events, not a mutable “held-by” column: the current holder is the fold of that stream, and who held it when is the log itself. Each append carries the stream position as an optimistic-concurrency token, so two observers racing to claim the same plot cannot both win.
  • Permits, and the visitor-permit saga. A per-hide daily visitor cap lives in its own context. When a booking is confirmed, a saga debits a permit across the context boundary; if the day is already full it compensates by cancelling the over-cap booking, freeing the seat through the same outbox. Cross-context orchestration with a compensating action, not a distributed transaction.
  • Notifications, the inbox pattern. The receive side mirrors the outbox. A booking confirmed or cancelled becomes a notification, deduplicated on the source event id, so the same event delivered more than once still produces a single notification. Recording the notification is one transaction; sending it is a separate, retrying step, so a slow channel never holds up a booking. Effectively once, assembled from at-least-once parts.
  • eBird sync, with a circuit breaker. Recorded sightings are pushed out to eBird through an anti-corruption layer that maps the platform’s model to eBird’s checklist format, so eBird’s vocabulary never reaches the domain. The call is wrapped in a hand-rolled circuit breaker and retry: a transient blip is retried, but once eBird is failing the breaker opens and the sync fails fast instead of hammering a dead service, probing for recovery after a cooldown. The push is driven off the outbox and queued idempotently, so it is reliable without putting a flaky third party on the write path.
  • Expeditions, a process manager. A guided expedition books several hides for one party as a single all-or-nothing outing. This is a process manager, not a one-shot reaction: a persisted state machine books each hide in turn, and if a slot cannot be held it releases the ones already booked and fails the outing. It also listens: if the visitor-permit saga later cancels an over-cap hide, the expedition compensates the rest. Two orchestrations meeting over the outbox, each step its own local transaction, unwound by a compensating action rather than a rollback.
  • Reserves, geospatial. A reserve is a place, so “which reserves are near me?” is a geospatial question. Each reserve sits at a point on a PostGIS geography column; find-nearby selects the ones within a radius with ST_DWithin and orders them nearest-first with the <-> operator, both served by a GiST index. The one capability nothing else in the platform needs, added exactly where the domain asks for it.
  • Taxonomy, read-through cached. Species taxonomy is near-static reference data behind a rate-limited external authority, so lookups are cached: a fresh hit returns at once, a miss or an expired entry is fetched and cached, and if the authority is unreachable an expired value is served rather than failing. That is graceful degradation (for data that barely changes, a stale classification beats none), and each result says whether it came from the cache, the authority or a stale fallback.

Rigor

  • ArchUnit pins the layering rules described above, in CI.
  • Testcontainers spins up real Postgres and Elasticsearch for integration tests, so persistence and search are exercised against the real engines, not mocks.
  • Flyway migrations are numbered per context, so each context owns its own schema range.

This is a focused reference rather than a sprawling system, and it is built to be read: a sequence of self-contained vertical slices, each landing in a single reviewed commit, from the shared foundation and the bookings concurrency work out to each bounded context in turn. Each slice stands on its own, so the git history itself reads as a guided tour of the patterns.

The point

bird-platform is a place to show, cleanly and end to end, that the patterns a senior backend engineer is expected to know are known here: how to draw a bounded context, when to reach for an outbox versus a saga, how to make concurrency safe under contention, and how to keep a domain model pure while still shipping a real API. The birding theme keeps it on brand for Digital Bluebird, and the domain keeps every decision honest.