Refine the service architecture ahead of the integrations work

Type

Tech Debt. No user will notice this directly. Every future integration will.

Problem

Integration logic is currently spread across the request handlers. Each new third-party service means touching code that has nothing to do with it, and the blast radius grows every time.

Acceptance criteria

• Current architecture documented as-is, including the parts nobody likes
• Target architecture proposed with the trade-offs stated, not hidden
• Migration path defined in increments that each ship on their own
• Decision recorded as an ADR, so the next person inherits the reasoning and not just the result
• Reviewed by the whole team, not just its author

Blocks

• Integrate with third-party apps

On reserving capacity

Hold roughly 15–20% of each sprint for work like this. Teams that reserve nothing spend it anyway, just later and at a worse exchange rate.