# sphireinc/foundry architecture

> Architecture diagram of the GitHub repository sphireinc/foundry, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sphireinc/foundry
- Repository: https://github.com/sphireinc/foundry

## Overview

1. **Overall shape**
Foundry is a Go-based CMS with two major faces: a command-line application and a long-running server/runtime. It works from a file-based project layout, with source content under `content/`, mutable operational state under `data/`, themes under `themes/`, plugins under `plugins/`, and generated output under `public/`.

2. **Core build pipeline**
The central architecture is a staged content pipeline: config loading feeds content and data loading, which builds an in-memory site graph, assigns routes, resolves dependencies, renders templates, and writes either static output or preview output. This pipeline is reused by both `foundry build` and the preview server.

3. **Content and site model**
`internal/content`, `internal/site`, `internal/router`, and `internal/taxonomy` form the content model layer. Markdown files with frontmatter become typed documents, language variants are grouped, taxonomies are indexed, and URLs are assigned. The resulting `SiteGraph` is the canonical in-memory representation of pages, posts, routes, config, and loaded data.

4. **Incremental rebuild boundary**
Foundry maintains a separate `DependencyGraph` in `internal/deps` to decide what must be regenerated after a change. This graph tracks dependencies from documents, templates, data keys, and taxonomy archives to rendered outputs, allowing the preview server to rebuild only affected pages instead of running a full site rebuild.

5. **Renderer and output generation**
`internal/renderer` is the rendering boundary between site state and emitted files. It combines the resolved site graph with theme templates, plugin hooks, markup rendering, and asset outputs. Static builds write into `public/`, while preview mode also emits live artifacts such as search and SDK data.

6. **Themes as a presentation boundary**
Themes are a first-class subsystem under `themes/`. Frontend themes provide layouts, partials, CSS, and JS for public pages, while admin themes provide the shell UI for the management surface. Theme manifests define compatibility, supported layouts, slot contracts, security declarations, and field contracts, making themes a validated extension surface rather than just templates.

7. **Admin subsystem**
`internal/admin` is a full subsystem with auth, session management, audit logging, HTTP handlers, service orchestration, user storage, and UI manifest support. The admin server exposes document, media, config, plugin, theme, status, and debug flows, and uses a session-based auth model backed by filesystem state. The admin UI is themeable and loads its own SDK/runtime contract.

8. **Plugin subsystem**
`internal/plugins` handles discovery, metadata, validation, lifecycle, installation, security assessment, and runtime integration for plugins in `plugins/`. Plugins can contribute hooks, assets, config schemas, admin pages/widgets, and renderer behavior. There is a strong boundary between declared permissions and actual execution, and some hooks can run in an out-of-process RPC host for reduced trust exposure.

9. **Assets and media flow**
`internal/assets`, `internal/media`, and the content/media roots together form the asset pipeline. Foundry copies content assets, theme assets, plugin assets, and user media into the build output, and also bundles CSS. Media references use a `media:` scheme that resolves to stable public paths, which keeps authored Markdown independent from filesystem layout.

10. **Configuration and data persistence**
`internal/config` loads and validates YAML-based configuration from `content/config/site.yaml` and environment overlays. `internal/data` reads additional structured data from `data/`, including admin state such as sessions, locks, and other runtime files. The system keeps user-editable content separate from operational state, but both feed the same site/runtime graph.

11. **Server, preview, and live reload**
`internal/server` orchestrates preview serving, request handling, live reload, debug endpoints, and rebuild coordination. It watches the filesystem through `internal/content/watcher`, triggers incremental updates, and serves the generated site plus runtime APIs. Live reload can be stream-based or polling-based, which affects the browser connection model during development.

12. **CLI and operational commands**
`cmd/foundry` is the main entrypoint and `internal/commands` contains the subcommands for build, serve, validate, doctor, backup, theme/plugin management, release, update, and content import/export. These commands are thin orchestration layers over the internal subsystems rather than separate business logic paths.

13. **Backups, updates, and standalone runtime**
`internal/backup`, `internal/standalone`, and `internal/updater` provide operational support beyond simple build/serve behavior. Backups snapshot the content tree, standalone mode turns Foundry into a portable persistent process with its own runtime directory, and the updater integrates with GitHub Releases for managed self-update flows.

