AI EngineeringZero to ProductionHome·About·Contact
Case Studies & Reference Architectures · Part 9

Standing up a shared AI platform

A full end-to-end walkthrough of standing up a shared, multi-team AI platform — an internal LLM gateway with model routing, cost governance, self-serve onboarding, and golden paths — so a dozen product teams can build on AI without each reinventing keys, guardrails, and billing. Problem → gateway architecture → routing → cost governance → self-serve + golden paths → platform-team topology → rollout. Representative composite; engineering-leadership framing.

⏱️ ~2.5 hours🧪 7 steps🎯 Advanced→Tech-lead

Learning objectives

  • Frame the platform problem: a dozen teams each wiring their own keys, guardrails, and billing is duplicated, unsafe, and unobservable.
  • Design an internal AI gateway that centralizes auth, routing, guardrails, caching, logging, and spend control behind one contract.
  • Route requests across models/providers by capability, cost, and availability — with fallback — without leaking that choice to callers.
  • Govern cost with per-team budgets, quotas, chargeback, and caching, so spend is attributable and bounded.
  • Ship self-serve onboarding and golden paths so teams adopt the platform because it's the fastest route, not because they're forced.
  • Choose a platform-team topology (Team Topologies-style) and a rollout that treats the platform as an internal product.
Representative scenario — not a real customerThe company, the team count, the budgets, and every number below are an illustrative composite invented for teaching. They are not a real deployment and no figure is a claimed result. The platform-engineering patterns are real, industry-standard practice; the story is a teaching device.

Meet "Vanta Corp" — a representative composite. A year into the AI gold rush, Vanta has a dozen product teams each shipping LLM features. Every team has independently wired up its own API keys, its own retry logic, its own half-built guardrails, and its own untracked spend. Nobody can answer "what are we spending on AI and on what?", two teams just leaked a key, and each team re-solves prompt-injection defense from scratch — badly. The mandate: stand up a shared AI platform so teams build features, not plumbing. This is the classic platform-engineering job applied to AI, dominated by three forces: you must remove duplicated toil, you must make the safe path the easy path, and you must make spend attributable and bounded.

1 · Framing the platform — what "shared" has to buy

A platform is only worth its own team if it removes more toil than it adds. Start by naming the duplicated, dangerous, or unobservable things every product team is doing today — because each one becomes a capability the platform centralizes. If the list is short, you don't need a platform yet; if it's this long, you can't afford not to have one.

Today, every team…The cost of thatWhat the platform centralizes
Manages its own provider keysKey sprawl, rotation gaps, leak risk.One brokered credential; teams never hold provider keys.
Re-implements guardrailsInconsistent, often weak, injection/PII defense.A shared, versioned guardrail layer, on by default.
Picks a model ad hocOverpays or under-delivers; no consistency.Capability-based routing with fallback.
Has untracked spendNo one can attribute or cap AI cost.Per-team metering, budgets, and chargeback.
Rebuilds retries/cachingDuplicated effort; inconsistent reliability.Shared resilience + prompt caching in one place.
Logs nothing consistentNo org-wide observability or audit.Uniform request logging, tracing, and metrics.
A platform is a product, and its customers are your own teamsThe single most useful reframe: the platform team's customers are the product teams, and adoption is voluntary in spirit even if mandated on paper. If the platform is slower or clumsier than a team calling the provider directly, teams will route around it — and you'll have built shadow IT with extra steps. Every decision below is in service of making the platform the fastest way to ship an AI feature.

2 · The AI gateway — one contract in front of everything

The heart of the platform is an internal AI gateway: a single service every team calls instead of a provider directly. It owns the cross-cutting concerns so no team has to. Read the diagram as one request's life: a team app authenticates to the gateway, which applies guardrails, checks the team's budget, routes to the right model (with caching and fallback), logs everything, and returns a clean response. The caller never sees keys, never sees which model answered, and never has to build any of it.

