# webmultipliers/examplepress-theme architecture

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

- Interactive diagram: https://gitdiagram.com/webmultipliers/examplepress-theme
- Repository: https://github.com/webmultipliers/examplepress-theme

## Overview

1. **Project shape and boundary**
   - This is a **WordPress block theme** that behaves more like an application platform than a traditional theme.
   - The repo is split into two clear halves:
     - **Theme infrastructure**: routing engine, feature registry, guards, config, admin tooling.
     - **App content / companions**: Blockstudio template blocks and demo companion plugin(s) that provide actual routed pages.

2. **Main request entry point**
   - All front-end requests converge on `templates/index.html`.
   - That template contains only the **router block** from `blockstudio/router`, so the theme bypasses the normal WordPress template hierarchy.
   - The router resolves a route slug, computes a Blockstudio block name, and dispatches to a matching template block.

3. **Routing pipeline**
   - The runtime route flow is:
     - resolve current route via `examplepress_get_current_route()`
     - enrich route payload with `examplepress_route_data`
     - emit `examplepress_route_resolved`
     - render the target block with `bs_block(...)`
   - The default fallback route is `get-started`, implemented in `blockstudio/templates/get-started`.
   - Companion plugins can intercept routing by providing their own route logic and template blocks.

4. **Theme engine core**
   - The PHP bootstrap lives in `functions.php` and `blockstudio/init.php`, with feature-specific bootstraps under `inc/` and `blockstudio/`.
   - `inc/router.php`, `inc/route-registry.php`, and `inc/features.php` form the core runtime coordination layer.
   - `inc/dependencies.php`, `inc/config.php`, and `examplepress.json` define the declarative configuration and dependency metadata that drive behavior.

5. **Feature registry and configuration model**
   - Features are registered in `inc/features/*.php` and resolved through a priority chain:
     1. PHP filters
     2. `examplepress.json`
     3. default registration values
   - `inc/feature-registry.php` appears to centralize the lookup and merging logic.
   - This lets the theme expose behavior as a configurable platform rather than hard-coded theme options.

6. **Editor, admin, and site hardening**
   - A major subsystem is the set of **editor and template guards** in `inc/features/guards.php`.
   - Other feature modules control:
     - admin UI customization
     - site options / permalink behavior
     - theme support flags
     - editor controls like block restriction and disabling patterns/openverse
   - These are used to prevent users or plugins from bypassing the router or altering the site model in unsupported ways.

7. **Design token injection**
   - `inc/features/design-tokens.php` maps config-driven design settings into WordPress theme supports and `theme.json`.
   - The theme ships a `theme.json` plus a runtime path that can inject or lock settings like colors, layout widths, typography, and strict appearance controls.
   - This is the design-system boundary between declarative config and WordPress editor behavior.

8. **Admin experience**
   - `inc/admin/settings-page.php` powers a read-only settings screen in wp-admin.
   - UI assets live in `assets/css/admin-settings.css` and `assets/js/admin-settings.js`.
   - The dashboard surfaces the resolved state of features, config, dependencies, available blocks, health checks, and build/demo actions.

9. **Build and companion app scaffolding**
   - `inc/scaffolder.php`, `inc/cli.php`, and the “Build” portion of the settings page support generating **companion plugins**.
   - The README describes a Troy Server integration using a GitHub Personal Access Token to scaffold a repository with CI/CD and optional SFTP deployment.
   - This is the theme’s app-generation boundary: it creates the companion codebase that actually owns routes and page blocks.

10. **Demo companion plugin as reference app**
   - `demo/examplepress-demo` is a bundled companion plugin showing how the platform is meant to be used.
   - It defines its own template blocks under `app/templates/*` for `front`, `single`, and `404`, each with its own Blockstudio block metadata and styles.
   - This demo plugin can take over routing and demonstrates the “theme as engine, plugin as application” split.