14. **SDK surface**
The `sdk/` tree is a deliberate external contract boundary. It exposes stable JavaScript clients for admin and frontend consumers, plus generated browser entrypoints and JSON artifacts under `/__foundry` and `public/__foundry/`. This lets themes and admin extensions integrate with Foundry through supported APIs instead of internal endpoints.

15. **Repo-level toolchain and distribution**
The repository is structured for Go builds plus web asset tooling. Go handles the server, CLI, and runtime logic; Node/Playwright support formatting and local browser tests for shipped themes; GitHub Actions builds, tests, releases binaries, and publishes docs coverage. The docs under `docs/` and sample content under `content/` also act as part of the architecture, showing the expected runtime project layout.

Main entry points: [`internal/renderer/renderer.go`](https://github.com/sphireinc/foundry/blob/main/internal/renderer/renderer.go) (Renderer), [`internal/commands`](https://github.com/sphireinc/foundry/tree/main/internal/commands) (Commands), [`internal/site/graph.go`](https://github.com/sphireinc/foundry/blob/main/internal/site/graph.go) (Site graph), [`internal/server/server.go`](https://github.com/sphireinc/foundry/blob/main/internal/server/server.go) (Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_cli["CLI"]
  node_cmd_foundry["foundry<br/>Go entrypoint<br/>[main.go]"]
  node_cmd_plugin_sync["plugin-sync<br/>Go utility<br/>[main.go]"]
  node_commands["Commands<br/>command layer"]
end

subgraph group_grp_core["Core runtime"]
  node_config["Config<br/>yaml loader<br/>[config.go]"]
  node_content["Content<br/>[graph.go]"]
  node_site{{"Site graph<br/>site model<br/>[graph.go]"}}
  node_taxonomy["Taxonomy<br/>indexing<br/>[taxonomy.go]"]
  node_router["Router<br/>url resolver<br/>[resolver.go]"]
  node_deps{{"Deps graph<br/>incremental graph<br/>[graph.go]"}}
  node_renderer["Renderer<br/>render boundary<br/>[renderer.go]"]
  node_assets["Assets<br/>asset pipeline<br/>[pipeline.go]"]
  node_media["Media<br/>[media.go]"]
end

subgraph group_grp_admin["Admin"]
  node_admin["Admin<br/>[service.go]"]
end

subgraph group_grp_ext["Extensions"]
  node_plugins["Plugins<br/>plugin subsystem<br/>[plugin.go]"]
  node_theme["Themes<br/>theme subsystem<br/>[manager.go]"]
  node_sdk["SDK<br/>public contract<br/>[http.js]"]
end

subgraph group_grp_ops["Operations"]
  node_server["Server<br/>preview runtime<br/>[server.go]"]
  node_backup["Backup<br/>ops support<br/>[backup.go]"]
  node_standalone["Standalone<br/>runtime mode<br/>[standalone.go]"]
  node_updater["Updater<br/>self-update<br/>[updater.go]"]
end

node_cmd_foundry -->|"dispatches"| node_commands
node_cmd_plugin_sync -->|"syncs"| node_plugins
node_commands -->|"loads"| node_config
node_commands -->|"builds"| node_content
node_commands -->|"orchestrates"| node_site
node_content -->|"feeds"| node_site
node_config -->|"configures"| node_site
node_site -->|"indexes"| node_taxonomy
node_site -->|"routes"| node_router
node_site -->|"tracks"| node_deps
node_deps -->|"invalidates"| node_renderer
node_renderer -->|"emits"| node_assets
node_renderer -->|"resolves"| node_media
node_renderer -->|"hooks"| node_plugins
node_renderer -->|"templates"| node_theme
node_server -->|"watches"| node_content
node_server -->|"rebuilds"| node_deps
node_server -->|"serves"| node_renderer
node_admin -->|"exposes"| node_sdk
node_admin -->|"manages"| node_plugins
node_admin -->|"skins"| node_theme
node_plugins -->|"extends"| node_sdk
node_theme -->|"contracts"| node_sdk
node_backup -->|"used by"| node_commands
node_standalone -->|"wraps"| node_server
node_updater -->|"used by"| node_commands

click node_cmd_foundry "https://github.com/sphireinc/foundry/blob/main/cmd/foundry/main.go"
click node_cmd_plugin_sync "https://github.com/sphireinc/foundry/blob/main/cmd/plugin-sync/main.go"
click node_commands "https://github.com/sphireinc/foundry/tree/main/internal/commands"
click node_config "https://github.com/sphireinc/foundry/blob/main/internal/config/config.go"
click node_content "https://github.com/sphireinc/foundry/blob/main/internal/content/graph.go"
click node_site "https://github.com/sphireinc/foundry/blob/main/internal/site/graph.go"
click node_taxonomy "https://github.com/sphireinc/foundry/blob/main/internal/taxonomy/taxonomy.go"
click node_router "https://github.com/sphireinc/foundry/blob/main/internal/router/resolver.go"
click node_deps "https://github.com/sphireinc/foundry/blob/main/internal/deps/graph.go"
click node_renderer "https://github.com/sphireinc/foundry/blob/main/internal/renderer/renderer.go"
click node_assets "https://github.com/sphireinc/foundry/blob/main/internal/assets/pipeline.go"
click node_media "https://github.com/sphireinc/foundry/blob/main/internal/media/media.go"
click node_server "https://github.com/sphireinc/foundry/blob/main/internal/server/server.go"
click node_admin "https://github.com/sphireinc/foundry/blob/main/internal/admin/service/service.go"
click node_plugins "https://github.com/sphireinc/foundry/blob/main/internal/plugins/plugin.go"
click node_theme "https://github.com/sphireinc/foundry/blob/main/internal/theme/manager.go"
click node_sdk "https://github.com/sphireinc/foundry/blob/main/sdk/core/http.js"
click node_backup "https://github.com/sphireinc/foundry/blob/main/internal/backup/backup.go"
click node_standalone "https://github.com/sphireinc/foundry/blob/main/internal/standalone/standalone.go"
click node_updater "https://github.com/sphireinc/foundry/blob/main/internal/updater/updater.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_foundry,node_cmd_plugin_sync,node_commands toneBlue
class node_config,node_content,node_site,node_taxonomy,node_router,node_deps,node_renderer,node_assets,node_media toneAmber
class node_admin toneMint
class node_plugins,node_theme,node_sdk toneRose
class node_server,node_backup,node_standalone,node_updater toneIndigo
```

## Components

### CLI

Command entrypoints and orchestration commands.

- [foundry](https://github.com/sphireinc/foundry/blob/main/cmd/foundry/main.go): Go entrypoint · Main CLI binary. · `cmd/foundry/main.go`
- [plugin-sync](https://github.com/sphireinc/foundry/blob/main/cmd/plugin-sync/main.go): Go utility · Standalone plugin synchronization tool. · `cmd/plugin-sync/main.go`
- [Commands](https://github.com/sphireinc/foundry/tree/main/internal/commands): command layer · Subcommand orchestration for build, serve, validate, and management flows. · `internal/commands`

### Core runtime

Content, site, routing, rendering, assets, and dependencies.

- [Config](https://github.com/sphireinc/foundry/blob/main/internal/config/config.go): yaml loader · Loads and validates site configuration. · `internal/config/config.go`
- [Content](https://github.com/sphireinc/foundry/blob/main/internal/content/graph.go): content graph · Parses documents, frontmatter, routes, and watch workflow. · `internal/content/graph.go`
- [Site graph](https://github.com/sphireinc/foundry/blob/main/internal/site/graph.go): site model · Canonical in-memory site representation and project assembly. · `internal/site/graph.go`
- [Taxonomy](https://github.com/sphireinc/foundry/blob/main/internal/taxonomy/taxonomy.go): indexing · Builds taxonomy collections and archive views. · `internal/taxonomy/taxonomy.go`
- [Router](https://github.com/sphireinc/foundry/blob/main/internal/router/resolver.go): url resolver · Assigns routes and resolves URL mappings. · `internal/router/resolver.go`
- [Deps graph](https://github.com/sphireinc/foundry/blob/main/internal/deps/graph.go): incremental graph · Tracks render dependencies for partial rebuilds. · `internal/deps/graph.go`
- [Renderer](https://github.com/sphireinc/foundry/blob/main/internal/renderer/renderer.go): render boundary · Combines site state, templates, markup, and hooks into outputs. · `internal/renderer/renderer.go`
- [Assets](https://github.com/sphireinc/foundry/blob/main/internal/assets/pipeline.go): asset pipeline · Collects and emits content, theme, plugin, and bundle assets. · `internal/assets/pipeline.go`
- [Media](https://github.com/sphireinc/foundry/blob/main/internal/media/media.go): media resolver · Resolves authored media references to public paths. · `internal/media/media.go`

### Admin

Authentication, HTTP, service layer, UI, and persisted state.

- [Admin](https://github.com/sphireinc/foundry/blob/main/internal/admin/service/service.go): admin subsystem · Auth, HTTP handlers, services, and admin UI orchestration. · `internal/admin/service/service.go`

### Extensions

Theme and plugin surfaces plus external SDK contracts.

- [Plugins](https://github.com/sphireinc/foundry/blob/main/internal/plugins/plugin.go): plugin subsystem · Discovery, validation, lifecycle, security, and runtime integration. · `internal/plugins/plugin.go`
- [Themes](https://github.com/sphireinc/foundry/blob/main/internal/theme/manager.go): theme subsystem · Theme installation, validation, security, and management. · `internal/theme/manager.go`
- [SDK](https://github.com/sphireinc/foundry/blob/main/sdk/core/http.js): public contract · Stable frontend and admin client surfaces plus plugin RPC protocol. · `sdk/core/http.js`

### Operations

Backup, standalone runtime, updater, and server/preview orchestration.

- [Server](https://github.com/sphireinc/foundry/blob/main/internal/server/server.go): preview runtime · Serves preview traffic, reload, debug, and rebuild coordination. · `internal/server/server.go`
- [Backup](https://github.com/sphireinc/foundry/blob/main/internal/backup/backup.go): ops support · Snapshots and restores project state. · `internal/backup/backup.go`
- [Standalone](https://github.com/sphireinc/foundry/blob/main/internal/standalone/standalone.go): runtime mode · Portable persistent process mode and runtime directory support. · `internal/standalone/standalone.go`
- [Updater](https://github.com/sphireinc/foundry/blob/main/internal/updater/updater.go): self-update · Release-driven update flow. · `internal/updater/updater.go`

## Connections

- foundry → Commands: dispatches · Main binary routes to subcommands.
- plugin-sync → Plugins: syncs · Utility operates on plugin metadata and installation state.
- Commands → Config: loads · Commands start from validated configuration.
- Commands → Content: builds · Command flows invoke content loading and workflows.
- Commands → Site graph: orchestrates · Build and serve commands assemble the site graph.
- Content → Site graph: feeds · Documents and routes populate the canonical site model.
- Config → Site graph: configures · Site assembly incorporates site configuration.
- Site graph → Taxonomy: indexes · Site graph includes taxonomy structures.
- Site graph → Router: routes · Canonical site data is assigned public URLs.
- Site graph → Deps graph: tracks · Rendered artifacts are linked into dependency graph.
- Deps graph → Renderer: invalidates · Dependency changes trigger selective rendering.
- Renderer → Assets: emits · Render boundary also produces bundled assets.
- Renderer → Media: resolves · Rendering turns media references into stable paths.
- Renderer → Plugins: hooks · Renderer integrates plugin contributions and hooks.
- Renderer → Themes: templates · Theme layouts and presentation contract drive rendering.
- Server → Content: watches · Preview server watches source changes.
- Server → Deps graph: rebuilds · Server uses dependency graph for incremental updates.
- Server → Renderer: serves · Server exposes the rendered site and preview artifacts.
- Admin → SDK: exposes · Admin UI and APIs are consumed through stable SDK contracts.
- Admin → Plugins: manages · Admin surface can install, inspect, and manage plugins.
- Admin → Themes: skins · Admin UI is themeable.
- Plugins → SDK: extends · Plugins integrate through supported admin/frontend and RPC APIs.
- Themes → SDK: contracts · Theme manifests and UI surfaces align to SDK contracts.
- Backup → Commands: used by · Backup operations are exposed as commands.
- Standalone → Server: wraps · Standalone mode runs the server/runtime persistently.
- Updater → Commands: used by · Update flow is surfaced through command orchestration.
