Skip to content

Document the plugin's architecture and developer-facing API surface - #1042

Closed
theaminulai wants to merge 2 commits into
WordPress:developfrom
theaminulai:docs/architecture-and-developer-api
Closed

theaminulai wants to merge 2 commits into
WordPress:developfrom
theaminulai:docs/architecture-and-developer-api

Conversation

@theaminulai

@theaminulai theaminulai commented Sep 17, 2026 •

Copy link
Copy Markdown
Member

What?

Closes #1037

Rewrites docs/ARCHITECTURE_OVERVIEW.md from a bare directory listing into an actual architecture guide, covering the whole plugin (bootstrap, the Feature/Experiment framework, Abilities, AI provider integration, cross-cutting modules, the REST API surface) plus a developer-facing API reference.

Why?

Both CONTRIBUTING.md and docs/DEVELOPER_GUIDE.md already link to Architecture Overview describing it as "Comprehensive guide to plugin architecture" — but the page itself was just an annotated directory tree with no prose explaining how the pieces actually fit together: how the plugin boots, how a Feature/Experiment gets from a class name to a running register() call, how Abilities get registered, or which functions and hooks are meant for external use versus internal-only. A contributor or integrator had to read source across a dozen files to reconstruct any of that.

How?

Added, without touching any code:

  • Bootstrap & Request Lifecycle — ai.php → SDK_Overlay → Main::get_instance() → the exact plugins_loaded/init hook sequence through Main::initialize_features().
  • The Feature/Experiment Framework — Contracts\Feature, Abstract_Feature's enabled-state checks (and the naming collision between the wpai_features_enabled option and the wpai_features_enabled filter, which is easy to miss reading the code cold), and the full registration flow from Experiments::init() through wpai_features_initialized.
  • The Abilities System — the wp_abilities_api_init registration pattern with a runnable example, plus the separate gated-abilities registry.
  • AI Provider Integration — connector discovery via wp_get_connectors(), the AI Client SDK, and preferred-model fallback lists.
  • Cross-Cutting Subsystems — a table covering Logging, Connector Approval, Key Encryption, Embeddings, Admin, REST, and CLI, plus a full inventory of every ai/v1 REST endpoint (there wasn't one anywhere before this).
  • Developer-Facing API Reference — a table of the includes/helpers.php functions that carry a stable @since tag (the plugin's actual public PHP API), and a table of the filters/actions that make up the framework's stable extension surface.
  • Directory Map — kept and extended the existing tree to include the directories it was missing (Admin, CLI, Connector_Approval, Contracts, Embeddings, REST, Vendor).

Every class, method, hook, and option name in the new content was checked directly against the current source (not written from a general impression of the codebase) — including tracing Main::initialize_features(), Features\Loader, Abstract_Feature, Settings_Registration, and each register_rest_route() call to confirm namespaces, hook names, and call order. Content already covered in depth elsewhere — the Developer Guide's experiment-building tutorial, docs/experiments/experiment-framework.md, docs/experiments/multi-provider-support.md, and each experiment's own doc page — is linked rather than duplicated, so this doesn't compete with or drift from those pages.

Testing Instructions

Documentation-only change; no code paths affected. Please review for accuracy and check that the internal links resolve (all verified to exist at review time: DEVELOPER_GUIDE.md, FEATURE_EXPERIMENT_LIFECYCLE.md, FEATURED_CONNECTORS.md, PROMPT_CUSTOMIZATION.md, TESTING.md, TESTING_REST_API.md, admin/settings-import-export.md, and the relevant experiments/*.md pages).

Changelog Entry

Developer - Rewrote Architecture Overview into a full guide covering the plugin's bootstrap, Feature/Experiment framework, Abilities system, AI provider integration, cross-cutting modules, REST API inventory, and developer-facing API/hook reference.

Open WordPress Playground Preview

Architecture Overview was a bare directory listing with no explanation
of how the plugin actually works, despite both CONTRIBUTING.md and the
Developer Guide already describing it as a "comprehensive guide to
plugin architecture."

Expands it to cover the bootstrap sequence (ai.php through
Main::initialize_features()), the Feature/Experiment registration flow
and its enabled-state checks, the Abilities registration pattern, how
AI provider integration and connector discovery work, a table of the
cross-cutting modules (Logging, Connector Approval, Key Encryption,
Embeddings, Admin, REST, CLI) and the full ai/v1 REST endpoint
inventory, and a developer-facing API reference table of the
helpers.php functions and filters/actions intended for external use.

Every class, method, hook, and option name cited was verified directly
against the current source rather than summarized from memory. Detail
already covered in depth elsewhere (the Developer Guide's experiment
tutorial, and each experiment's own docs/experiments/*.md page) is
linked rather than repeated.

Closes WordPress#1037.
@theaminulai
theaminulai requested a review from a team September 17, 2026 15:05
@github-actions

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: theaminulai <theaminuldev@git.wordpress.org>
Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

This commit fixes the indentation in the directory tree shown in docs/ARCHITECTURE_OVERVIEW.md so the architecture overview renders consistently and is easier to read. It is a documentation-only cleanup with no functional changes.
@codecov

codecov Bot commented Sep 17, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.23%. Comparing base (123ab42) to head (9170860).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files
@@            Coverage Diff             @@
##             develop    #1042   +/-   ##
==========================================
  Coverage      80.23%   80.23%           
  Complexity      2998     2998           
==========================================
  Files            124      124           
  Lines          11978    11978           
==========================================
  Hits            9611     9611           
  Misses          2367     2367           
Flag Coverage Δ
unit 80.23% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@jeffpaul

Copy link
Copy Markdown
Member

@theaminulai apologies for the incomplete issue, but this was supposed to help specifically with the embeddings support, so probably best to close out this PR and open one that documents embeddings specifically.

@theaminulai

Copy link
Copy Markdown
Member Author

Thanks for the clarification, @jeffpaul .

That makes sense. I’ll close this PR and open a new one focused specifically on documenting the Embeddings support, including its architecture and developer-facing API.

I’ll make sure the new PR is scoped accordingly. Thanks for pointing me in the right direction!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document the architecture and developer-facing APIs for Embeddings support

3 participants