# visual-framework/vf-wp architecture

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

- Interactive diagram: https://gitdiagram.com/visual-framework/vf-wp
- Repository: https://github.com/visual-framework/vf-wp

## Overview

1. This repository is a WordPress monorepo for “VF 2.0” sites, built around the Visual Framework. The architecture is plugin-heavy: shared behavior lives in plugins, while themes mainly compose templates and expose presentation variants.

2. The runtime boundary is classic WordPress/PHP. Requests are handled by the active theme under `wp-content/themes/`, while feature logic is delivered by many custom plugins under `wp-content/plugins/`. Gutenberg editor behavior, frontend rendering, and ACF field definitions are all part of the same WordPress execution environment.

3. There are two main themes:
   - `wp-content/themes/vf-wp`: the base theme, with global layouts, page templates, partials, and theme functions.
   - `wp-content/themes/vf-wp-groups`: a specialized theme for group sites, with its own template set, custom archive/singular layouts, and group-specific header patterns.
   The base theme is the main presentation shell; the groups theme is a site-variant layer on top of the same Visual Framework conventions.

4. The theme structure is driven by reusable content patterns:
   - `blocks/` contains block definitions backed by `block.json`, ACF JSON, PHP templates, and sometimes widget shims.
   - `template-*.php` files define page-level compositions.
   - `partials/` contains reusable layout fragments.
   In other words, the theme is a composition layer over reusable block/container primitives rather than a monolithic page implementation.

5. The plugin layer is where most domain logic sits. `vf-wp` acts as the central platform plugin, with helpers for ACF integration, block registration, container registration, caching, and template support. Other plugins add site features such as events, taxonomy, members, publications, banners, headers/footers, navigation, search, jobs, and news. Many are single-purpose content modules with their own ACF group JSON and PHP template rendering.

6. `vf-gutenberg` is a major subsystem. It provides custom Gutenberg blocks and editor support code in React/JSX, plus rendering hooks, defaults, term lookups, iframe handling, and block transforms. It bridges the editor experience to the frontend templates and is paired with precompiled assets in both the plugin and theme asset trees.

7. The Visual Framework component pipeline is separated from WordPress-specific code. Source components live under `vf-components/`, with many component packages containing Sass, templates, config, and precompiled JS. These are built into the WordPress theme’s asset tree, especially `wp-content/themes/vf-wp/assets/assets/`, where each component ends up as a distributable CSS/JS bundle.

8. Build-time generation is a key architectural boundary. `gulpfile.js` and `gulp-tasks/` orchestrate:
   - compiling component Sass into the theme stylesheet,
   - building component JavaScript bundles,
   - precompiling Nunjucks/templates,
   - building Gutenberg assets.
   The repo also contains `vf-core`, `vf-extensions`, Fractal/Eleventy-related code, and component-generator tooling, which are part of the asset generation pipeline rather than the WordPress runtime itself.

9. Content and configuration are heavily declarative. ACF field groups are stored in JSON across themes and plugins, and many blocks/containers are defined by `block.json`, group JSON, and template PHP files. That means the UI structure is mostly configuration-driven, with PHP templates acting as renderers rather than business logic holders.

10. The main request flow is: WordPress loads a theme template, the theme assembles layout from partials/blocks/containers, and those render against shared Visual Framework assets plus plugin-provided data. For dynamic content, plugins supply queries, custom post types, taxonomies, and editor metadata; for static layout, the theme and component assets provide the shell.

11. Local development and packaging are containerized. `docker-compose.yml`, `bin/dev`, and the `.env` file support a reproducible WordPress stack with database, admin login, mail capture, and diagnostics. This is the operational boundary for running the site locally.

12. CI/CD is split across GitHub Actions and GitLab CI, with build workflows that run the Gulp build and validate the asset pipeline. The repo also depends on an external plugins repository, so deployment is not fully self-contained; some WordPress plugins are version-pinned via tags in `.env`.

13. For an architecture diagram, the most important boxes are:
   - WordPress runtime
   - base theme vs. groups theme
   - central platform plugin (`vf-wp`)
   - feature plugins
   - Gutenberg/editor subsystem
   - shared Visual Framework component library and build pipeline
   - Docker/local dev environment
   - external plugin dependency repository
   These boundaries capture how content, rendering, and asset generation are separated in the repository.