Team app service identity Gateway auth no team keys Guardrails + budget safe + bounded Model router capability + cost Provider / model brokered key Log + meter per-team spend
Why one gateway beats a shared libraryYou could ship a shared client library instead of a gateway. Libraries drift: teams pin old versions, skip the guardrail update, and you can't enforce spend or rotate a key centrally. A gateway is a runtime boundary — guardrails, budgets, routing, and key rotation apply to every call the moment you change them, with no team redeploy. Ship a thin client SDK for ergonomics, but the enforcement lives in the gateway.

3 · Model routing — the right model, hidden from the caller

With every request flowing through one place, the gateway can make the model choice for the team — by capability, cost, and availability — and change it centrally without a single caller redeploying. Teams request a capability tier ("cheap-fast", "balanced", "frontier"), not a specific model name, so you can swap models, add providers, or fail over transparently.

Routing inputHow it steers the choiceWhy it's centralized
Capability tierTeam asks for cheap-fast / balanced / frontier by intent.Decouples callers from model names; you swap models freely.
CostPrefer the cheapest model that meets the tier's quality bar.One place to enforce the cost/quality tradeoff org-wide.
AvailabilityFail over to an alternate provider on error/timeout.Every team gets resilience without building it.
PolicySome data classes pinned to a region/provider.Compliance routing enforced once, not per team.
Route on capability tiers, not model namesIf teams hard-code "model-x-latest", you can never migrate: every model change becomes a dozen coordinated redeploys. Expose intent-level tiers instead, map tiers to concrete models in the gateway, and you can upgrade a model, add a fallback, or shift cost profiles for everyone at once. Model names are an implementation detail the platform owns — verify current model availability and pricing in provider docs, which drift often.

4 · Cost governance — spend that's attributable and bounded

The reason finance blessed the platform is this section. Because every call is authenticated and metered, the gateway turns AI spend from an untraceable lump into a per-team, per-feature line item — and, crucially, it can enforce budgets, not just report them. Four mechanisms, layered, give you FinOps for AI: metering, budgets, quotas/rate-limits, and shared caching.

How the gateway governs cost

  1. Meter every call — attribute input/output tokens and cost to a team and feature via the auth identity.
  2. Per-team budgets — a monthly cap; approaching it alerts the team, exceeding it soft-fails to a cheaper tier or blocks non-critical calls.
  3. Quotas + rate limits — per-team RPS/concurrency so one team's runaway loop can't starve everyone.
  4. Shared prompt caching — common system prompts/context cached once at the gateway, cutting cost across all teams (verify cache pricing/TTL in provider docs).
  5. Chargeback / showback — a monthly per-team report so cost is owned by the team that incurs it.
Budgets must be enforceable, not just dashboardsA cost dashboard nobody's budget depends on changes no behavior. The platform's leverage is that it sits in the request path, so it can act: warn at 80% of budget, downgrade the tier at 100%, block non-critical calls beyond that. Pair enforcement with showback so each team sees — and owns — its own line. That combination is what actually bends the cost curve.

5 · Self-serve & golden paths — adoption by attraction

A platform that requires a ticket and a two-week wait to onboard a team will lose to teams calling the provider directly. The goal is self-serve: a team registers, gets a scoped identity, and ships against a golden path — a paved, documented, best-practice route for the common cases — in an afternoon. Golden paths aren't mandates; they're the easiest path, so teams take them by choice.

Self-serve capabilityWhat the team doesWhat they don't have to do
OnboardingRegister the app, get a scoped service identity + tier access.File a ticket; wait on the platform team.
Golden path: RAGFollow a template wiring retrieval + the gateway.Design grounding, citations, and guardrails from scratch.
Golden path: agentUse the paved tool-loop + guardrail defaults.Re-derive the agent loop and safety rails.
ObservabilityGet dashboards + tracing for free on every call.Instrument logging and metrics themselves.
GuardrailsInherit the shared, on-by-default guardrail layer.Build injection/PII defense per team.
Golden paths beat golden handcuffsYou can mandate the platform, but mandates breed resentment and workarounds. A golden path wins by being genuinely the fastest, safest way to ship the common case — guardrails, observability, and resilience come free, and the docs actually work. Teams with an exotic need can still go off-path (with more responsibility); most won't want to. Adoption by attraction is more durable than adoption by decree.

