Repository navigation
Document the plugin's architecture and developer-facing API surface - #1042
theaminulai wants to merge 2 commits into
Conversation
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.
|
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 If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. 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 Report✅ All modified and coverable lines are covered by tests. 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
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
@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. |
|
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! |
What?
Closes #1037
Rewrites
docs/ARCHITECTURE_OVERVIEW.mdfrom 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.mdanddocs/DEVELOPER_GUIDE.mdalready 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 runningregister()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:
ai.php→SDK_Overlay→Main::get_instance()→ the exactplugins_loaded/inithook sequence throughMain::initialize_features().Contracts\Feature,Abstract_Feature's enabled-state checks (and the naming collision between thewpai_features_enabledoption and thewpai_features_enabledfilter, which is easy to miss reading the code cold), and the full registration flow fromExperiments::init()throughwpai_features_initialized.wp_abilities_api_initregistration pattern with a runnable example, plus the separate gated-abilities registry.wp_get_connectors(), the AI Client SDK, and preferred-model fallback lists.ai/v1REST endpoint (there wasn't one anywhere before this).includes/helpers.phpfunctions that carry a stable@sincetag (the plugin's actual public PHP API), and a table of the filters/actions that make up the framework's stable extension surface.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 eachregister_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 relevantexperiments/*.mdpages).Changelog Entry