LinkedIn Carousel: Provider Vocabulary Normalisation

Post type: Technical · 10 slides
Blog post: https://www.nuvikatech.com/blog/posts/provider-vocabulary-normalisation

SLIDE 1 — Cover

Headline: AWS says “resolved”. Azure says “closed”. GCP says “SOLUTION_PROVIDED”. Get the translation wrong and valid credits are silently marked as denied.

Sub-line: The vocabulary normalisation bug that nearly shipped — and the architecture that prevents the entire class of problem.

SLIDE 2

Label: THE PROBLEM

Headline: Multi-cloud integration is fundamentally a translation problem.

Body: Every cloud provider evolved its own vocabulary for the same concepts. Support case statuses, resource names, billing categories — different words for identical things. Build without translating and you write provider-specific code for every feature.

SLIDE 3

Label: THE TRAP

Headline: GCP: “CLOSED” means denied. “SOLUTION_PROVIDED” means approved. Two completely different outcomes.

Body: Not a typo. Not an edge case. GCP’s support API uses “CLOSED” for rejected claims and “SOLUTION_PROVIDED” for approved ones. If you treat “CLOSED” as “approved”, you mark denied claims as credits.

SLIDE 4

Label: THE BUG WE SHIPPED

Headline: Raw status “resolved” hit the else branch. Result: “Credit Denied.” For every approved AWS claim.

Body: Our poll endpoint checked if credit_status == "approved". AWS get_claim_status() returned the raw string “resolved”. No match → else → Credit Denied. No exception. No log warning. Just wrong data.

SLIDE 5

Label: HOW IT WAS CAUGHT

Headline: A code review that traced the full flow — from provider API response to database write.

Body: Not caught by tests. Not caught by the first review pass. Caught by someone reading the poll endpoint carefully and asking: “what does get_claim_status() actually return?” That question revealed the gap.

SLIDE 6

Label: THE FIX

Headline: Normalise at the provider layer. The consumer only ever sees approved / denied / pending / unknown.

Body: Each provider strategy maps its own vocabulary to our four-value internal set. AWS: “resolved” → approved, “work-in-progress” → pending. GCP: “SOLUTION_PROVIDED” → approved, “CLOSED” → denied.

SLIDE 7

Label: BELT AND SUSPENDERS

Headline: If a status isn’t in our known vocabulary, skip the update entirely.

Body: if credit_status not in ("approved", "denied", "pending"): continue. When a provider returns something unexpected, we skip the write rather than guess. The breach stays in “Filed” until the next poll.

SLIDE 8

Label: WHY NOT IN THE CONSUMER

Headline: Centralising normalisation in the poll endpoint doesn’t scale.

Body: Every new provider would require changes to the poll endpoint. Every AWS edge case would sit next to GCP’s. Normalising at the provider strategy layer means the poll endpoint never needs to know about provider-specific vocabulary.

SLIDE 9

Label: THE PRINCIPLE

Headline: Normalise at the boundary. When AWS changes their strings, you update one map in one file.

Body: The provider strategy is the boundary — it speaks the provider’s language and translates to yours. Everything upstream speaks only your internal vocabulary. Maintenance is isolated. Blast radius is minimal.

SLIDE 10 — CTA

Headline: Want the full story?

Body: The full vocabulary normalisation architecture: the bug that almost shipped, the fix, and the broader principle for any system integrating with multiple external APIs.

Link: nuvikatech.com/blog/posts/provider-vocabulary-normalisation