How webmultipliers/examplepress-theme works
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: features.php Features bootstrap · router.php Route runtime · feature-registry.php Feature registry · examplepress-demo.php Demo plugin
Components 28
Theme engine
Core WordPress theme runtime, configuration, admin, and hardening.
- Front door · Single public entry template that bypasses the normal WP hierarchy and hands requests to the router block.
templates/index.html - Router block · Blockstudio router that resolves the current route and dispatches the matching template block.
blockstudio/router/index.php - Bootstrap · Theme and Blockstudio bootstrapping entrypoints.
functions.php - Route runtime · Coordinates current-route resolution, route data enrichment, and route resolution events.
inc/router.php - Route registry · Defines and looks up available routes and route metadata.
inc/route-registry.php - Feature registry · Central feature lookup and merge logic across filters, JSON config, and defaults.
inc/feature-registry.php - Features bootstrap · Registers and wires the theme feature modules.
inc/features.php - Guards · Editor and template guards that prevent unsupported site mutations and bypasses.
inc/features/guards.php - Design tokens · Maps config-driven design settings into theme supports and theme.json behavior.
inc/features/design-tokens.php - Admin UI · Admin customization and settings surface for the platform.
inc/features/admin-customization.php - Site options · Controls permalink and other site-model options exposed by the theme.
inc/features/site-options.php - Editor controls · Blocks, patterns, and editor capability restrictions.
inc/features/editor-controls.php - Theme support · Theme support flags and editor-facing compatibility settings.
inc/features/theme-support.php - Settings page · Read-only admin dashboard for resolved state, health, blocks, and build actions.
inc/admin/settings-page.php - API layer · Programmatic endpoints for apps, connections, and demo management.
inc/api.php - Scaffolder · Build and CLI support for generating companion plugins and related deployment scaffolds.
inc/scaffolder.php - GitHub ops · GitHub App, key, and repository automation support.
inc/github.php - Updater · Theme and companion lifecycle updates.
inc/updater.php - Blockstudio init · Initializes the theme-local Blockstudio modules.
blockstudio/init.php - Site editor · Site-editor scripts and styles for Blockstudio editing experience.
blockstudio/site-editor/init.php - Login branding · 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 · Local Blockstudio template blocks and reusable fallback content.
blockstudio/templates/get-started/index.php - Demo plugin · Reference companion app that owns its own routes and page blocks.
demo/examplepress-demo/examplepress-demo.php - Demo blocks · 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 · Primary runtime configuration consumed by the feature and route registries.
examplepress.json - Config schema · Schema for the main theme configuration document.
schema/examplepress-theme.json - Theme JSON · WordPress theme editor configuration and design-system boundary.
theme.json - Docs · Architecture and usage documentation for routing, guards, configuration, and companion plugins.
docs/routing.md
Connections 27
- 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.