Foundry logo Foundry Architecture
Reference

Architecture

Foundry keeps the runtime split into a few clear stages: load content, assign routes, build dependencies, render outputs, and serve or publish the result.

Main flow

config
  -> content/data load
  -> site graph
  -> route assignment
  -> dependency graph
  -> renderer
  -> preview server or static output

Key packages

  • internal/config: config loading, editing, and validation.
  • internal/content: document loading, frontmatter parsing, markdown rendering, and site graph construction.
  • internal/router: URL assignment for documents and archives.
  • internal/deps: dependency graph construction and rebuild planning.
  • internal/renderer: template rendering, output writing, asset coordination, and taxonomy archive rendering.
  • internal/server: preview HTTP server, file watching, and incremental rebuild orchestration.
  • internal/plugins: plugin metadata, registration, lifecycle hooks, generated plugin sync, and the RPC host for out-of-process plugins.
  • internal/theme: theme management, validation, and scaffolding.

Two graphs

Foundry uses two different graph models for different jobs:

  • SiteGraph: the in-memory model of documents, routes, taxonomies, data, and config.
  • DependencyGraph: the rebuild graph used to determine which outputs need to be regenerated after a change.

Preview runtime

  1. Load the site graph.
  2. Assign URLs.
  3. Run route hooks.
  4. Sync assets.
  5. Build dependency state.
  6. Watch content, theme, data, and plugin roots for changes.
  7. Choose between a full rebuild and a targeted rebuild based on the dependency graph.

Plugin runtime model

Foundry has two plugin runtime paths. First-class Go plugins run in process and are compiled into the binary for deep integration with the CMS lifecycle. RPC plugins run out of process through a declared runtime.mode: rpc command, which lets Foundry expand extension points without loading third-party code into the main process.

Why the package boundaries matter

The project is intentionally not organized as a single giant runtime package. That makes it easier to test subsystems independently and to evolve the rebuild and rendering logic without entangling CLI, admin, plugin, and serving concerns.

Useful entry points

  • cmd/foundry: application entrypoint.
  • internal/commands: command implementations.
  • internal/server/server.go: preview serving and rebuild orchestration.
  • internal/renderer/renderer.go: rendering and output writing.