# Architecture ## Overview Hypertune is architected to provide strong reliability and performance guarantees when you access your feature flags via one of our SDKs. SDKs make a single network request on initialization to fetch your flag [logic](https://docs.hypertune.com/concepts/logic) from [Hypertune Edge](https://docs.hypertune.com/concepts/hypertune-edge) and then evaluate your flags locally, synchronously, in memory with no network latency. They listen for updates to your flag logic in the background and automatically fetch any changes which will be reflected in the next flag evaluation. Flag evaluations, experiment exposures, and analytics events are collected by SDKs and then flushed to Hypertune Edge in the background. Since there's no dependency on the server for each flag evaluation, this greatly improves both reliability and performance. All SDK initialization requests are made to our CDN edge servers hosted by Cloudflare so there is no direct dependency on our application servers.
## Auto-generated, type-safe client SDKs ship with a CLI tool to auto-generate a client so you can access your flags with end-to-end type safety. This ensures typos in flag names or incorrectly passed targeting attributes can be caught at build-time rather than runtime. It also improves the developer experience with code completion, comments, "find all references" and type-safe flag clean up. ## Initialization You can choose to provide an initialization query to: * Select which flags to fetch * Provide some targeting attributes upfront so that any flag logic that depends on those attributes can be [partially reduced](https://docs.hypertune.com/reduction#partial-reduction) on the edge This is useful for: * Performance * Limit which flags are fetched to reduce the network payload size * Partially reduce flag logic on the edge to: * Reduce the network payload size * Reduce the logic that needs to be locally evaluated by the SDK * Security * Eliminate sensitive logic, e.g. a list of user IDs, on the edge so it doesn't get leaked to publicly accessible clients, e.g. in the browser ## Build-time snapshot To improve reliability, you can include a fallback snapshot of your flag logic in the [generated client](https://docs.hypertune.com/sdk-reference/type-safe-client-generation) at build time. The SDK will instantly initialize from the snapshot first before fetching the latest flag logic from [Hypertune Edge](https://docs.hypertune.com/concepts/hypertune-edge). To keep the snapshot fresh, set up a [webhook](https://docs.hypertune.com/integrations/webhooks) to regenerate the client on every Hypertune commit. In this case, you don't need to initialize from Hypertune Edge at all, eliminating network latency and bandwidth, improving both performance and efficiency. The snapshot is particularly useful for SPAs (single-page applications) as you can use your flags in the first app render without any layout shift, flickering, or page load delay. It also enables using Hypertune in local-only, offline mode, e.g. for running unit tests, or in isolated, secure, air-gapped environments. ## Hard-coded fallbacks Whenever you evaluate a flag, you pass a hard-coded fallback value, e.g. ```typescript const exampleFlag = hypertune.exampleFlag({ fallback: false }); ``` If [Hypertune Edge](https://docs.hypertune.com/concepts/hypertune-edge) is unreachable and there's no build-time fallback snapshot of your flag logic, or there's an error evaluating the flag, you'll get this hard-coded fallback value instead. This ensures that in the worst-case scenario, your app still works properly. ## Hydrate from your own server You can hydrate or "bootstrap" the SDK in the browser with the state of the SDK on your server so you can use your flags in the first app render without any page load delay, UI flicker, or layout shift. This works well with server-side rendering frameworks like Next.js, Nuxt, Remix and Gatsby. ## Local-only, offline mode You can disable server initialization and use a build-time fallback snapshot of your flag logic to use SDKs in local-only, offline mode. This is useful for running unit tests or using Hypertune in isolated, secure, air-gapped environments. ## Provide targeting attributes You can define targeting attributes at the: * `root` level * individual flag level And provide them during: * SDK initialization * local flag evaluation * a mix of both Typically, you'll provide targeting attributes when locally evaluating the `root` flag, passing it the `context` argument you defined in your [schema](https://docs.hypertune.com/concepts/schema). You'll get back the `Root` SDK node which will have type-safe methods to evaluate all your individual flags. You can also provide [flag-specific targeting attributes](https://docs.hypertune.com/schema#flag-specific-targeting-attributes) when evaluating individual flags. ## Local, synchronous, in-memory flag evaluation SDKs evaluate flags locally, synchronously, in memory with no network latency. This includes flag logic that contains experiments. So you can use an SDK on the backend to evaluate flags, including experiments, for different users without adding latency to every request. And you can use an SDK on the frontend to evaluate flags, including experiments, without blocking renders. ## Sending logs SDKs send logs to [Hypertune Edge](https://docs.hypertune.com/concepts/hypertune-edge) in the background. This enables you to: * See how often different parts of your flag logic are evaluated, e.g. to see how often different targeting rules are evaluated and passed in realtime * Log [experiment](https://docs.hypertune.com/concepts/experiments) exposures * Log [analytics events](https://docs.hypertune.com/concepts/event-types) * See any SDK errors from the Hypertune UI You can also manually trigger and wait for logs to be flushed. ## Getting flag updates SDKs listen for updates to your flag logic in the background. When you save and activate a new commit from the Hypertune UI, the SDK will fetch your new flag logic and use it on the next evaluation. You can also manually trigger and wait for a re-initialization from the server. And you can add and remove listeners to be notified of updates, e.g. to trigger a re-render on the frontend after an update. ## Serverless environments Hypertune SDKs have been uniquely architected to work optimally in serverless and edge environments like: * Vercel deployments * Cloudflare Workers * AWS Lambdas * Google Cloud Functions * Netlify Functions * DigitalOcean Functions ## Vercel Edge Config If you deploy on Vercel, you can initialize the SDK with near-zero latency in Vercel's edge environment when you set up our [Vercel Edge Config integration](https://docs.hypertune.com/integrations/vercel-edge-config-integration). ## Custom logging By default, SDKs output info and error logs to the console. But you can provide a custom logging callback to capture and forward logs elsewhere, e.g. to your monitoring infrastructure. ## Shutting down You can shut down an SDK to cleanly stop all its background processes and terminate all its connections. ## Git-based version control All of your flags are versioned together in the single [Git-based version history](https://docs.hypertune.com/git-based-version-control#version-history) of your project. New changes create [commits](https://docs.hypertune.com/git-based-version-control#commits). You can review [diffs](https://docs.hypertune.com/git-based-version-control#diffs) of your changes before saving them, as well as diffs of historical commits. You can create [branches](https://docs.hypertune.com/git-based-version-control#branches) and configure the SDK and code generation to use a specific branch. You can merge branches with [pull requests](https://docs.hypertune.com/git-based-version-control#pull-requests). And you can [safely onboard nontechnical team members](https://docs.hypertune.com/git-based-version-control#safely-onboarding-nontechnical-team-members) by assigning them the [Contributor role](https://docs.hypertune.com/git-based-version-control#team-roles) so that any changes they make create a pull request that needs to be reviewed. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.hypertune.com/concepts/architecture.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.