6 · Platform-team topology & the internal-product mindset

A platform needs an owning team, and how you structure it decides whether it thrives. Borrowing the publicly known Team Topologies vocabulary: the platform team is a platform team providing a self-serve internal product to stream-aligned product teams, and it should minimize the cognitive load it imposes — the whole point is to reduce what product teams must know. Early on it also acts as an enabling team, pairing with product teams to bootstrap adoption, then stepping back.

Team-topology roleWhoInteraction mode
Platform teamOwns the gateway, routing, guardrails, cost governance.Provides self-serve; treats teams as customers (X-as-a-Service).
Stream-aligned teamsThe dozen product teams building AI features.Consume the platform; own their features and budgets.
Enabling team (early)Platform engineers embedding temporarily.Pair to bootstrap the first adopters, then withdraw (Facilitating).
Cognitive load is the metric the platform team optimizesThe platform succeeds when a product team can ship an AI feature while knowing almost nothing about models, keys, guardrails, or billing. That's not fewer capabilities — it's the same capabilities behind a smaller surface. Every good API, default, and golden path lowers cognitive load; every leaky abstraction or mandatory-but-undocumented step raises it. Track adoption and time-to-first-call as your real product metrics.

7 · Rollout & the failure modes of a platform

Roll the platform out the way you'd roll out any internal product: land a lighthouse team, prove the golden path, then widen — never a mandate-first big bang. And a platform has its own failure modes, each mapping to a design choice already made above.

Stage / failure modeWhat happensThe design choice that handles it
Rollout 1 · LighthouseOne eager team ships on the platform, co-built.Enabling-team pairing proves the golden path (§5,§6)
Rollout 2 · WidenSelf-serve onboarding opens to more teams.Golden paths + docs make it the fastest route (§5)
Rollout 3 · Steady stateMost new AI features start on the platform.Attraction, not mandate; cognitive load stays low (§6)
Gateway is a SPOFOne service in every path can take everything down.HA + circuit-breaker fallback per provider (§2,§3)
Platform too slowTeams route around it to the provider.Thin client SDK; latency budget; golden-path ergonomics (§2,§5)
Runaway spendOne team's loop blows the org budget.Per-team quotas + enforceable budgets (§4)
Guardrail rotShared defense drifts out of date.Versioned, centrally-updated guardrail layer, on by default (§2)
The gateway is a single point of failure — design it like onePutting one service in every team's request path means its availability is now the org's AI availability. That's the price of centralization, and it's worth it — but only if you treat the gateway with the reliability rigor of critical infrastructure: HA/multi-instance, per-provider circuit breakers and fallback, graceful degradation, and a tested runbook. A cheap gateway that goes down takes a dozen features with it.
📋 Grade this design
DimensionMeets barAbove bar
Problem framed as toilLists what teams duplicate today.Each duplicated concern maps to a centralized platform capability.
Gateway as runtime boundaryProvides a shared endpoint.Enforces auth, guardrails, budgets, routing at runtime; changes apply with no team redeploy.
Capability-based routingPicks a model.Routes on tier/cost/availability with fallback; callers never see model names.
Enforceable cost governanceReports spend.Per-team metering + enforceable budgets + quotas + shared caching + chargeback.
Self-serve golden pathsHas onboarding docs.Teams onboard and ship in an afternoon; golden paths win by being the fastest, safest route.
Product-minded topologyNames an owning team.Platform-as-product; optimizes cognitive load; enabling-team bootstrap then withdraw.

Score each dimension Meets or Above. All six at least Meets = a platform teams will adopt by choice. Any dimension you can't hit is where teams will route around you.

✓ Knowledge check

A team lead says: "just give us the provider API key directly — the gateway adds latency and we know what we're doing." How do you respond as the platform owner?

