Skip to content
Houdini Docs

Houdini's Architecture

Out of Date

This page has not been updated to reflect the current version of Houdini. The information here may be incomplete or incorrect. Check back soon.

Houdini is built around a compiler-first model. You write GraphQL documents in your app, Houdini reads them at build time, validates them against your schema, and generates the runtime code and TypeScript types your framework integration needs.

The goal is to move as much work as possible out of the browser and into code generation.

The three main pieces

Houdini has three major parts:

  • Houdini Client: the runtime client used by your application. It manages network requests, normalized caching, optimistic updates, pagination, subscriptions, and document behavior.
  • Code generation: the compiler pipeline that reads GraphQL documents, validates them, and writes generated files into $houdini.
  • Framework plugins: integrations such as Svelte/SvelteKit that turn generated artifacts into framework-native APIs.

The core compiler understands GraphQL and Houdini’s runtime model. The framework plugin decides how that model should feel inside your app.

Compile-time work

When you write a GraphQL document, Houdini can know a lot before your app ever runs:

  • the operation name
  • the result shape
  • required variables
  • fragment dependencies
  • cache selection data
  • generated TypeScript types
  • framework-specific wrappers

That lets Houdini generate strongly typed code instead of shipping a large GraphQL interpretation layer to the browser.

Example

In a Svelte component you might write:

<script lang="ts">
  import { graphql } from '$houdini'


  const UserList = graphql(`
    query UserList @load {
      users {
        name
      }
    }
  `)
</script>


{$UserList.data?.users?.map((user) => user.name).join(', ')}

This looks small, but Houdini uses it to do several things:

  • parse and validate the UserList query
  • generate the UserList result and variable types
  • generate a store for loading the query
  • create cache metadata for the selected fields
  • transform framework code where needed

A simplified generated version looks like this:

<script lang="ts">
  import { UserListStore } from '$houdini'


  const UserList = new UserListStore()


  onMount(() => {
    UserList.fetch()
  })
</script>


{$UserList.data?.users?.map((user) => user.name).join(', ')}

The real generated output is more involved, but the important idea is that Houdini turns GraphQL documents into typed framework APIs.

What the Svelte/SvelteKit plugin does

The Svelte/SvelteKit integration is responsible for making Houdini feel native in Svelte apps. It can:

  • generate Svelte stores
  • wire route queries into SvelteKit load behavior
  • provide $houdini types for route data
  • transform inline graphql calls
  • support Svelte 5 runes-specific patterns

The Houdini core still handles the GraphQL document model, cache, network behavior, and generated metadata. The plugin wraps that core in Svelte conventions.

Why this architecture matters

This split gives Houdini a few important properties:

  • small runtime: expensive GraphQL analysis happens during generation
  • typed APIs: generated types match your schema and documents
  • framework-native APIs: each integration can expose the right mental model
  • plugin extensibility: codegen and runtime behavior can be extended