ADR 0002: Expose a canonical neobank API over Perflo adapters
This record prevents upstream service differences from becoming public product behavior.Context
Perflo publishes four OpenAPI surfaces with different authentication headers, inline schemas, and incomplete error contracts. The neobank needs stable resources and errors.Decision
Define provider-neutral account, beneficiary, quote, transfer, mandate, card, operation, and error models. Put every Perflo call behind a typed adapter. Preserve raw upstream codes only in restricted operational metadata.Consequences
The public API can version independently. Adapter contract tests must detect upstream drift, and unsupported upstream capabilities fail with explicit capability errors. ADR 0013 clarifies this record’s scope: the provider-neutral models are the ones its decision enumerates, and the Perflo connection lifecycle was never among them.Rejected alternatives
- Transparent proxy: it would expose inconsistent authentication and error behavior.
- Generated client as public model: weak inline upstream schemas would become a compatibility burden.