01 / REFERENCE ARCHITECTURE
DesignedExecutive summary
Give enterprise AI consumers a common access contract, with identity, model permissions, safety and cost policy evaluated before inference.
The proposed platform places Azure API Management between callers and approved Microsoft Foundry / Azure OpenAI deployments. A logical consumer links users, applications and agents to policy ownership and usage attribution. Azure AI Search supports permission-aware enterprise RAG.
Here, “secure” describes intended controls—validated identity, explicit authorization and protected data handling—not an assurance of production security. No production adoption, measured performance or financial savings are claimed.
02 / REFERENCE ARCHITECTURE
DesignedBusiness problem
Direct model access across enterprise applications, copilots and agents distributes policy enforcement across teams. The resulting problems include:
- Inconsistent authentication and authorization, with no unified logical-consumer identity.
- Uncontrolled model access and weak requests-per-minute (RPM), tokens-per-minute (TPM) and monthly quota governance.
- Limited cost attribution and weak budget, chargeback and showback controls.
- Inconsistent content safety and PII protection, alongside fragmented telemetry.
- Difficult model routing, deployment migration and controlled failover.
03 / REFERENCE ARCHITECTURE
DesignedRole and responsibilities
This independent portfolio design presents the architecture responsibilities: define trust boundaries and request contracts; specify consumer resolution and policies; document ADRs and failure behavior; and establish evidence requirements for production readiness.
Samson’s current professional designation is Technical Architect. Senior Azure AI Solution Architect is the specialization and target role, not a claimed employment title for this reference project. No client engagement or implementation delivery is asserted here.
04 / REFERENCE ARCHITECTURE
DesignedRequirements and constraints
- Authorize each caller and resolve it to an enabled consumer before provider access.
- Apply per-consumer model, RPM, TPM, monthly token and budget policies.
- Preserve product attribution across workload and delegated identities.
- Keep prompts, retrieved documents and sensitive identifiers out of routine logs.
- Support streaming, partial failures and accounting reconciliation without unlimited retries.
- Respect deployment-region and data-residency constraints; validate service tier and region support before deployment.
Latency objectives, cache lifetimes, availability objectives and recovery targets remain to be agreed with workload owners. No numerical production SLO has been validated.
05 / REFERENCE ARCHITECTURE
DesignedHigh-level architecture
- Applications, agents & human usersWorkload and delegated access
- Microsoft Entra IDToken issuance · trusted identity
- Azure API ManagementEnterprise AI gateway
- Logical-consumer resolutionValidated claims → consumerId
- Governance policiesModel · quota · budget · safety · routing
- Microsoft Foundry / Azure OpenAIAzure AI Search · permission-aware RAG
Supporting services
Logical flow; retrieval is orchestrated by the application or agent. Supporting services integrate with the gateway and workloads; they are not sequential request hops.
Trust boundaries separate external callers, the gateway and policy services, and model/retrieval backends. The gateway validates access; workloads remain responsible for tool authorization and document-level retrieval permissions.
06 / REFERENCE ARCHITECTURE
DesignedRequest lifecycle
- Obtain an Entra access token for the gateway audience using the appropriate workload or delegated flow.
- Validate token signature, issuer, audience, expiry and tenant; establish a correlation ID.
- Resolve verified claims to a logical consumer using cached or authoritative configuration.
- Authorize the caller, consumer and model; check rate limits, token reservation, quota and budget.
- Apply required PII and content-safety inspection; constrain retrieval and tools to the caller’s permissions.
- Route through managed identity to an approved deployment; enforce timeouts and bounded retries.
- Inspect the response where required. Reconcile provider usage, release unused reservations and emit redacted telemetry.
Streaming requires separate design validation: inspect before release where required, account for cancellation, and do not claim whole-response safety if tokens have already reached the caller.
07 / REFERENCE ARCHITECTURE
DesignedIdentity and logical-consumer resolution
Application, bot or agent
Use validated appid or azp with the trusted tenant and application roles. Resolve a registered workload mapping to consumerId.
Human user
Use validated oid, tenant, delegated scopes and approved groups and/or application roles. Resolve the authorized product context to consumerId.
Do not infer a workload solely from the presence of azp: delegated tokens can also identify the client application. Distinguish token context, validate the permission model, handle group-overage claims through an authorized lookup, and deny ambiguous mappings. Never trust a caller-supplied consumer header as authorization.
Both paths converge on an enabled consumer. Unknown identities, unresolved membership, missing claims and unauthorized mappings deny access by default.
08 / REFERENCE ARCHITECTURE
DesignedGovernance-policy design
A versioned consumer record defines model allowlists, authorization and cost policy. Evaluate cheap access checks before expensive inspection or inference. Use an atomic reservation ledger for concurrent usage admission; Redis configuration caching alone does not provide reliable monthly accounting.
Synthetic consumer configuration
Synthetic demonstration data. Every value below is illustrative, including the limits and dollar budget. These are not real client settings, observed lab results or approved production targets.
{
"consumerId": "finance-copilot",
"enabled": true,
"allowedModels": [
"sample-chat-model",
"sample-embedding-model"
],
"rpmLimit": 120,
"tpmLimit": 250000,
"monthlyTokenQuota": 25000000,
"monthlyBudgetUsd": 1000,
"allowedGroups": [
"finance-ai-users"
],
"contentSafetyLevel": "medium",
"piiProtection": true
}Group names are readable placeholders; deployed policy should resolve immutable identifiers. Define month boundaries, currency, policy versioning, invalidation and revocation behavior before implementation.
09 / REFERENCE ARCHITECTURE
DesignedSecurity and Responsible AI
- Identity: Entra ID with OAuth 2.0 access tokens; OpenID Connect for interactive sign-in where needed. Validate JWTs at the gateway and apply least-privilege RBAC.
- Backend access: managed identities; Key Vault for remaining secrets and certificates; consumer and model allowlists.
- Data protection: PII redaction or anonymization before inference and in logs, with workload-specific rules and retention controls.
- Responsible AI: Azure AI Content Safety, prompt-injection inspection, untrusted-document boundaries and output validation. Safety classifiers do not replace authorization.
- Agent controls: scoped tools, outbound destination allowlists and human approval for high-risk actions to reduce data exfiltration and unintended changes.
- Auditability: record policy version, outcome and correlation identifiers without storing raw prompts by default.
- Production targets: private endpoints, VNet integration, verified regional data flows, residency review and least-privilege operational access.
Residual risks include missed PII, jailbreaks, poisoned retrieval content, excessive permissions, stale authorization and sensitive generated output. Threat modeling and adversarial evaluation are required; this design makes no compliance certification claim.
10 / REFERENCE ARCHITECTURE
DesignedObservability and LLMOps
Correlate gateway requests, retrieval, safety checks and provider calls without exposing prompt content. Track request success/failure; P50/P95 latency; input/output tokens; estimated cost; throttling and quota rejections; budget consumption; content-safety blocks; model distribution; and configuration-cache hit ratio.
For RAG, use a curated, permission-aware evaluation dataset to assess groundedness and relevance. Version prompts, retrieval settings, models and evaluation datasets; compare releases against accepted baselines before promotion. Track cached-token usage separately where providers expose it.
PORTFOLIO EVIDENCE PLANNED
Operational dashboard & evaluation report
Reserved for actual redacted telemetry screenshots and reproducible evaluation results. No fabricated charts or measurements.
11 / REFERENCE ARCHITECTURE
DesignedFinOps and cost attribution
Capture provider-reported input, output and cached-token usage where available. Join it to consumer, product, deployment, model version and effective pricing configuration. Avoid counting cached input twice: calculate uncached input separately from cached input and output.
Reserve estimated cost and token use before admission; reconcile with completed usage and retain an explicit “estimated” state when usage is missing. Apply budget thresholds and monthly quotas, alert owners, and support consumer/product showback and reviewed chargeback reports.
Cost per successful request includes attributed costs of unsuccessful attempts and retries divided by successful requests; show “not available” when no request succeeds. Report estimated inference cost separately from invoiced Azure cost, which also includes infrastructure, discounts and billing adjustments.
Near-real-time enforcement can overshoot under concurrency. Hard ceilings need transactional reservations and conservative admission. Review cheaper models, retrieval size and caching against quality and latency evaluations; no savings or production volumes are claimed.
12 / REFERENCE ARCHITECTURE
DesignedReliability and failure handling
All behavior below is designed, not validated through fault injection. Production acceptance requires explicit tests for each failure path.
| Failure | Intended behavior |
|---|---|
| Invalid or missing token claims | Reject authentication; no model call. Return an opaque error and correlation ID. |
| Redis cache miss or unavailability | Read authoritative Cosmos DB configuration with bounded timeouts; apply load protection. Never bypass authorization. |
| Cosmos DB unavailability | Use only an unexpired validated cache entry within the approved staleness window; otherwise deny service. Sensitive revocations need stricter consistency. |
| Azure OpenAI 429 | Honor Retry-After within the deadline; use jitter and a bounded retry budget. Return throttling when exhausted. |
| Unauthorized model request | Reject before provider invocation; log a redacted policy reason. |
| Monthly quota or budget exhaustion | Reject new admissions; reconcile reservations for in-flight requests. Concurrent overshoot remains a design risk. |
| Safety-service failure | Fail closed for workloads requiring inspection; return service unavailable rather than send uninspected content. |
| Primary deployment failure | Circuit-break and route only to an approved, compatible deployment within the allowed residency boundary. |
| Logging or telemetry failure | Buffer redacted operational events with limits and alert on loss. Fail closed if mandatory audit or budget accounting cannot be durably recorded. |
13 / REFERENCE ARCHITECTURE
DesignedArchitecture decisions and trade-offs
These ADR summaries are design choices for the reference architecture. Revisit them when workload constraints change.
| Decision | Reason | Rejected alternative | Benefit | Cost / trade-off | Revisit when |
|---|---|---|---|---|---|
| APIM enterprise gateway | Central policy enforcement and API lifecycle management | Direct model access or a custom proxy | Consistent access contracts | Gateway cost, policy complexity and latency | A required protocol or policy cannot be supported within the chosen APIM tier |
| Logical consumer abstraction | Separate billing and policy ownership from callers | One quota per identity | Shared product attribution across users and agents | Mapping lifecycle and ownership must be maintained | Every caller is a permanently isolated billing unit |
| Cosmos DB + Redis cache-aside | Durable configuration with low-latency reads | Database access on every request | Less repeated configuration lookup | Stale policy and cache invalidation risk | Traffic is low or policy changes require synchronous consistency |
| Entra applications + roles/groups | Distinguish workload and delegated permissions | Shared API keys | Revocable access with explicit authorization | Group overage and tenant administration complexity | A non-Entra consumer needs a reviewed federation path |
| Gateway telemetry + provider token usage | Join request context with actual returned usage | Prompt-size estimates alone | Better usage attribution | Streaming, missing usage and reconciliation complexity | Provider usage is unavailable; label fallback estimates explicitly |
| Near-real-time budgets | Balance response latency with aggregate spend controls | Synchronous global accounting for every token | Practical threshold enforcement | Concurrent requests can overshoot; reserve and reconcile | Strict spend ceilings require a transactional reservation ledger |
| Azure AI Search for RAG | Use hybrid retrieval with document-level authorization | A standalone vector database | Integrated search and indexing | Index cost, freshness and permission synchronization | Data locality or retrieval needs exceed service capabilities |
| Managed identity + Key Vault | Avoid embedded credentials and centralize remaining secrets | Static keys in application settings | RBAC and controlled credential rotation | Identity dependencies and rotation procedures | Backend lacks identity support; use a rotated vault-held credential |
| Bounded retry + approved fallback | Handle transient failures within request deadlines | Unbounded retries or arbitrary region failover | Limit amplification and preserve routing policy | Possible duplicate billing; compatibility checks required | Side effects or residency restrictions prohibit replay or fallback |
14 / EVIDENCE REVIEW
DesignedImplementation evidence
Available now: this architecture narrative, responsive logical diagram, synthetic configuration and decision records. These are design artifacts, not gateway implementation evidence.
PORTFOLIO EVIDENCE PLANNED
Reproducible implementation artifacts
APIM policy exports, infrastructure as code, consumer resolver, redacted request traces, usage reconciliation and a tagged repository release are still needed.
Evidence status convention
- Implemented and tested: use only with reproducible tests and linked results. No gateway capability currently carries this status.
- Implemented, evidence pending: use when code exists but supporting evidence is incomplete. The existing meeting summarizer is listed this way; no gateway code was supplied.
- Designed: the gateway, identity, RAG, governance, safety, LLMOps, FinOps and failure contracts in this case study.
- Planned for production hardening: deployment and operational assurance work listed below.
15 / EVIDENCE REVIEW
DesignedTest results
No gateway lab results were supplied or found in this portfolio repository. Website build checks do not validate an Azure platform.
| Test area | Required evidence | Result |
|---|---|---|
| Identity and authorization | Valid workload/user mapping; missing claims; cross-tenant denial; group overage | Not run |
| Policy and accounting | Disallowed models; concurrent quota admission; month rollover; budget reconciliation | Not run |
| Safety and RAG | PII fixtures; injection attempts; document ACL enforcement; groundedness evaluation | Not run |
| Reliability | Dependency fault injection; 429 handling; stream cancellation; bounded approved failover | Not run |
16 / REFERENCE ARCHITECTURE
DesignedLimitations
- No gateway implementation, Azure deployment, load test or production adoption is evidenced here.
- The diagram omits physical network topology and service-tier-specific configuration.
- Distributed counters, streaming safety and budget reservations need implementation validation.
- Retrieval permission freshness and group membership changes can create authorization gaps.
- Content filters and injection defenses are probabilistic; human review and scoped tools remain necessary.
- Public credential verification and a downloadable resume have not been supplied.
17 / REFERENCE ARCHITECTURE
Planned for production hardeningProduction-hardening roadmap
- Build the lab: publish sanitized infrastructure, policy code and synthetic fixtures; automate positive and negative tests.
- Validate identity and data boundaries: threat model, private endpoints, VNet integration, RBAC, residency and retention review.
- Prove accounting: transactional reservations, concurrency tests, effective-dated pricing and Azure invoice reconciliation.
- Operationalize: agreed SLOs, load/fault tests, disaster recovery, audit retention and incident runbooks.
- Gate releases: reproducible RAG and safety evaluations, adversarial tests and human approval for high-risk changes.
18 / REFERENCE ARCHITECTURE
DesignedRepository, documents and demos
A public gateway repository, downloadable architecture document and gateway demo are not available yet. This page is the current design document.
- Microsoft Learn: AI gateway capabilities in Azure API Management — platform reference; custom consumer and accounting logic still require implementation.
- Selected work and existing application demos
- Discuss the architecture with Samson on LinkedIn
Let’s talk through the possibilities.
Have a similar architecture challenge or a different perspective? I’d love to hear it.
Connect with Samson on LinkedIn ↗