Part 2 · 1 chapters · ~10 min

Interfaces

Interface control for software: the boundaries of one service and their owners, what an interface control document states beyond the schema, the semantic gap that schemas miss, versioning rules, contract tests on both sides, and ownership with a change process.

Interface control, contracts and versioning

boundaries with owners

List every interface and the team that owns each side.
An ICD covers data, units, semantics, timing, errors and guarantees.
Semantic gaps: the schemas match but the meanings differ.
Versioning: additive changes are compatible. Changes of meaning are breaking.
Verification: contract tests on both sides.
Ownership and a change process. Public interfaces only ever get new versions.

code

# icd/loan-events.md (excerpt): the part a schema cannot say
event: LoanRepaid
schema: schemas/loan-repaid.v2.json
emitted: when a repayment is RECEIVED (not settled). Direct debits may reverse for up to 3 business days.
follow-up: LoanSettled is emitted when the final repayment can no longer be reversed.
           Consumers that certify anything (e.g. clearance letters) MUST wait for LoanSettled.
amounts: integer kobo; currency always NGN on this topic
ordering: per loan_id (partition key); no ordering across loans
delivery: at least once; dedupe on event_id
owners: producer = Loans Ledger (#loans-ledger); consumers = Clearance (#clearance), Notifications
change process: RFC in #api-changes, 2-week review, both owners sign off; breaking changes → v3 topic

INTERFACE CONTROL

every boundary has a documented contract, an owner on each side, and a change process

swipe the figure sideways, or tap expand for full screen

1/6

the interfaces

The interfaces of the clearance service: the repayment events it consumes from the loan ledger, the balance query it makes to the ledger, the signing request to the HSM service, the document store, the public verification endpoint third parties call, and the notification service. Six boundaries, five owning teams.