Show answer
Handing out provider keys defeats the platform: you lose central key rotation, per-team cost attribution and budget enforcement (§4), the shared guardrail layer (§2), and org-wide observability. The right response is two-pronged: fix the reason they're asking — if the gateway's latency or ergonomics are the real complaint, that's a platform bug to close with a thin client SDK and a tight latency budget (§7) — and explain what the key buys the org: rotate-once security, an attributable AI bill, and guardrails that update everywhere at once. The goal is that the gateway is genuinely the easiest path, so this request stops coming up. Adoption by attraction, not by decree.
✓ Knowledge check

Why does the gateway expose "capability tiers" (cheap-fast / balanced / frontier) instead of letting teams name the exact model they want?

Show answer
Because model names are an implementation detail the platform must own to stay migratable. If a dozen teams hard-code a specific model, every model upgrade, price change, or provider fallback becomes a coordinated multi-team redeploy — so you never do it. Exposing intent-level tiers and mapping them to concrete models inside the gateway (§3) lets you swap models, add a fallback provider, or shift the cost/quality tradeoff for everyone at once, with no caller change. It also centralizes the cost/quality decision instead of scattering it across teams. (Model availability and pricing drift — verify in provider docs.)

🪜 Practice ladder beginner → industry

Six graded exercises, easy to real-world. Try each before opening its solution.

Exercise 1 · Justify building a platform at allBeginner

Context: Not every org needs an AI platform, and building one prematurely is its own waste. The first skill is arguing when the platform pays for itself.

Your task: List four things product teams duplicate today and, for each, the centralized capability that justifies a shared platform.

Requirements:

  • Name at least four duplicated/dangerous/unobservable concerns (keys, guardrails, model choice, spend, retries, logging)
  • For each, state the platform capability that replaces it
  • State the tipping point: roughly when the toil outweighs the platform's own cost
  • Note the failure case: a platform slower/clumsier than direct calls loses

💡 Hint: The justification is always toil-removed minus toil-added; if it's negative, don't build yet.

Show solution
  • Own keys → one brokered credential, central rotation; teams never hold provider keys.
  • Re-implement guardrails → a shared, versioned, on-by-default guardrail layer.
  • Pick models ad hoc → capability-tier routing with fallback, owned centrally.
  • Untracked spend → per-team metering, enforceable budgets, and chargeback.

Tipping point: once several teams are each rebuilding this — and no one can answer "what do we spend on AI and is it safe?" — the toil removed exceeds the platform's cost. Before that, a shared library may be enough. The platform loses the moment it's slower or clumsier than a direct provider call, so it must be built as the fastest path, not a tollbooth.

Exercise 2 · Design the gateway contractIntermediate

Context: The gateway is only adopted if its contract is clean and its enforcement is real. A leaky or slow contract sends teams back to direct calls.

Your task: Specify what the AI gateway owns and the request contract a team codes against — and why it's a runtime boundary, not a library.

Requirements:

  • Gateway owns: auth, guardrails, routing, caching, logging, budgets
  • Team sends: a capability tier + prompt/messages + a feature id; never a provider key
  • Gateway returns: a clean response plus usage metadata for metering
  • Explain why enforcement at runtime beats a shared client library
  • Note the thin client SDK is for ergonomics, not enforcement

💡 Hint: Design the contract so a team never touches keys, model names, or guardrail code.

Show solution
Team -> Gateway:
  { service_identity, feature_id, tier: cheap-fast|balanced|frontier, messages }
Gateway does:  auth -> guardrails -> budget check -> route(tier,cost,availability)
               -> provider call (cached, with fallback) -> log + meter
Gateway -> Team:
  { response, usage: {tokens_in, tokens_out, cost, model_used} }

The gateway owns auth, guardrails, routing, caching, logging, and budgets; the team sends intent (a tier + a feature id) and never a provider key or model name. It's a runtime boundary, not a library, because a guardrail update, a key rotation, or a routing change then applies to every call instantly — no team redeploy, no version drift. Ship a thin client SDK for ergonomics, but keep all enforcement server-side.

Exercise 3 · Design capability-based model routingAdvanced

Context: Hidden, central model routing is what lets a platform migrate models without a dozen redeploys. Get the abstraction wrong and you're frozen on today's model forever.