11. **API, GitHub, updater, and notifications**
   - `inc/api.php` plus `inc/api/*.php` expose programmatic endpoints for apps, connections, and demo management.
   - `inc/github.php`, `inc/github-app.php`, and `inc/github-app-key.php` suggest GitHub App / repository automation support.
   - `inc/updater.php` and `inc/notifications.php` provide maintenance and status messaging around theme and companion lifecycle.

12. **Blockstudio integration and local component layout**
   - The `blockstudio/` folder contains the theme’s local Blockstudio modules:
     - router
     - login
     - plugins
     - site-editor
     - reusable templates such as `get-started`
   - `blockstudio/site-editor` includes editor-specific scripts/styles, while `blockstudio/login` and `assets/css/login.css` handle branded login experience.
   - The `blockstudio.json` file likely defines Blockstudio-specific build/runtime configuration.

13. **Supporting artifacts**
   - `schema/examplepress-theme.json` documents the structure of `examplepress.json`.
   - `composer.json` indicates PHP dependency/autoload management.
   - `docs/` contains design and behavior documentation for routing, guards, configuration, the feature registry, and companion plugins.
   - `languages/` and `examplepress-theme.pot` support translation.

14. **How to draw the architecture**
   - Draw a single front-door through `templates/index.html` into the Blockstudio router.
   - Split the system into two trust zones:
     - **Theme engine**: config, features, guards, admin, API, updater, scaffolder.
     - **Companion app/plugin**: route handlers and page template blocks.
   - Show `examplepress.json` and PHP filters as shared control inputs into the feature registry and routing decisions.

