How visual-framework/vf-wp works
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: vf-wp vf-wp · gulpfile.js Gulp build · vf-wp-groups vf-wp-groups · vf-gutenberg vf-gutenberg
Components 21
WordPress runtime
PHP request handling, theme rendering, and plugin-provided features.
- WordPress · Core request lifecycle that loads the active theme and installed plugins.
Themes
Base theme and site-variant theme layers that compose layouts.
- vf-wp · Main presentation shell with templates, partials, blocks, and theme functions.
wp-content/themes/vf-wp - vf-wp-groups · Group-site theme variant with custom archives, singles, templates, and header patterns.
wp-content/themes/vf-wp-groups - Theme blocks · Theme-defined block compositions backed by block.json, ACF JSON, and PHP templates.
wp-content/themes/vf-wp/blocks - Theme partials · Reusable layout fragments and template parts used by theme page compositions.
wp-content/themes/vf-wp/partials - Theme hooks · Theme bootstrap and helpers for content, pagination, widgets, admin behavior, and block wiring.
wp-content/themes/vf-wp/functions - Group header · Group-theme header composition with hero, masthead, and navigation pieces.
wp-content/themes/vf-wp-groups/vf-wp-groups-header - Theme 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 · Central WordPress platform plugin for ACF, blocks, containers, caching, and template support.
wp-content/plugins/vf-wp - Feature plugins · 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 · Major Gutenberg subsystem providing custom blocks, hooks, transforms, and render integration.
wp-content/plugins/vf-gutenberg - Block editor · Editor-side block registrations, controls, and view/edit implementations.
wp-content/plugins/vf-gutenberg/blocks - Editor hooks · Hooks and utilities that connect defaults, Nunjucks, iframe behavior, terms, and transient rendering.
wp-content/plugins/vf-gutenberg/blocks/hooks - Core blocks · 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 · Shared Visual Framework source components with Sass, templates, config, and precompiled outputs.
vf-components - Gulp build · Build-time orchestration for components, Sass, JavaScript bundles, templates, and Gutenberg assets.
gulpfile.js - vf-core tasks · Core build task set used by the Visual Framework asset pipeline.
gulp-tasks/vf-core.js - vf-gutenberg tasks · Build task entrypoint for Gutenberg asset compilation.
gulp-tasks/vf-gutenberg.js
Ops
Local development, containers, and CI/CD automation.
- Dev stack · Docker-based local WordPress environment with database, mail capture, and diagnostics.
docker-compose.yml - CI/CD · GitHub Actions and GitLab CI workflows that validate and build the repository.
.github/workflows - External plugins · Pinned external WordPress plugins source used by the monorepo.
.gitmodules
Connections 25
- 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.