[{"content":"Engineering the AI Gateway Identity, Guardrails, and Production Hardening in USS When you add AI to a product, the real engineering work isn\u2019t model selection.\nIt\u2019s boundary enforcement.\nUSS uses a Cloudflare Worker as a hardened AI gateway. This post breaks down how it works \u2014 and why each layer exists.\n1. The Worker Is Not a Proxy A naive implementation would look like:\nFrontend \u2192 Worker \u2192 OpenAI That\u2019s not what this is.\nThe Worker is a:\nPolicy engine Identity extractor Intent filter Cost guard Failure isolator It exists to ensure:\nOnly structured OpenAPI drafting requests reach the model.\n2. Identity via Cloudflare Access (JWT Extraction) Because the endpoint is protected with Cloudflare Access:\nEvery request contains Cf-Access-Jwt-Assertion The Worker extracts it Decodes payload Logs user identity Core concept:\nconst jwt = request.headers.get("Cf-Access-Jwt-Assertion") || ""; const payload = decodeJwtPayload(jwt); const identity = { email: payload.email, sub: payload.sub }; This gives:\nTraceability Abuse accountability Enterprise posture Zero anonymous usage No custom session handling required.\nThat\u2019s the power of edge identity.\n3. CORS + Access + Edge Headers This combination is subtle.\nBecause:\nBrowser enforces CORS\nAccess injects headers\nWorker must allow them explicitly\nCritical headers:\nAccess-Control-Allow-Origin Access-Control-Allow-Headers: Content-Type, Cf-Access-Jwt-Assertion If Cf-Access-Jwt-Assertion is not allowed:\nRequests silently fail before hitting your logic.\nDebugging this required inspecting:\nPreflight OPTIONS Response headers Access rules Worker response behavior This is where many edge integrations break.\n4. Prompt Validation Layer Before classification, I validate structure.\nChecks include:\nNon-empty input Minimum length threshold Maximum token guard API-related keyword presence No markdown chat-style indicators No conversational cues Reject early.\nReject cheaply.\nNever send garbage upstream.\nThis protects:\nToken burn Abuse loops Prompt injection attempts 5. Intent Classification Guard This is the most important engineering layer.\nThe goal:\nPrevent USS from becoming a general chatbot.\nThe Worker evaluates:\nDoes the prompt request:\nOpenAPI drafting? \u2705 API endpoint structure? \u2705 Resource + method definition? \u2705 Or:\nEssay writing? \u274c General programming help? \u274c Conversational response? \u274c If classification fails:\nReturn 400 with structured error.\nThis ensures product alignment.\nWithout this layer:\nCost increases. Brand dilutes. Scope drifts.\n6. Rate Limiting Strategy Rate limiting is implemented via Cloudflare security rules.\nCharacteristics:\nScoped to \/api\/ai\/* Identity-aware (via Access) Burst threshold Cooldown duration Temporary block on exceed This protects against:\nScripted abuse Accidental infinite loops Bot attacks Token floods Layering matters:\nFrontend does not enforce rate. Worker does not enforce rate. Edge WAF enforces rate.\nDefense in depth.\n7. Prompt Engineering Decisions The system prompt is structured and strict.\nCore constraints:\nMust output valid OpenAPI 3.0.3 Must produce YAML only No explanation text No markdown fences Deterministic structure Include info, paths, components if applicable I avoid:\nCreative tone Narrative responses Free-form explanation The model is treated as a structured generator \u2014 not a chat assistant.\n8. Failure Modes Considered AI systems fail in predictable ways.\nI accounted for:\n1. Upstream Timeout Return 502 with structured error.\n2. Model Refusal Return explicit refusal message.\n3. Non-YAML Output Reject and return validation error.\n4. Access Token Missing Return 401.\n5. Rate Limit Triggered Return 429.\n6. Unexpected Exception Return generic 500 without leaking internals.\nNever pass raw OpenAI errors directly to client.\n9. Observability Strategy Even without a traditional backend:\nYou still need signals.\nCurrent observability includes:\nWorker console logs (identity + status) Access logs WAF trigger monitoring Cloudflare analytics OpenAI usage dashboard Future improvements:\nStructured JSON logging Centralized log drain Per-user usage metrics Token consumption tracking Observability is what separates hobby AI from production AI.\n10. Scaling Considerations Right now:\nStateless edge execution No database dependency No session state Low latency Future scale concerns:\nToken cost management Caching safe prompt patterns Per-identity quotas Tiered rate limits Enterprise access segmentation The architecture already supports these expansions.\nThat was intentional.\n11. What Makes This Production-Ready Production-ready does not mean \u201cperfect.\u201d\nIt means:\nIdentity-aware Intent-aligned Abuse-resistant Rate-limited Failure-contained Observed The gateway is the boundary.\nAnd boundaries define software quality.\n12. The Philosophy Behind the Gateway This design reflects a belief:\nAI belongs behind policy layers.\nNot directly in browsers. Not publicly exposed. Not unbounded.\nIt should sit behind:\nIdentity Validation Guardrails Observability That is how AI becomes infrastructure.\n","permalink":"https:\/\/mumbleb.com\/posts\/uss-ai-gateway\/","summary":"

Engineering the AI Gateway<\/h1>\n

Identity, Guardrails, and Production Hardening in USS<\/h2>\n

When you add AI to a product, the real engineering work isn\u2019t model selection.<\/p>\n

It\u2019s boundary enforcement.<\/p>\n

USS uses a Cloudflare Worker as a hardened AI gateway. This post breaks down how it works \u2014 and why each layer exists.<\/p>\n

\n

1. The Worker Is Not a Proxy<\/h2>\n

A naive implementation would look like:<\/p>\n

Frontend \u2192 Worker \u2192 OpenAI\n<\/code><\/pre>
That\u2019s not what this is.<\/p>","title":"Engineering the AI Gateway \u2014 Identity, Guardrails, and Production Hardening in USS"},{"content":"From Tool to Platform Why I Added AI to Universal Schema Studio Universal Schema Studio didn\u2019t start as an AI product.\nIt started as a practical frustration.\nXSD to OpenAPI conversions Schema inspection Clean documentation workflows Developer-focused structure It was a tool.\nFocused. Deterministic. Static.\nThen something changed.\n1. Why Add AI at All? There are two types of AI integration:\nFeature-driven AI (\u201cbecause it\u2019s trending\u201d)\nWorkflow-driven AI (\u201cbecause it reduces friction\u201d)\nI was only interested in the second.\nThe real friction I observed:\nDevelopers staring at a blank OpenAPI file Translating business requirements into structure Rewriting similar API skeletons repeatedly Getting schema formatting wrong on first draft What AI does well:\nConvert description \u2192 structured output Produce valid YAML skeletons Accelerate the \u201cfirst 60%\u201d So the goal was not:\n\u201cAdd AI to USS.\u201d\nThe goal was:\n\u201cReduce friction in API design.\u201d\nThat distinction matters.\n2. User Value (Not Just Capability) The feature does one thing:\nYou describe your API in plain English \u2192 receive valid OpenAPI 3.0.3 YAML.\nBut the value is deeper:\nBefore\nBlank editor Manual scaffolding Syntax mistakes Structure second-guessing After\nStructured starting point Valid document Clear endpoints Editable baseline It shifts USS from:\nSchema viewer \/ editor\nto\nAPI drafting assistant\nThat\u2019s a different product category.\n3. Risk Analysis Before Writing Code AI features introduce real risks:\nToken cost explosions Abuse Prompt misuse General chatbot drift Security exposure Brand dilution I had to answer one question:\nDoes adding AI increase the long-term quality of USS?\nOnly if:\nIt stays aligned to API design It remains structured It does not become a generic chat interface It preserves developer intent So the integration had to be constrained.\nNot open-ended.\n4. Guardrails Define the Product The most important design decision was not model selection.\nIt was guardrails.\nThe AI endpoint:\nOnly accepts OpenAPI drafting prompts Blocks general Q&A Enforces intent classification Requires identity via Cloudflare Access Enforces rate limiting Logs identity metadata This is deliberate.\nGuardrails do two things:\nProtect cost and abuse\nPreserve product identity\nWithout guardrails:\nUSS becomes:\n\u201cChatGPT with YAML formatting.\u201d\nWith guardrails:\nUSS remains:\nA structured API design tool.\n5. UX Decisions (What I Didn\u2019t Build) Equally important is what I chose not to do.\nI did not:\nAdd streaming chat bubbles Add conversational memory Add follow-up question chains Add prompt history Add multi-turn chat UX Why?\nBecause USS is not a chat product.\nIt is a document product.\nThe AI is a drafting engine \u2014 not a conversation engine.\nThis preserves clarity.\n6. Founder Mindset Shift This was the moment USS stopped being just a project.\nIt became infrastructure.\nWhen you:\nAdd identity enforcement Add rate limiting Add structured gateways Add intent filtering Add layered security You\u2019re not building a toy anymore.\nYou\u2019re building something that can survive production use.\nThe mindset changes from:\n\u201cDoes this work?\u201d\nto\n\u201cCan this be trusted?\u201d\n7. From Tool \u2192 Platform A tool solves a narrow problem.\nA platform creates a foundation others can build on.\nAI integration nudges USS toward:\nDraft generation Conversion workflows Structured exports Policy enforcement Developer productivity acceleration It starts forming layers:\nEditor layer AI layer Identity layer Security layer Export layer That is platform territory.\nNot in scale \u2014 but in structure.\n8. Enterprise Readiness Narrative Enterprise doesn\u2019t mean:\nBig servers Complex dashboards Expensive plans It means:\nIdentity-aware Rate-limited Logged Controlled Intent-aligned Even as a self-hosted project, USS now reflects:\nZero-trust thinking Layered security Clear boundaries Deterministic output expectations That is enterprise posture.\n9. What This Signals for USS Adding AI is not the end.\nIt signals future direction:\nStructured document intelligence Schema-assisted validation Context-aware linting AI-assisted refactoring AI-driven documentation summaries But always within boundaries.\nThe discipline is the differentiator.\n10. The Real Question The question is not:\n\u201cDoes USS have AI?\u201d\nThe question is:\n\u201cDoes USS use AI responsibly?\u201d\nThat\u2019s the long-term positioning.\nUSS is not chasing AI.\nIt is integrating AI as infrastructure.\nThat\u2019s a different story.\n","permalink":"https:\/\/mumbleb.com\/posts\/uss-from-tool-to-platform\/","summary":"
From Tool to Platform<\/h1>\n
Why I Added AI to Universal Schema Studio<\/h2>\n
Universal Schema Studio didn\u2019t start as an AI product.<\/p>\n
It started as a practical frustration.<\/p>\n