Architecture Decision Records on Pledger.io

ADR-001 Contract-first OpenAPI with Micronaut code generation

Mon, 01 Jan 0001 00:00:00 +0000

Status

Accepted

Context

The REST API must stay consistent for the separate web UI and any API clients. Handwritten controllers and DTOs tend to drift from documentation unless the contract is the single source of truth.

The project already ships an OpenAPI 3.1 description split across src/contract/ and uses the Micronaut OpenAPI Gradle plugin.

ADR-002 Multi-database strategy with dialect-specific Flyway migrations

Mon, 01 Jan 0001 00:00:00 +0000

Status

Accepted

Context

Users self-host Pledger.io on different environments. The application supports PostgreSQL, MySQL, and H2 (development/tests). SQL dialects differ (types, indexes, functions), so a single generic migration script set is fragile.

Decision

Use Flyway with separate migration trees under src/main/resources/db/migration/ (for example psql/ and mysql/). Select the appropriate datasource and Flyway locations via Micronaut configuration profiles. Rely on dialect-appropriate drivers at runtime.

ADR-003 Use Jetty as the HTTP server runtime

Mon, 01 Jan 0001 00:00:00 +0000

Status

Accepted

Context

Micronaut supports multiple HTTP runtimes (notably Netty and Jetty). The choice affects threading model, integration with servlet-style features, dependency footprint, and operational familiarity.

Decision

Configure the Micronaut application to use runtime("jetty") and depend on micronaut-http-server-jetty as the embedded server for this service.

ADR-004 Enforce modular boundaries with ArchUnit

Mon, 01 Jan 0001 00:00:00 +0000

Status

Accepted

Context

The codebase is a modular monolith: many bounded contexts in one repository. Without enforcement, package dependencies creep across boundaries (“just one import”), cycles appear, and refactors become risky.

Decision

Use ArchUnit in ArchitectureTest to enforce:

ADR-005 Legacy Camunda Flyway migrations without Camunda runtime

Mon, 01 Jan 0001 00:00:00 +0000

Status

Accepted

Context

Older versions of Pledger.io used Camunda BPM for batch import workflows. The database still contains Camunda-style tables created by historical migrations. The application no longer embeds Camunda; imports are driven by an in-process ImportProcessEngineImpl and related domain code under exporter.