Main entry points: [`inc/features.php`](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features.php) (Features bootstrap), [`inc/router.php`](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/router.php) (Route runtime), [`inc/feature-registry.php`](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/feature-registry.php) (Feature registry), [`demo/examplepress-demo/examplepress-demo.php`](https://github.com/webmultipliers/examplepress-theme/blob/development/demo/examplepress-demo/examplepress-demo.php) (Demo plugin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_theme_engine["Theme engine"]
  node_templates_index["Front door<br/>entry template<br/>[index.html]"]
  node_blockstudio_router["Router block<br/>block module<br/>[index.php]"]
  node_theme_bootstrap["Bootstrap<br/>[functions.php]"]
  node_route_runtime["Route runtime<br/>routing core<br/>[router.php]"]
  node_route_registry["Route registry<br/>route config<br/>[route-registry.php]"]
  node_feature_registry["Feature registry<br/>feature config"]
  node_features_boot["Features bootstrap<br/>feature wiring<br/>[features.php]"]
  node_feature_guards["Guards<br/>hardening<br/>[guards.php]"]
  node_feature_tokens["Design tokens<br/>theme supports<br/>[design-tokens.php]"]
  node_feature_admin["Admin UI<br/>admin feature"]
  node_feature_site["Site options<br/>site feature<br/>[site-options.php]"]
  node_feature_editor["Editor controls<br/>editor feature"]
  node_feature_support["Theme support<br/>support feature<br/>[theme-support.php]"]
  node_admin_settings["Settings page<br/>wp-admin page<br/>[settings-page.php]"]
  node_api_layer["API layer<br/>http api<br/>[api.php]"]
  node_scaffolder["Scaffolder<br/>generator<br/>[scaffolder.php]"]
  node_github_ops["GitHub ops<br/>integration<br/>[github.php]"]
  node_updater["Updater<br/>maintenance<br/>[updater.php]"]
  node_blockstudio_init["Blockstudio init<br/>bootstrap<br/>[init.php]"]
  node_site_editor["Site editor<br/>editor module<br/>[init.php]"]
  node_login_branding["Login branding<br/>ui module<br/>[init.php]"]
end

subgraph group_companion_app["Companion app"]
  node_template_blocks["Template blocks<br/>template modules<br/>[index.php]"]
  node_demo_plugin["Demo plugin<br/>companion plugin"]
  node_demo_templates["Demo blocks<br/>app templates<br/>[index.php]"]
end

subgraph group_supporting["Supporting assets"]
  node_config_json["Config JSON<br/>declarative config<br/>[examplepress.json]"]
  node_schema_doc["Config schema"]
  node_theme_json["Theme JSON<br/>editor config<br/>[theme.json]"]
  node_docs["Docs<br/>documentation<br/>[routing.md]"]
end

node_templates_index -->|"renders"| node_blockstudio_router
node_blockstudio_router -->|"resolves"| node_route_runtime
node_route_runtime -->|"looks up"| node_route_registry
node_route_runtime -->|"consults"| node_feature_registry
node_feature_registry -->|"reads"| node_config_json
node_feature_registry -.->|"filters"| node_theme_bootstrap
node_features_boot -->|"loads"| node_feature_guards
node_features_boot -->|"loads"| node_feature_tokens
node_features_boot -->|"loads"| node_feature_admin
node_features_boot -->|"loads"| node_feature_site
node_features_boot -->|"loads"| node_feature_editor
node_features_boot -->|"loads"| node_feature_support
node_theme_bootstrap -->|"boots"| node_blockstudio_init
node_blockstudio_init -->|"includes"| node_site_editor
node_blockstudio_init -->|"includes"| node_login_branding
node_route_runtime -->|"dispatches"| node_template_blocks
node_route_runtime -.->|"can defer to"| node_demo_plugin
node_demo_plugin -->|"owns"| node_demo_templates
node_admin_settings -->|"shows"| node_feature_registry
node_admin_settings -->|"uses"| node_api_layer
node_scaffolder -->|"generates"| node_demo_plugin
node_github_ops -->|"supports"| node_scaffolder
node_updater -->|"maintains"| node_demo_plugin
node_docs -.->|"documents"| node_route_runtime
node_docs -.->|"documents"| node_feature_registry
node_schema_doc -.->|"validates"| node_config_json
node_theme_json -->|"feeds"| node_feature_tokens

click node_templates_index "https://github.com/webmultipliers/examplepress-theme/blob/development/templates/index.html"
click node_blockstudio_router "https://github.com/webmultipliers/examplepress-theme/blob/development/blockstudio/router/index.php"
click node_theme_bootstrap "https://github.com/webmultipliers/examplepress-theme/blob/development/functions.php"
click node_route_runtime "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/router.php"
click node_route_registry "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/route-registry.php"
click node_feature_registry "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/feature-registry.php"
click node_features_boot "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features.php"
click node_feature_guards "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features/guards.php"
click node_feature_tokens "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features/design-tokens.php"
click node_feature_admin "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features/admin-customization.php"
click node_feature_site "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features/site-options.php"
click node_feature_editor "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features/editor-controls.php"
click node_feature_support "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features/theme-support.php"
click node_admin_settings "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/admin/settings-page.php"
click node_api_layer "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/api.php"
click node_scaffolder "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/scaffolder.php"
click node_github_ops "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/github.php"
click node_updater "https://github.com/webmultipliers/examplepress-theme/blob/development/inc/updater.php"
click node_blockstudio_init "https://github.com/webmultipliers/examplepress-theme/blob/development/blockstudio/init.php"
click node_template_blocks "https://github.com/webmultipliers/examplepress-theme/blob/development/blockstudio/templates/get-started/index.php"
click node_site_editor "https://github.com/webmultipliers/examplepress-theme/blob/development/blockstudio/site-editor/init.php"
click node_login_branding "https://github.com/webmultipliers/examplepress-theme/blob/development/blockstudio/login/init.php"
click node_demo_plugin "https://github.com/webmultipliers/examplepress-theme/blob/development/demo/examplepress-demo/examplepress-demo.php"
click node_demo_templates "https://github.com/webmultipliers/examplepress-theme/blob/development/demo/examplepress-demo/app/templates/front/index.php"
click node_config_json "https://github.com/webmultipliers/examplepress-theme/blob/development/examplepress.json"
click node_schema_doc "https://github.com/webmultipliers/examplepress-theme/blob/development/schema/examplepress-theme.json"
click node_theme_json "https://github.com/webmultipliers/examplepress-theme/blob/development/theme.json"
click node_docs "https://github.com/webmultipliers/examplepress-theme/blob/development/docs/routing.md"

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_templates_index,node_blockstudio_router,node_theme_bootstrap,node_route_runtime,node_route_registry,node_feature_registry,node_features_boot,node_feature_guards,node_feature_tokens,node_feature_admin,node_feature_site,node_feature_editor,node_feature_support,node_admin_settings,node_api_layer,node_scaffolder,node_github_ops,node_updater,node_blockstudio_init,node_site_editor,node_login_branding toneBlue
class node_template_blocks,node_demo_plugin,node_demo_templates toneAmber
class node_config_json,node_schema_doc,node_theme_json,node_docs toneMint
```

## Components

### Theme engine

Core WordPress theme runtime, configuration, admin, and hardening.

- [Front door](https://github.com/webmultipliers/examplepress-theme/blob/development/templates/index.html): entry template · Single public entry template that bypasses the normal WP hierarchy and hands requests to the router block. · `templates/index.html`
- [Router block](https://github.com/webmultipliers/examplepress-theme/blob/development/blockstudio/router/index.php): block module · Blockstudio router that resolves the current route and dispatches the matching template block. · `blockstudio/router/index.php`
- [Bootstrap](https://github.com/webmultipliers/examplepress-theme/blob/development/functions.php): php bootstrap · Theme and Blockstudio bootstrapping entrypoints. · `functions.php`
- [Route runtime](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/router.php): routing core · Coordinates current-route resolution, route data enrichment, and route resolution events. · `inc/router.php`
- [Route registry](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/route-registry.php): route config · Defines and looks up available routes and route metadata. · `inc/route-registry.php`
- [Feature registry](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/feature-registry.php): feature config · Central feature lookup and merge logic across filters, JSON config, and defaults. · `inc/feature-registry.php`
- [Features bootstrap](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features.php): feature wiring · Registers and wires the theme feature modules. · `inc/features.php`
- [Guards](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features/guards.php): hardening · Editor and template guards that prevent unsupported site mutations and bypasses. · `inc/features/guards.php`
- [Design tokens](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features/design-tokens.php): theme supports · Maps config-driven design settings into theme supports and theme.json behavior. · `inc/features/design-tokens.php`
- [Admin UI](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features/admin-customization.php): admin feature · Admin customization and settings surface for the platform. · `inc/features/admin-customization.php`
- [Site options](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features/site-options.php): site feature · Controls permalink and other site-model options exposed by the theme. · `inc/features/site-options.php`
- [Editor controls](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features/editor-controls.php): editor feature · Blocks, patterns, and editor capability restrictions. · `inc/features/editor-controls.php`
- [Theme support](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/features/theme-support.php): support feature · Theme support flags and editor-facing compatibility settings. · `inc/features/theme-support.php`
- [Settings page](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/admin/settings-page.php): wp-admin page · Read-only admin dashboard for resolved state, health, blocks, and build actions. · `inc/admin/settings-page.php`
- [API layer](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/api.php): http api · Programmatic endpoints for apps, connections, and demo management. · `inc/api.php`
- [Scaffolder](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/scaffolder.php): generator · Build and CLI support for generating companion plugins and related deployment scaffolds. · `inc/scaffolder.php`
- [GitHub ops](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/github.php): integration · GitHub App, key, and repository automation support. · `inc/github.php`
- [Updater](https://github.com/webmultipliers/examplepress-theme/blob/development/inc/updater.php): maintenance · Theme and companion lifecycle updates. · `inc/updater.php`
- [Blockstudio init](https://github.com/webmultipliers/examplepress-theme/blob/development/blockstudio/init.php): bootstrap · Initializes the theme-local Blockstudio modules. · `blockstudio/init.php`
- [Site editor](https://github.com/webmultipliers/examplepress-theme/blob/development/blockstudio/site-editor/init.php): editor module · Site-editor scripts and styles for Blockstudio editing experience. · `blockstudio/site-editor/init.php`
- [Login branding](https://github.com/webmultipliers/examplepress-theme/blob/development/blockstudio/login/init.php): ui module · Branded login assets and Blockstudio login integration. · `blockstudio/login/init.php`

### Companion app

Blockstudio template blocks and demo plugin that supply routed content.

- [Template blocks](https://github.com/webmultipliers/examplepress-theme/blob/development/blockstudio/templates/get-started/index.php): template modules · Local Blockstudio template blocks and reusable fallback content. · `blockstudio/templates/get-started/index.php`
- [Demo plugin](https://github.com/webmultipliers/examplepress-theme/blob/development/demo/examplepress-demo/examplepress-demo.php): companion plugin · Reference companion app that owns its own routes and page blocks. · `demo/examplepress-demo/examplepress-demo.php`
- [Demo blocks](https://github.com/webmultipliers/examplepress-theme/blob/development/demo/examplepress-demo/app/templates/front/index.php): app templates · Demo companion template blocks for front, single, and 404 routes. · `demo/examplepress-demo/app/templates/front/index.php`

### Supporting assets

Documentation, localization, schema, and release metadata.

- [Config JSON](https://github.com/webmultipliers/examplepress-theme/blob/development/examplepress.json): declarative config · Primary runtime configuration consumed by the feature and route registries. · `examplepress.json`
- [Config schema](https://github.com/webmultipliers/examplepress-theme/blob/development/schema/examplepress-theme.json): schema · Schema for the main theme configuration document. · `schema/examplepress-theme.json`
- [Theme JSON](https://github.com/webmultipliers/examplepress-theme/blob/development/theme.json): editor config · WordPress theme editor configuration and design-system boundary. · `theme.json`
- [Docs](https://github.com/webmultipliers/examplepress-theme/blob/development/docs/routing.md): documentation · Architecture and usage documentation for routing, guards, configuration, and companion plugins. · `docs/routing.md`

## Connections

- Front door → Router block: renders · The front door template contains only the router block.
- Router block → Route runtime: resolves · Router asks the runtime to resolve the active route.
- Route runtime → Route registry: looks up · Resolved routes are matched against the route registry.
- Route runtime → Feature registry: consults · Route behavior is shaped by feature lookup and merged config.
- Feature registry → Config JSON: reads · JSON config participates in feature resolution.
- Feature registry → Bootstrap: filters · PHP filters can override feature registration values.
- Features bootstrap → Guards: loads · Feature bootstrap wires guard modules.
- Features bootstrap → Design tokens: loads · Feature bootstrap wires design-token mapping.
- Features bootstrap → Admin UI: loads · Feature bootstrap wires admin customization.
- Features bootstrap → Site options: loads · Feature bootstrap wires site-option controls.
- Features bootstrap → Editor controls: loads · Feature bootstrap wires editor controls.
- Features bootstrap → Theme support: loads · Feature bootstrap wires theme support flags.
- Bootstrap → Blockstudio init: boots · Theme bootstrap initializes Blockstudio integration.
- Blockstudio init → Site editor: includes · Blockstudio init exposes site-editor assets.
- Blockstudio init → Login branding: includes · Blockstudio init exposes login branding assets.
- Route runtime → Template blocks: dispatches · Resolved routes render matching Blockstudio template blocks.
- Route runtime → Demo plugin: can defer to · Companion plugins may provide their own route logic.
- Demo plugin → Demo blocks: owns · Demo companion plugin ships its own routed page blocks.
- Settings page → Feature registry: shows · Admin settings surface resolved feature state.
- Settings page → API layer: uses · Settings page can trigger API-backed actions and checks.
- Scaffolder → Demo plugin: generates · Scaffolder creates companion plugin codebases.
- GitHub ops → Scaffolder: supports · GitHub automation underpins scaffolded repo workflows.
- Updater → Demo plugin: maintains · Updater manages theme and companion lifecycle.
- Docs → Route runtime: documents · Docs explain routing and runtime boundaries.
- Docs → Feature registry: documents · Docs describe feature merging and config priority.
- Config schema → Config JSON: validates · Schema documents the expected shape of the config file.
- Theme JSON → Design tokens: feeds · Theme JSON is the editor-side counterpart to design-token mapping.
