# use-novamira/novamira architecture

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

- Interactive diagram: https://gitdiagram.com/use-novamira/novamira
- Repository: https://github.com/use-novamira/novamira

## Overview

1. **What this repository is**
   Novamira is a WordPress plugin that exposes a **Model Context Protocol (MCP) server** so AI agents can operate on a WordPress site. The core architectural boundary is between the **AI agent / MCP client** and the **WordPress runtime**, with Novamira translating agent requests into WordPress-aware operations.

2. **Primary entry point**
   `novamira.php` is the plugin bootstrap. It likely wires together the major subsystems under `includes/`, registers WordPress hooks, and activates the MCP-facing capabilities. `composer.json` and `composer.lock` indicate PHP dependency management, while `stubs/wordpress-constants.php` supports development/static analysis against WordPress-specific globals/constants.

3. **Capability/ability layer**
   The `includes/abilities/` directory is the main execution surface. Each file corresponds to a discrete action such as reading/writing files, listing directories, editing or deleting files, enabling/disabling files, creating upload/admin links, running WP-CLI, and executing PHP. This is the most important subsystem for diagrams: it is the **operation layer** that bridges AI requests to privileged site actions.

4. **Execution model and trust boundary**
   Several abilities are intentionally high-trust: `execute-php.php`, `run-wp-cli.php`, and file mutation abilities imply direct server-side execution. `sandbox-loader.php`, `rest-shim.php`, and the various link-generation helpers suggest the plugin supports controlled entry points and remote invocation paths, likely to separate browser/admin interactions from backend execution. The key diagram boundary is **untrusted agent input → authenticated capability dispatch → WordPress/PHP/filesystem side effects**.

5. **Gutenberg editing workflow**
   `includes/abilities/gutenberg/` is a specialized subsystem for content editing/finalization in the block editor domain. It includes pending batch/change management, content read/write, finalization URL/runtime lookup, and a `rest.php` endpoint. This indicates a **multi-step content change pipeline** rather than direct one-shot edits: changes are staged, reviewed/finalized, and then applied through a runtime helper.

6. **Skills subsystem**
   `includes/skills/` is a separate abstraction layer for reusable AI skills. It has:
   - `abilities/` wrappers for skill CRUD operations,
   - `built-in/` markdown skill definitions,
   - `catalog.php`, `parser.php`, `sources.php`, and `prompts.php` for loading, parsing, and presenting skills,
   - `cpt.php` and `admin.php` for WordPress-backed storage and UI,
   - `templates/` for editing/list/upload flows.
   Architecturally, this is a **content/catalog subsystem** for organizing agent behaviors, distinct from the low-level action abilities.

7. **Admin and onboarding surfaces**
   The plugin includes multiple administrative pages and helpers: `admin-page.php`, `connect-page.php`, `instructions-admin.php`, `gutenberg-finalizer-admin.php`, `skills/admin.php`, and `pro-upsell.php`. `admin-access-link.php` and `upload-link.php` imply link-based onboarding or remote access bootstrap flows. These components provide the **human operator control plane** for setup, permissions, and guidance.

8. **Content storage and WordPress integration**
   `skills/cpt.php` suggests WordPress custom post type usage for persisting skill data, while the Gutenberg files interact with content editing state. The plugin is therefore not just an external server; it is deeply embedded in WordPress storage and admin APIs. Any architecture diagram should show **WordPress database/content APIs** as a central persistence layer for at least part of the plugin’s state.

9. **UI assets**
   `includes/assets/hub.css`, `hub.js`, and `sandbox.css`, plus `includes/skills/assets/admin.css`, support the plugin’s admin experiences. These are not core logic, but they matter because the admin/setup flows are likely delivered through WordPress-rendered pages with custom interaction logic for connecting, uploading, sandboxing, and managing skills.

10. **Update and release plumbing**
   `includes/updater.php`, `build/`, and `build-ignore` indicate release packaging and update support. This is a plugin-distribution concern rather than runtime behavior, but it matters for architecture because the codebase is intended to be installed and maintained as a WordPress plugin lifecycle artifact.

11. **Overall data flow**
   The dominant flow is: **AI agent/MCP client → Novamira MCP/ability dispatch → WordPress/PHP/filesystem/CLI/Gutenberg subsystems → persisted site state or file changes**. A secondary flow exists for **admin/operator setup → connect/upload/access links → plugin initialization and permissioned use**. The Gutenberg and skills subsystems add staged workflows on top of that core execution path.