Your task: Design the router: what inputs steer the choice, how tiers map to models, and how fallback works — without leaking model names to callers.

Requirements:

  • Callers request a capability tier, not a model name
  • Router picks the cheapest model meeting the tier's quality bar
  • Availability-based fallback to an alternate provider on error/timeout
  • Policy routing: some data classes pinned to a region/provider
  • Explain how you migrate a model with zero caller changes

💡 Hint: Map tiers → models inside the gateway so callers depend on intent, never on a model string.

Show solution
route(tier, data_class):
  candidates = TIER_MAP[tier]                 # e.g. balanced -> [modelA, modelB]
  candidates = filter_by_policy(candidates, data_class)   # region/provider pins
  for m in order_by_cost(candidates):
     if available(m):  return call_with_fallback(m, rest=candidates)
  raise NoModelAvailable                       # circuit-breaker / degrade

Callers request a tier (cheap-fast / balanced / frontier), and the router maps it to concrete models by cost, availability, and policy, failing over to an alternate on error. Migration is a gateway-only change: to adopt a new model you edit TIER_MAP, and every caller gets it with no redeploy. Because callers never see model names, you're free to swap, add, or fall back at will. Verify current model availability/pricing in provider docs — they drift.

Exercise 4 · Design enforceable cost governanceExpert

Context: A cost dashboard nobody's budget depends on changes nothing. The platform's leverage is that it sits in the path and can act.

Your task: Design cost governance that is attributable AND enforceable: metering, budgets, quotas, caching, and chargeback — and what the gateway does at each budget threshold.

Requirements:

  • Meter and attribute every call's cost to a team + feature via the auth identity
  • Per-team monthly budget with graduated enforcement (warn / downgrade tier / block non-critical)
  • Per-team quotas/rate limits so one team can't starve others
  • Shared prompt caching at the gateway to cut cost across teams
  • Monthly chargeback/showback so each team owns its spend
  • Explain why enforcement in the path beats a dashboard

💡 Hint: For each budget threshold, name the concrete action the gateway takes automatically.

Show solution
📋 Cost-governance controls
ControlMechanismAction
MeteringAttribute tokens+cost to team/feature via auth identity.Feeds budgets + chargeback.
Budget @ 80%Threshold on the per-team monthly cap.Alert the team; no behavior change yet.
Budget @ 100%Cap reached.Auto-downgrade to a cheaper tier where quality allows.
Budget overBeyond cap.Block non-critical calls; critical calls flagged for approval.
QuotasPer-team RPS/concurrency.Isolate a runaway loop from everyone else.
CachingShared prompt caching at the gateway.Cut cost on repeated prefixes across all teams.

Why in-path beats a dashboard: the gateway can act — warn, downgrade, block, throttle — because it's in the request path, and chargeback makes each team own its line. That pairing bends the cost curve; a report alone doesn't. Verify cache pricing/TTL in provider docs.

Exercise 5 · Design self-serve onboarding + golden pathsProfessional

Context: Adoption is won or lost at onboarding. If it takes a ticket and two weeks, teams route around you; if it takes an afternoon, they take the paved road by choice.

Your task: Design the self-serve onboarding flow and two golden paths (RAG and agent) so a team ships in an afternoon with guardrails and observability for free.

Requirements:

  • Self-serve registration → scoped service identity + tier access, no ticket
  • Golden path (RAG): a template wiring retrieval + the gateway, grounding/citations built in
  • Golden path (agent): a paved tool-loop with guardrail defaults
  • Observability + guardrails inherited free on every call
  • Explain why golden paths (attraction) beat a mandate (handcuffs)
  • Allow off-path use for exotic needs, with more responsibility on the team

💡 Hint: Make the paved path the genuinely fastest and safest option for the common case.

