Control plane vs runtime proxy: why Ahena stays out of your request path

Two places a platform can sit

A tool that helps you manage third-party services (a database, email, payments, storage, an AI model) can sit in one of two places relative to your application.

A runtime proxy, or API gateway, sits in the request path. Your app sends its own traffic (completions, emails, charges, uploads) to the proxy, and the proxy forwards it to the provider. The appeal is real: one key, central logging, and the promise that you can change providers by flipping a setting instead of changing code. The cost is that every request now depends on one more service. Its latency is added to yours, and its outages become yours.

A control plane sits beside the app. It talks to providers' management APIs to create, configure and check the resources your app needs, and the app talks to the providers directly. The control plane shapes the environment your app runs in; it doesn't carry the app's traffic.

Ahena is a control plane. That was a deliberate decision, recorded as the project's first architecture decision record, and the rest of this guide explains what it means in practice.

What Ahena calls, and what it never touches

Ahena holds credentials for the provider accounts you connect, per environment, and uses them for management calls: create a webhook endpoint, set CORS on an R2 bucket, add the DNS records an email domain needs, ask Resend to re-check a domain, register an iOS app with Firebase, or read the current configuration so it can plan, verify and detect drift.

Your application's own traffic is a different category: sign-ins, database queries, sent emails, payments, uploads and AI requests. That traffic goes straight from your app to the provider. No Ahena API route forwards application traffic, and Ahena's API serves only Ahena's own control surface: the dashboard, the CLI, the MCP server and CI checks.

Credentials are fenced in the same way. Every provider integration declares the hosts it may call, and Ahena's core refuses any other destination, so a Stripe credential can only ever reach Stripe's API. Your app doesn't get its keys from Ahena at runtime either: the generated code reads them from your own environment variables. The security overview covers how stored credentials are encrypted and fenced.

What happens when Ahena is unavailable

If Ahena is unreachable, whether because of an outage, a network problem or because you stopped using it, a correctly configured app keeps working. Nothing in its request path has changed: it still calls Supabase, Stripe, Resend, Cloudflare, Firebase and its AI provider directly, with credentials from its own environment.

What does depend on Ahena being reachable is management:

• planning and applying changes (ahena plan, ahena apply, ahena configure);
• Doctor runs and drift checks, including Continuous Doctor's scheduled runs;
• approvals in the dashboard;
• the CI deploy check, ahena deploy-check.

The deploy check is the one place where unavailability is visible in your pipeline, and it fails closed: if it can't reach Ahena, it doesn't report the environment as ready. That's the right default for a gate. A check that passed whenever it couldn't run would be worse than no check.

This isn't only a design intent. Ahena's own validation flow stops the Ahena API and then runs a generated application against its providers, and the generated Supabase, Resend and Ollama code is run in Ahena's tests with Ahena stopped.

Generated code has no Ahena dependency

ahena generate writes readable TypeScript into your repository, under src/ahena/, for every provider connected to an environment. It's built on each provider's official SDK. The generated output imports nothing from Ahena and references nothing at Ahena, and you can keep or edit it without Ahena.

import { ahena } from "./ahena/client";

await ahena.email.send({ to: user.email, subject: "Welcome", text: "Hi!" }); // straight to Resend
await ahena.storage.upload("avatars/1.png", bytes, "image/png");             // straight to Cloudflare R2
const s3 = ahena.storage.raw; // escape hatch: the provider's own client

ahena.email.send() calls Resend with the Resend SDK. Nothing goes through Ahena's servers. Keys come from your environment, and the generated assertEnv() fails fast with the names of any that are missing. Regenerating is safe: files you edited since the last generate are kept unless you pass --force.

One honest note on depth: every generator's output is typechecked against the real provider SDKs in Ahena's CI, and the generated layers are run in Ahena's tests against fakes at the network boundary. That shows the code compiles and behaves as intended against those fakes; it isn't a claim that any provider integration is production-ready. The providers overview says how far each one is verified against the real service.

The trade-offs Ahena accepts

Staying out of the request path has costs, and they're worth stating plainly.

• Ahena can't see runtime traffic. It doesn't have request logs, error rates or latency for your app. Its view of health comes from provider state: Doctor's checks and drift against ahena.lock. Uptime monitoring is out of scope. Continuous Doctor checks configuration health (credentials, settings, drift, coverage), not whether your app is up.
• Switching providers needs code changes. There's no proxy setting to flip. Generated adapters keep the change small, and ahena switch does the mechanical parts, but it's still a change to your code and configuration. The switching guide covers why that's the honest version anyway.
• Management depends on Ahena. Plans, applies, Doctor and the CI check need Ahena to be reachable, as listed above.

In return: no added latency, no shared outage, and no runtime lock-in. Any exception to this boundary would need its own decision record naming the capability and why direct calls can't work.

What Ahena isn't

• Not a proxy or API gateway. Application traffic never passes through Ahena.
• Not a secret manager. Ahena stores provider credentials so it can manage providers, plus a few application secrets it creates (such as webhook signing secrets) or that you keep with an environment. That storage serves management; it isn't the product.
• Not a host, a runtime or a reseller. You keep your own provider accounts and pay providers directly.

What it is: the place where your app's external stack is declared (ahena.config.ts), recorded (ahena.lock), planned, approved, applied, verified and watched. If you're evaluating it, the useful question isn't "what if Ahena goes down?" (your app keeps running) but "which management tasks would I be doing by hand meanwhile?"