12. **How to draw it**
   A good diagram would center on the WordPress plugin boundary, with separate boxes for:
   - MCP/entry layer,
   - ability execution layer,
   - Gutenberg staging/finalization,
   - skills catalog/admin/storage,
   - admin/onboarding UI,
   - filesystem/PHP/WP-CLI side effects.
   Emphasize that this is an **agent-control plugin for WordPress**, not a conventional standalone web app.

Main entry points: [`novamira.php`](https://github.com/use-novamira/novamira/blob/main/novamira.php) (novamira.php), [`includes/abilities/discover-abilities.php`](https://github.com/use-novamira/novamira/blob/main/includes/abilities/discover-abilities.php) (Discover abilities), [`includes/abilities/gutenberg/bootstrap.php`](https://github.com/use-novamira/novamira/blob/main/includes/abilities/gutenberg/bootstrap.php) (Gutenberg bootstrap), [`includes/skills/bootstrap.php`](https://github.com/use-novamira/novamira/blob/main/includes/skills/bootstrap.php) (Skills bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_plugin["Plugin core"]
  node_novamira_php["novamira.php<br/>bootstrap<br/>[novamira.php]"]
  node_helpers_php["Helpers<br/>[helpers.php]"]
  node_rest_shim_php["REST shim<br/>entry adapter<br/>[rest-shim.php]"]
  node_sandbox_loader_php["Sandbox loader<br/>execution loader<br/>[sandbox-loader.php]"]
end

subgraph group_group_abilities["Ability layer"]
  node_discover_abilities_php["Discover abilities<br/>capability registry"]
  node_file_ops["File ops<br/>filesystem abilities<br/>[read-file.php]"]
  node_execute_php["Execute PHP<br/>high-trust ability<br/>[execute-php.php]"]
  node_run_wp_cli["WP-CLI<br/>admin command ability<br/>[run-wp-cli.php]"]
end

subgraph group_group_gutenberg["Gutenberg flow"]
  node_gutenberg_bootstrap["Gutenberg bootstrap<br/>editing pipeline<br/>[bootstrap.php]"]
  node_pending_batches["Pending batches<br/>staging store"]
  node_content_io["Content IO<br/>content ops<br/>[get-content.php]"]
  node_finalization["Finalization<br/>release step"]
  node_gutenberg_rest["Gutenberg REST<br/>endpoint<br/>[rest.php]"]
end

subgraph group_group_skills["Skills subsystem"]
  node_skills_bootstrap["Skills bootstrap<br/>skills entry<br/>[bootstrap.php]"]
  node_skills_catalog["Skills catalog<br/>catalog/parser<br/>[catalog.php]"]
  node_skills_storage["Skills storage<br/>wp content store<br/>[cpt.php]"]
  node_skills_crud["Skills CRUD<br/>skill abilities<br/>[skill-get.php]"]
  node_skills_ui["Skills UI<br/>admin screens<br/>[admin.php]"]
end

subgraph group_group_admin["Admin surfaces"]
  node_access_links["Access links<br/>bootstrap abilities"]
  node_admin_pages["Admin pages<br/>control plane<br/>[admin-page.php]"]
  node_connect_page["Connect page<br/>onboarding<br/>[connect-page.php]"]
  node_gutenberg_admin["Gutenberg admin<br/>admin page"]
end

subgraph group_group_release["Release plumbing"]
  node_updater_php["Updater<br/>update support<br/>[updater.php]"]
  node_build_dir["Build files<br/>release assets"]
  node_wordpress_constants["WP constants<br/>stubs"]
end

node_novamira_php -->|"loads"| node_helpers_php
node_novamira_php -->|"routes"| node_rest_shim_php
node_novamira_php -->|"loads"| node_sandbox_loader_php
node_novamira_php -->|"registers"| node_discover_abilities_php
node_discover_abilities_php -->|"includes"| node_file_ops
node_discover_abilities_php -->|"includes"| node_execute_php
node_discover_abilities_php -->|"includes"| node_run_wp_cli
node_discover_abilities_php -->|"includes"| node_access_links
node_file_ops -->|"uses"| node_sandbox_loader_php
node_execute_php -->|"uses"| node_sandbox_loader_php
node_run_wp_cli -->|"invoked via"| node_rest_shim_php
node_novamira_php -->|"enables"| node_gutenberg_bootstrap
node_gutenberg_bootstrap -->|"manages"| node_pending_batches
node_gutenberg_bootstrap -->|"reads/writes"| node_content_io
node_gutenberg_bootstrap -->|"finalizes"| node_finalization
node_gutenberg_bootstrap -->|"exposes"| node_gutenberg_rest
node_novamira_php -->|"loads"| node_skills_bootstrap
node_skills_bootstrap -->|"builds"| node_skills_catalog
node_skills_bootstrap -->|"persists"| node_skills_storage
node_skills_bootstrap -->|"exposes"| node_skills_crud
node_skills_bootstrap -->|"renders"| node_skills_ui
node_skills_catalog -->|"reads"| node_skills_storage
node_skills_ui -->|"manages"| node_skills_storage
node_skills_ui -->|"embedded in"| node_admin_pages
node_novamira_php -->|"registers"| node_admin_pages
node_admin_pages -->|"includes"| node_connect_page
node_admin_pages -->|"includes"| node_gutenberg_admin
node_novamira_php -->|"loads"| node_updater_php
node_novamira_php -->|"packages"| node_build_dir
node_novamira_php -->|"uses"| node_wordpress_constants

click node_novamira_php "https://github.com/use-novamira/novamira/blob/main/novamira.php"
click node_helpers_php "https://github.com/use-novamira/novamira/blob/main/includes/helpers.php"
click node_rest_shim_php "https://github.com/use-novamira/novamira/blob/main/includes/rest-shim.php"
click node_sandbox_loader_php "https://github.com/use-novamira/novamira/blob/main/includes/sandbox-loader.php"
click node_discover_abilities_php "https://github.com/use-novamira/novamira/blob/main/includes/abilities/discover-abilities.php"
click node_file_ops "https://github.com/use-novamira/novamira/blob/main/includes/abilities/read-file.php"
click node_execute_php "https://github.com/use-novamira/novamira/blob/main/includes/abilities/execute-php.php"
click node_run_wp_cli "https://github.com/use-novamira/novamira/blob/main/includes/abilities/run-wp-cli.php"
click node_access_links "https://github.com/use-novamira/novamira/blob/main/includes/abilities/create-admin-access-link.php"
click node_gutenberg_bootstrap "https://github.com/use-novamira/novamira/blob/main/includes/abilities/gutenberg/bootstrap.php"
click node_pending_batches "https://github.com/use-novamira/novamira/blob/main/includes/abilities/gutenberg/create-pending-batch.php"
click node_content_io "https://github.com/use-novamira/novamira/blob/main/includes/abilities/gutenberg/get-content.php"
click node_finalization "https://github.com/use-novamira/novamira/blob/main/includes/abilities/gutenberg/get-finalization-url.php"
click node_gutenberg_rest "https://github.com/use-novamira/novamira/blob/main/includes/abilities/gutenberg/rest.php"
click node_skills_bootstrap "https://github.com/use-novamira/novamira/blob/main/includes/skills/bootstrap.php"
click node_skills_catalog "https://github.com/use-novamira/novamira/blob/main/includes/skills/catalog.php"
click node_skills_storage "https://github.com/use-novamira/novamira/blob/main/includes/skills/cpt.php"
click node_skills_crud "https://github.com/use-novamira/novamira/blob/main/includes/skills/abilities/skill-get.php"
click node_skills_ui "https://github.com/use-novamira/novamira/blob/main/includes/skills/admin.php"
click node_admin_pages "https://github.com/use-novamira/novamira/blob/main/includes/admin-page.php"
click node_connect_page "https://github.com/use-novamira/novamira/blob/main/includes/connect-page.php"
click node_gutenberg_admin "https://github.com/use-novamira/novamira/blob/main/includes/gutenberg-finalizer-admin.php"
click node_updater_php "https://github.com/use-novamira/novamira/blob/main/includes/updater.php"
click node_build_dir "https://github.com/use-novamira/novamira/tree/main/build/build"
click node_wordpress_constants "https://github.com/use-novamira/novamira/blob/main/stubs/wordpress-constants.php"

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_novamira_php,node_helpers_php,node_rest_shim_php,node_sandbox_loader_php toneBlue
class node_discover_abilities_php,node_file_ops,node_execute_php,node_run_wp_cli toneAmber
class node_gutenberg_bootstrap,node_pending_batches,node_content_io,node_finalization,node_gutenberg_rest toneMint
class node_skills_bootstrap,node_skills_catalog,node_skills_storage,node_skills_crud,node_skills_ui toneRose
class node_access_links,node_admin_pages,node_connect_page,node_gutenberg_admin toneIndigo
class node_updater_php,node_build_dir,node_wordpress_constants toneTeal
```

## Components

### Plugin core

Bootstrap and shared plugin infrastructure.

- [novamira.php](https://github.com/use-novamira/novamira/blob/main/novamira.php): bootstrap · Plugin entry point that wires the runtime together. · `novamira.php`
- [Helpers](https://github.com/use-novamira/novamira/blob/main/includes/helpers.php): shared helpers · Common utility functions used across the plugin. · `includes/helpers.php`
- [REST shim](https://github.com/use-novamira/novamira/blob/main/includes/rest-shim.php): entry adapter · Bridges external requests into plugin execution paths. · `includes/rest-shim.php`
- [Sandbox loader](https://github.com/use-novamira/novamira/blob/main/includes/sandbox-loader.php): execution loader · Loads the sandboxed execution environment. · `includes/sandbox-loader.php`

### Ability layer

Agent-facing operations that act on files, PHP, and WordPress.

- [Discover abilities](https://github.com/use-novamira/novamira/blob/main/includes/abilities/discover-abilities.php): capability registry · Finds and exposes available abilities to the MCP surface. · `includes/abilities/discover-abilities.php`
- [File ops](https://github.com/use-novamira/novamira/blob/main/includes/abilities/read-file.php): filesystem abilities · Read, write, edit, delete, list, enable, and disable file actions. · `includes/abilities/read-file.php`
- [Execute PHP](https://github.com/use-novamira/novamira/blob/main/includes/abilities/execute-php.php): high-trust ability · Runs server-side PHP code directly. · `includes/abilities/execute-php.php`
- [WP-CLI](https://github.com/use-novamira/novamira/blob/main/includes/abilities/run-wp-cli.php): admin command ability · Executes WordPress command-line operations. · `includes/abilities/run-wp-cli.php`

### Gutenberg flow

Staged content-editing pipeline for block editor operations.

- [Gutenberg bootstrap](https://github.com/use-novamira/novamira/blob/main/includes/abilities/gutenberg/bootstrap.php): editing pipeline · Initializes the staged Gutenberg content workflow. · `includes/abilities/gutenberg/bootstrap.php`
- [Pending batches](https://github.com/use-novamira/novamira/blob/main/includes/abilities/gutenberg/create-pending-batch.php): staging store · Creates, lists, reads, and deletes staged content batches and changes. · `includes/abilities/gutenberg/create-pending-batch.php`
- [Content IO](https://github.com/use-novamira/novamira/blob/main/includes/abilities/gutenberg/get-content.php): content ops · Reads and writes block-editor content during the staged flow. · `includes/abilities/gutenberg/get-content.php`
- [Finalization](https://github.com/use-novamira/novamira/blob/main/includes/abilities/gutenberg/get-finalization-url.php): release step · Builds finalization URLs and runtime helpers for applying changes. · `includes/abilities/gutenberg/get-finalization-url.php`
- [Gutenberg REST](https://github.com/use-novamira/novamira/blob/main/includes/abilities/gutenberg/rest.php): endpoint · REST endpoint for the Gutenberg editing pipeline. · `includes/abilities/gutenberg/rest.php`

### Skills subsystem

Catalog, storage, prompts, and CRUD for reusable AI skills.

- [Skills bootstrap](https://github.com/use-novamira/novamira/blob/main/includes/skills/bootstrap.php): skills entry · Initializes the skills subsystem. · `includes/skills/bootstrap.php`
- [Skills catalog](https://github.com/use-novamira/novamira/blob/main/includes/skills/catalog.php): catalog/parser · Loads, parses, and resolves skill sources and prompts. · `includes/skills/catalog.php`
- [Skills storage](https://github.com/use-novamira/novamira/blob/main/includes/skills/cpt.php): wp content store · Persists skills using WordPress-backed content structures. · `includes/skills/cpt.php`
- [Skills CRUD](https://github.com/use-novamira/novamira/blob/main/includes/skills/abilities/skill-get.php): skill abilities · Get, write, edit, and delete skill records. · `includes/skills/abilities/skill-get.php`
- [Skills UI](https://github.com/use-novamira/novamira/blob/main/includes/skills/admin.php): admin screens · Admin pages and templates for listing, editing, and uploading skills. · `includes/skills/admin.php`

### Admin surfaces

Operator pages, links, and onboarding flows.

- [Access links](https://github.com/use-novamira/novamira/blob/main/includes/abilities/create-admin-access-link.php): bootstrap abilities · Creates admin-access and upload links for remote setup. · `includes/abilities/create-admin-access-link.php`
- [Admin pages](https://github.com/use-novamira/novamira/blob/main/includes/admin-page.php): control plane · Plugin admin pages for connection, instructions, and finalizer setup. · `includes/admin-page.php`
- [Connect page](https://github.com/use-novamira/novamira/blob/main/includes/connect-page.php): onboarding · Setup flow for connecting the plugin to an operator or agent. · `includes/connect-page.php`
- [Gutenberg admin](https://github.com/use-novamira/novamira/blob/main/includes/gutenberg-finalizer-admin.php): admin page · Admin surface for configuring Gutenberg finalization. · `includes/gutenberg-finalizer-admin.php`

### Release plumbing

Packaging, updates, and development support files.

- [Updater](https://github.com/use-novamira/novamira/blob/main/includes/updater.php): update support · Plugin update and lifecycle support. · `includes/updater.php`
- [Build files](https://github.com/use-novamira/novamira/tree/main/build/build): release assets · Packaged build outputs and ignore rules. · `build/build`
- [WP constants](https://github.com/use-novamira/novamira/blob/main/stubs/wordpress-constants.php): stubs · Static-analysis stubs for WordPress globals and constants. · `stubs/wordpress-constants.php`

## Connections

- novamira.php → Helpers: loads · Bootstrap shares utilities across subsystems.
- novamira.php → REST shim: routes · Registers external request entry points.
- novamira.php → Sandbox loader: loads · Initializes controlled execution context.
- novamira.php → Discover abilities: registers · Exposes capability catalog to the MCP layer.
- Discover abilities → File ops: includes · Publishes filesystem and mutation abilities.
- Discover abilities → Execute PHP: includes · Publishes high-trust code execution.
- Discover abilities → WP-CLI: includes · Publishes CLI automation.
- Discover abilities → Access links: includes · Publishes onboarding link-generation actions.
- File ops → Sandbox loader: uses · File actions may execute inside the sandboxed loader path.
- Execute PHP → Sandbox loader: uses · Direct PHP execution is mediated by the execution loader.
- WP-CLI → REST shim: invoked via · Remote/HTTP-facing requests can reach command execution through the shim.
- novamira.php → Gutenberg bootstrap: enables · Bootstraps the staged Gutenberg workflow.
- Gutenberg bootstrap → Pending batches: manages · Creates and tracks staged changes.
- Gutenberg bootstrap → Content IO: reads/writes · Handles editor content access and mutation.
- Gutenberg bootstrap → Finalization: finalizes · Produces URLs and runtime context for applying changes.
- Gutenberg bootstrap → Gutenberg REST: exposes · Provides REST entry point for the editing pipeline.
- novamira.php → Skills bootstrap: loads · Initializes the reusable skills subsystem.
- Skills bootstrap → Skills catalog: builds · Loads and resolves skill definitions and prompts.
- Skills bootstrap → Skills storage: persists · Stores skills in WordPress-backed content.
- Skills bootstrap → Skills CRUD: exposes · Provides agent-facing skill operations.
- Skills bootstrap → Skills UI: renders · Serves the admin editing/list/upload experience.
- Skills catalog → Skills storage: reads · Catalog resolves stored skills from WP content.
- Skills UI → Skills storage: manages · Admin screens edit and upload persisted skills.
- Skills UI → Admin pages: embedded in · Skills UI is part of the broader operator control plane.
- novamira.php → Admin pages: registers · Main plugin bootstrap wires admin surfaces.
- Admin pages → Connect page: includes · Connection onboarding is one of the main admin views.
- Admin pages → Gutenberg admin: includes · Finalizer configuration is exposed in admin.
- novamira.php → Updater: loads · Adds update and lifecycle support.
- novamira.php → Build files: packages · Release artifacts are part of distribution.
- novamira.php → WP constants: uses · Development stubs support WordPress-specific globals.