Main entry points: [`wp-content/themes/vf-wp`](https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp) (vf-wp), [`gulpfile.js`](https://github.com/visual-framework/vf-wp/blob/master/gulpfile.js) (Gulp build), [`wp-content/themes/vf-wp-groups`](https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp-groups) (vf-wp-groups), [`wp-content/plugins/vf-gutenberg`](https://github.com/visual-framework/vf-wp/tree/master/wp-content/plugins/vf-gutenberg) (vf-gutenberg)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["WordPress runtime"]
  node_wp_runtime[("WordPress<br/>PHP runtime")]
end

subgraph group_presentation["Themes"]
  node_theme_base["vf-wp<br/>base theme"]
  node_theme_groups["vf-wp-groups<br/>variant theme"]
  node_theme_blocks["Theme blocks<br/>block templates"]
  node_theme_partials["Theme partials<br/>shared fragments"]
  node_theme_functions["Theme hooks<br/>theme logic"]
  node_groups_header["Group header<br/>header pattern"]
  node_theme_assets["Theme assets<br/>bundled assets"]
end

subgraph group_plugins["Plugins"]
  node_vf_wp_plugin["vf-wp<br/>platform plugin"]
  node_feature_plugins["Feature plugins<br/>site modules"]
end

subgraph group_editor["Gutenberg"]
  node_vf_gutenberg_plugin["vf-gutenberg<br/>editor plugin"]
  node_gutenberg_blocks["Block editor<br/>React/JSX blocks"]
  node_gutenberg_hooks["Editor hooks<br/>render bridge"]
  node_gutenberg_core["Core blocks<br/>block set"]
end

subgraph group_vf["Visual Framework"]
  node_vf_components["vf-components<br/>component library"]
  node_build_pipeline["Gulp build<br/>asset pipeline<br/>[gulpfile.js]"]
  node_vf_core_tasks["vf-core tasks<br/>build tasks<br/>[vf-core.js]"]
  node_vf_gutenberg_tasks["vf-gutenberg tasks<br/>build tasks<br/>[vf-gutenberg.js]"]
end

subgraph group_ops["Ops"]
  node_dev_env[("Dev stack<br/>containerized dev<br/>[docker-compose.yml]")]
  node_ci_cd["CI/CD<br/>automation<br/>[workflows]"]
  node_external_plugins["External plugins<br/>dependency repo<br/>[.gitmodules]"]
end

node_wp_runtime -->|"loads"| node_theme_base
node_wp_runtime -->|"loads"| node_theme_groups
node_wp_runtime -->|"executes"| node_vf_wp_plugin
node_wp_runtime -->|"executes"| node_vf_gutenberg_plugin
node_wp_runtime -->|"executes"| node_feature_plugins
node_theme_base -->|"composes"| node_theme_blocks
node_theme_base -->|"includes"| node_theme_partials
node_theme_base -->|"bootstraps"| node_theme_functions
node_theme_groups -->|"specializes"| node_groups_header
node_theme_groups -->|"reuses"| node_theme_partials
node_vf_wp_plugin -->|"supports"| node_theme_blocks
node_vf_wp_plugin -->|"shared APIs"| node_feature_plugins
node_vf_gutenberg_plugin -->|"defines"| node_gutenberg_blocks
node_vf_gutenberg_plugin -->|"orchestrates"| node_gutenberg_hooks
node_vf_gutenberg_plugin -->|"extends"| node_gutenberg_core
node_gutenberg_blocks -->|"renders into"| node_theme_blocks
node_vf_components -->|"feeds"| node_build_pipeline
node_build_pipeline -->|"builds"| node_theme_assets
node_build_pipeline -->|"runs"| node_vf_core_tasks
node_build_pipeline -->|"runs"| node_vf_gutenberg_tasks
node_theme_base -->|"consumes"| node_vf_components
node_theme_groups -->|"consumes"| node_vf_components
node_dev_env -->|"hosts"| node_wp_runtime
node_ci_cd -->|"validates"| node_build_pipeline
node_external_plugins -->|"supplies"| node_feature_plugins

click node_theme_base "https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp"
click node_theme_groups "https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp-groups"
click node_theme_blocks "https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp/blocks"
click node_theme_partials "https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp/partials"
click node_theme_functions "https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp/functions"
click node_groups_header "https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp-groups/vf-wp-groups-header"
click node_vf_wp_plugin "https://github.com/visual-framework/vf-wp/tree/master/wp-content/plugins/vf-wp"
click node_vf_gutenberg_plugin "https://github.com/visual-framework/vf-wp/tree/master/wp-content/plugins/vf-gutenberg"
click node_feature_plugins "https://github.com/visual-framework/vf-wp/tree/master/wp-content/plugins"
click node_gutenberg_blocks "https://github.com/visual-framework/vf-wp/tree/master/wp-content/plugins/vf-gutenberg/blocks"
click node_gutenberg_hooks "https://github.com/visual-framework/vf-wp/tree/master/wp-content/plugins/vf-gutenberg/blocks/hooks"
click node_gutenberg_core "https://github.com/visual-framework/vf-wp/tree/master/wp-content/plugins/vf-gutenberg/blocks/vf-core"
click node_vf_components "https://github.com/visual-framework/vf-wp/tree/master/vf-components"
click node_theme_assets "https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp/assets/assets"
click node_build_pipeline "https://github.com/visual-framework/vf-wp/blob/master/gulpfile.js"
click node_vf_core_tasks "https://github.com/visual-framework/vf-wp/blob/master/gulp-tasks/vf-core.js"
click node_vf_gutenberg_tasks "https://github.com/visual-framework/vf-wp/blob/master/gulp-tasks/vf-gutenberg.js"
click node_dev_env "https://github.com/visual-framework/vf-wp/blob/master/docker-compose.yml"
click node_ci_cd "https://github.com/visual-framework/vf-wp/blob/master/.github/workflows"
click node_external_plugins "https://github.com/visual-framework/vf-wp/blob/master/.gitmodules"

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_wp_runtime toneBlue
class node_theme_base,node_theme_groups,node_theme_blocks,node_theme_partials,node_theme_functions,node_groups_header,node_theme_assets toneAmber
class node_vf_wp_plugin,node_feature_plugins toneMint
class node_vf_gutenberg_plugin,node_gutenberg_blocks,node_gutenberg_hooks,node_gutenberg_core toneRose
class node_vf_components,node_build_pipeline,node_vf_core_tasks,node_vf_gutenberg_tasks toneIndigo
class node_dev_env,node_ci_cd,node_external_plugins toneTeal
```

## Components

### WordPress runtime

PHP request handling, theme rendering, and plugin-provided features.

- **WordPress**: PHP runtime · Core request lifecycle that loads the active theme and installed plugins.

### Themes

Base theme and site-variant theme layers that compose layouts.

- [vf-wp](https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp): base theme · Main presentation shell with templates, partials, blocks, and theme functions. · `wp-content/themes/vf-wp`
- [vf-wp-groups](https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp-groups): variant theme · Group-site theme variant with custom archives, singles, templates, and header patterns. · `wp-content/themes/vf-wp-groups`
- [Theme blocks](https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp/blocks): block templates · Theme-defined block compositions backed by block.json, ACF JSON, and PHP templates. · `wp-content/themes/vf-wp/blocks`
- [Theme partials](https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp/partials): shared fragments · Reusable layout fragments and template parts used by theme page compositions. · `wp-content/themes/vf-wp/partials`
- [Theme hooks](https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp/functions): theme logic · Theme bootstrap and helpers for content, pagination, widgets, admin behavior, and block wiring. · `wp-content/themes/vf-wp/functions`
- [Group header](https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp-groups/vf-wp-groups-header): header pattern · Group-theme header composition with hero, masthead, and navigation pieces. · `wp-content/themes/vf-wp-groups/vf-wp-groups-header`
- [Theme assets](https://github.com/visual-framework/vf-wp/tree/master/wp-content/themes/vf-wp/assets/assets): bundled assets · Compiled CSS/JS bundles and distributable component assets consumed by the base theme. · `wp-content/themes/vf-wp/assets/assets`

### Plugins

Platform plugin and feature modules loaded into the WordPress runtime.

- [vf-wp](https://github.com/visual-framework/vf-wp/tree/master/wp-content/plugins/vf-wp): platform plugin · Central WordPress platform plugin for ACF, blocks, containers, caching, and template support. · `wp-content/plugins/vf-wp`
- [Feature plugins](https://github.com/visual-framework/vf-wp/tree/master/wp-content/plugins): site modules · Domain plugins for events, publications, members, navigation, headers/footers, search, jobs, and related content. · `wp-content/plugins`

### Gutenberg

Editor-side blocks, hooks, and rendering bridge code.

- [vf-gutenberg](https://github.com/visual-framework/vf-wp/tree/master/wp-content/plugins/vf-gutenberg): editor plugin · Major Gutenberg subsystem providing custom blocks, hooks, transforms, and render integration. · `wp-content/plugins/vf-gutenberg`
- [Block editor](https://github.com/visual-framework/vf-wp/tree/master/wp-content/plugins/vf-gutenberg/blocks): React/JSX blocks · Editor-side block registrations, controls, and view/edit implementations. · `wp-content/plugins/vf-gutenberg/blocks`
- [Editor hooks](https://github.com/visual-framework/vf-wp/tree/master/wp-content/plugins/vf-gutenberg/blocks/hooks): render bridge · Hooks and utilities that connect defaults, Nunjucks, iframe behavior, terms, and transient rendering. · `wp-content/plugins/vf-gutenberg/blocks/hooks`
- [Core blocks](https://github.com/visual-framework/vf-wp/tree/master/wp-content/plugins/vf-gutenberg/blocks/vf-core): block set · Shared block set, transforms, and deprecated editor components used across VF content. · `wp-content/plugins/vf-gutenberg/blocks/vf-core`

### Visual Framework

Shared component library and build pipeline outside the WordPress runtime.

- [vf-components](https://github.com/visual-framework/vf-wp/tree/master/vf-components): component library · Shared Visual Framework source components with Sass, templates, config, and precompiled outputs. · `vf-components`
- [Gulp build](https://github.com/visual-framework/vf-wp/blob/master/gulpfile.js): asset pipeline · Build-time orchestration for components, Sass, JavaScript bundles, templates, and Gutenberg assets. · `gulpfile.js`
- [vf-core tasks](https://github.com/visual-framework/vf-wp/blob/master/gulp-tasks/vf-core.js): build tasks · Core build task set used by the Visual Framework asset pipeline. · `gulp-tasks/vf-core.js`
- [vf-gutenberg tasks](https://github.com/visual-framework/vf-wp/blob/master/gulp-tasks/vf-gutenberg.js): build tasks · Build task entrypoint for Gutenberg asset compilation. · `gulp-tasks/vf-gutenberg.js`

### Ops

Local development, containers, and CI/CD automation.

- [Dev stack](https://github.com/visual-framework/vf-wp/blob/master/docker-compose.yml): containerized dev · Docker-based local WordPress environment with database, mail capture, and diagnostics. · `docker-compose.yml`
- [CI/CD](https://github.com/visual-framework/vf-wp/blob/master/.github/workflows): automation · GitHub Actions and GitLab CI workflows that validate and build the repository. · `.github/workflows`
- [External plugins](https://github.com/visual-framework/vf-wp/blob/master/.gitmodules): dependency repo · Pinned external WordPress plugins source used by the monorepo. · `.gitmodules`

## Connections

- WordPress → vf-wp: loads · WordPress activates the base theme for most requests.
- WordPress → vf-wp-groups: loads · WordPress can activate the groups theme for group sites.
- WordPress → vf-wp: executes · Platform plugin runs within the WordPress lifecycle.
- WordPress → vf-gutenberg: executes · Editor subsystem participates in the same PHP/WordPress runtime.
- WordPress → Feature plugins: executes · Feature plugins extend content types, queries, and site behavior.
- vf-wp → Theme blocks: composes · The base theme assembles pages from reusable blocks.
- vf-wp → Theme partials: includes · Templates reuse partials for shared layout pieces.
- vf-wp → Theme hooks: bootstraps · Theme functions register hooks and theme behavior.
- vf-wp-groups → Group header: specializes · Groups theme defines its own header and navigation composition.
- vf-wp-groups → Theme partials: reuses · Group templates reuse shared fragments and summary variants.
- vf-wp → Theme blocks: supports · Platform plugin supports block and container registration.
- vf-wp → Feature plugins: shared APIs · Feature plugins rely on the central plugin for common helpers.
- vf-gutenberg → Block editor: defines · The Gutenberg plugin provides custom block editor UI.
- vf-gutenberg → Editor hooks: orchestrates · Hook layer bridges editor defaults, rendering, and terms.
- vf-gutenberg → Core blocks: extends · Shared editor blocks and transforms are part of the subsystem.
- Block editor → Theme blocks: renders into · Editor blocks map to theme/ACF-backed front-end templates.
- vf-components → Gulp build: feeds · Component source is compiled by the build pipeline.
- Gulp build → Theme assets: builds · Pipeline outputs distributable CSS/JS bundles into the theme asset tree.
- Gulp build → vf-core tasks: runs · Core Gulp tasks orchestrate component compilation.
- Gulp build → vf-gutenberg tasks: runs · Dedicated tasks build Gutenberg-related assets.
- vf-wp → vf-components: consumes · The base theme consumes shared Visual Framework components.
- vf-wp-groups → vf-components: consumes · The groups theme also composes from the shared component library.
- Dev stack → WordPress: hosts · Docker stack provides the local WordPress runtime.
- CI/CD → Gulp build: validates · CI workflows run the build and asset validation steps.
- External plugins → Feature plugins: supplies · Some plugins are sourced from an external dependency repository.