Show solution
  1. Self-serve onboarding. A team registers its app in a portal, gets a scoped service identity and tier access immediately — no ticket, no wait on the platform team.
  2. Golden path — RAG. A template wires retrieval + the gateway with grounding, citations, and guardrails already in place; the team supplies its corpus and ships.
  3. Golden path — agent. A paved tool-loop with guardrail and retry defaults; the team adds its tools without re-deriving the loop or the safety rails.
  4. Free by default. Observability (dashboards, tracing) and the shared guardrail layer apply to every call automatically.
  5. Off-path allowed. A team with an exotic need can go off the golden path, accepting more responsibility — but most won't want to.

Attraction over handcuffs: golden paths win by being the fastest, safest way to ship the common case, so teams choose them. A mandate breeds workarounds; a genuinely-better paved road earns durable adoption.

Exercise 6 · Stand up and roll out the whole platformIndustry scenario

Context: The gateway prototype works; now you must roll it across a dozen teams, own it as an internal product, keep spend bounded, and not become the org's single point of failure. This is the tech-lead deliverable.

Your task: Lay out the end-to-end platform plan: gateway architecture, routing, cost governance, self-serve golden paths, team topology, and the attraction-first rollout — with the reliability posture for a service in every path.

Requirements:

  • Architecture: gateway owns auth, guardrails, routing, caching, logging, budgets (runtime boundary)
  • Routing: capability tiers → models, with cost/availability/policy and fallback
  • Cost: metering + enforceable budgets + quotas + shared caching + chargeback
  • Self-serve: onboarding in an afternoon; golden paths for RAG and agents; guardrails/observability free
  • Topology: platform team as product owner; enabling-team bootstrap then withdraw; optimize cognitive load
  • Rollout: lighthouse team → widen via self-serve → steady state, by attraction not mandate
  • Reliability: treat the gateway as critical infra — HA, per-provider circuit breakers, tested runbook

💡 Hint: Lead with the gateway as a product teams want to use; win adoption by being the fastest, safest path, and engineer the SPOF away.

Show solution
  1. Gateway architecture. One service every team calls, owning auth, guardrails, routing, caching, logging, and budgets at runtime — so a change applies everywhere with no team redeploy. Thin client SDK for ergonomics; enforcement stays server-side.
  2. Routing. Capability tiers → concrete models by cost/availability/policy, with fallback; callers never see model names, so you can migrate freely (verify model availability/pricing in provider docs).
  3. Cost governance. Meter and attribute every call; per-team enforceable budgets (warn → downgrade → block), quotas, shared prompt caching, and monthly chargeback so teams own their spend.
  4. Self-serve + golden paths. Register-and-ship in an afternoon; paved RAG and agent paths with guardrails and observability free by default; off-path allowed for the rare exotic need.
  5. Topology. The platform team runs it as an internal product for stream-aligned teams, embeds as an enabling team to bootstrap the first adopters, then withdraws — optimizing cognitive load throughout.
  6. Rollout by attraction. Land one lighthouse team, prove the golden path, widen via self-serve, reach steady state where new AI features start on the platform by choice.
  7. Reliability. Because the gateway is in every path, engineer it as critical infra: HA, per-provider circuit breakers and fallback, graceful degradation, and a tested runbook.

Order: build the gateway as something teams want to use, win the lighthouse, widen by attraction, and never let the SPOF you created take the org down. A platform is a product; treat its own teams as customers and the adoption follows.

✓ Checkpoint — you can move on when you can…

  • Argue when a shared AI platform pays for itself, and map each duplicated concern to a centralized capability.
  • Design an AI gateway as a runtime boundary owning auth, guardrails, routing, caching, logging, and budgets.
  • Route on capability tiers (not model names) by cost/availability/policy with fallback, and migrate models with no caller change.
  • Govern cost with metering, enforceable budgets, quotas, shared caching, and chargeback.
  • Ship self-serve onboarding and golden paths that win adoption by attraction, not mandate.
  • Choose a platform-team topology that optimizes cognitive load, and engineer the gateway's SPOF risk away.
© 2026 studybydoing.in · AI Engineering: Zero to Production · All rights reserved. · About · Privacy Policy · Terms · Contact
Educational content, provided as-is and without warranty. Code samples are examples — review, test, and adapt them before using in production. See the Terms of Use & Disclaimer. Use at your own risk.
© studybydoing.in