Architecture Decision Records

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. ...

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. ...

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. ...

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: ...

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. ...