Architecture

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, and generated plugin sync.
• 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.

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.