Skip to content

ADR-0001 — WPDoctor Architecture v1.0

Repository: agent-adk-wpdoctor
Version: 1.0
Status: Accepted / Initial implementation baseline
Date: 2026-09-08
Product codename: WPDoctor

1. Decision Summary

WPDoctor will be implemented as a provider-agnostic autonomous SRE runtime specialized in WordPress estates.

The product will manage the complete technical stack required to operate WordPress reliably:

  • Linux
  • networking and filesystem basics
  • web servers
  • PHP / PHP-FPM / OPcache
  • MySQL / MariaDB
  • Redis
  • WordPress
  • WooCommerce
  • updates
  • backups and restore workflows
  • performance
  • incident investigation
  • remediation
  • security operations

The initial integration boundary with customer infrastructure will be SSH.

WPDoctor MUST NOT require a specific hosting provider, hosting control panel or orchestration platform.

The main architectural flow is:

User
  ↓
WPDoctor SRE Manager
  ↓
Specialists
  ↓
Operations
  ↓
Skills
  ↓
Policy Engine
  ↓
Deterministic Tools / Adapters
  ↓
SSH
  ↓
Customer Infrastructure

The external user interacts with one WPDoctor SRE identity.

Specialist agents are internal implementation components and MUST NOT require the user to choose between Linux, WordPress, PHP, database or performance profiles.

2. Context

Existing AI coding and shell agents can execute commands on Linux servers, but unrestricted shell access is not sufficient for a safe commercial SRE product.

A commercial WordPress SRE system must additionally provide:

  • environment discovery;
  • understanding of infrastructure topology;
  • persistent tenant-specific knowledge;
  • deterministic operational workflows;
  • execution policies;
  • approval gates;
  • audit trails;
  • incident state;
  • rollback awareness;
  • reusable WordPress operational knowledge;
  • safe multi-server operation;
  • isolation between customers;
  • evaluation against known incidents.

WPDoctor is intended to operate WordPress infrastructure independently of where it is hosted.

Examples include:

  • generic VPS;
  • bare metal;
  • OVH;
  • Hetzner;
  • AWS;
  • DigitalOcean;
  • customer-owned virtualization;
  • Docker hosts;
  • hosting panels through future adapters;
  • Wetopi infrastructure through a separate private adapter.

Provider APIs MAY be added later as optimizations.

They MUST NOT become mandatory dependencies of the core architecture.

3. Product Model

The commercial unit is:

1 Customer
    ↓
1 WPDoctor tenant
    ↓
1 logical WPDoctor SRE identity
    ↓
N servers
    ↓
N WordPress installations

WPDoctor is NOT designed as:

1 WordPress site = 1 autonomous agent

and NOT as:

1 technical specialty = 1 user-facing profile

A customer with 30 servers and 500 WordPress installations may therefore have a single WPDoctor tenant responsible for the complete estate.

4. Tenant Runtime Decision

For the initial product architecture:

1 tenant = 1 isolated WPDoctor runtime

A runtime MAY be deployed as:

Docker container

during development and early commercial deployments.

A Kubernetes implementation MAY later use:

namespace per tenant

or equivalent isolation.

Per-tenant runtime isolation is chosen initially because WPDoctor handles highly privileged customer infrastructure.

The runtime boundary isolates:

  • sessions;
  • workspace;
  • SSH credentials;
  • inventory;
  • tenant memory;
  • policy;
  • incidents;
  • temporary files;
  • tool execution;
  • audit information.

This does NOT imply that every supporting platform service must permanently remain physically duplicated per tenant.

Shared control-plane services MAY be introduced later if tenant isolation is cryptographically and logically preserved.

5. Agent Model

WPDoctor exposes one principal agent:

WPDoctor SRE Manager

Internally it MAY delegate to specialist agents.

Initial specialist domains:

Linux Specialist
Webserver Specialist
PHP Specialist
Database Specialist
WordPress Specialist
WooCommerce Specialist
Performance Specialist
Security Specialist
Update / Lifecycle Specialist
Backup / Restore Specialist
Reviewer
Executor

Specialists SHOULD be invoked based on task requirements.

They MUST NOT independently own customer infrastructure state.

Shared canonical state belongs to the runtime.

6. Canonical SRE Workflow

All operational requests SHOULD converge on the following lifecycle:

DISCOVER
   ↓
INVESTIGATE
   ↓
DIAGNOSE
   ↓
PLAN
   ↓
POLICY CHECK
   ↓
APPROVE — when required
   ↓
EXECUTE
   ↓
VALIDATE
   ↓
LEARN

This extends the existing SRE pattern:

investigate → diagnose → plan → execute

with explicit:

  • environment discovery;
  • policy enforcement;
  • validation;
  • memory learning.

No incident is considered successfully resolved merely because a command returned exit status 0.

Post-execution validation is mandatory for mutating operations.

7. Architecture Layers

7.1 Manager

Responsibilities:

  • understand user intent;
  • identify affected tenant/server/site;
  • coordinate investigation;
  • select specialists;
  • collect evidence;
  • formulate diagnosis;
  • choose operations;
  • produce plans;
  • request approval when needed.

The Manager SHOULD NOT implement low-level shell logic.

7.2 Specialists

Specialists perform domain reasoning.

Examples:

Linux Specialist

  • CPU pressure;
  • RAM pressure;
  • OOM;
  • filesystem;
  • IO;
  • processes;
  • load;
  • network basics;
  • systemd;
  • cron.

PHP Specialist

  • PHP-FPM saturation;
  • pm.max_children;
  • slowlog;
  • OPcache;
  • configuration;
  • process crashes.

Database Specialist

  • slow queries;
  • locks;
  • connections;
  • buffer pressure;
  • table/index analysis;
  • WordPress-specific query behavior.

WordPress Specialist

  • plugins;
  • themes;
  • WP-CLI;
  • cron;
  • options;
  • transients;
  • autoload;
  • object cache;
  • updates;
  • configuration.

WooCommerce Specialist

  • Action Scheduler;
  • checkout performance;
  • order jobs;
  • imports;
  • scheduled jobs;
  • WooCommerce database behavior.

8. Operations, Skills and Tools

The following distinction is mandatory.

Operation

An Operation represents a complete SRE outcome.

Examples:

wordpress-performance-audit
safe-plugin-update
investigate-502
investigate-high-load
restore-wordpress
tune-php-fpm

Operations can compose multiple skills.

Skill

A Skill represents reusable technical knowledge or procedure.

Examples:

inspect-linux-load
inspect-php-fpm
inspect-wp-cron
inspect-autoload
find-wordpress-installations
check-mysql-connections

Tool

A Tool performs a bounded technical action.

Examples:

ssh_exec
read_file
service_status
wp_cli
mysql_query
get_processes
get_disk_usage

The hierarchy is:

Agent
  ↓
Operation
  ↓
Skills
  ↓
Policy
  ↓
Tools
  ↓
Adapters
  ↓
SSH

9. Shell Policy

WPDoctor MUST NOT be designed as:

LLM + unrestricted root shell

The preferred execution model is:

LLM
 ↓
typed operation
 ↓
policy
 ↓
deterministic tool
 ↓
known command
 ↓
SSH

A free-form shell capability MAY exist as a controlled escape hatch.

It MUST:

  • be disabled by default for autonomous execution;
  • require elevated policy;
  • be fully audited;
  • never silently bypass operation policies.

10. SSH Boundary

SSH is the minimum common denominator for MVP infrastructure integration.

WPDoctor MUST support:

  • SSH key authentication;
  • mandatory host-key verification;
  • connection timeout;
  • command timeout;
  • exit status;
  • stdout/stderr separation;
  • privilege discovery;
  • sudo capability discovery;
  • safe argument handling;
  • structured audit.

Root access MUST NOT be required by default.

Three conceptual access levels exist:

READONLY
OPERATOR
ADMIN

OPERATOR with constrained sudo SHOULD be the recommended production configuration.

11. Discovery

Before operating a new host, WPDoctor MUST construct a host inventory.

Example:

host:
  id: server-01
  hostname: wp-prod-01
  os:
    family: debian
    distribution: ubuntu
    version: "24.04"

init:
  systemd: true

web:
  nginx: true
  apache: false

php:
  versions:
    - "8.3"
  fpm: true

database:
  mysql: false
  mariadb: true

cache:
  redis: true

wordpress:
  wp_cli: true
  installations:
    - domain: shop.example.com
      path: /var/www/shop.example.com

Discovery MUST distinguish:

verified facts
inferred facts
unknown facts

Discovery information MUST carry freshness metadata.

Mutating operations MUST revalidate critical capabilities before execution.

12. Capability Model

Operations MUST declare requirements.

Example:

operation: restart_php_fpm

requires:
  - php.fpm
  - privilege.service_restart

Example:

operation: safe_wordpress_plugin_update

requires:
  - wordpress.wp_cli
  - filesystem.write
  - wordpress.backup_or_rollback

An operation MUST NOT run when mandatory capabilities are absent.

The agent may instead:

  • collect additional information;
  • request credentials;
  • offer another procedure;
  • explain why execution is unavailable.

13. Environment Adapters

Core operations MUST avoid hardcoding hosting-specific commands.

Example abstraction:

restart_php(site)

may resolve to:

systemd adapter
Docker adapter
Plesk adapter
cPanel adapter
Wetopi adapter

Initial adapters:

linux-systemd
nginx
apache
php-fpm
mysql-mariadb
redis
wordpress-wpcli

Future adapters MAY include:

Docker
LiteSpeed
OpenLiteSpeed
Plesk
cPanel
CloudPanel
RunCloud
GridPane
Kubernetes
Wetopi

Wetopi-specific behavior MUST live outside the provider-agnostic core.

14. Memory Architecture

WPDoctor uses three fundamentally different information planes.

GLOBAL KNOWLEDGE
TENANT MEMORY
LIVE STATE

They MUST NOT be conflated.

14.1 Global Knowledge

Shared knowledge includes:

  • WordPress operational knowledge;
  • PHP knowledge;
  • Linux knowledge;
  • runbooks;
  • known failure patterns;
  • product skills;
  • product documentation;
  • generic remediation practices.

This knowledge belongs to the WPDoctor product.

It MAY be represented through:

  • repository Markdown;
  • skills;
  • wiki knowledge;
  • indexed documentation.

14.2 Tenant Memory

Tenant memory contains durable knowledge learned about a customer environment.

Hindsight will be the initial long-term memory backend.

Examples:

server01 hosts 17 WordPress installations
MariaDB restart requires approval
shop.example.com performs ERP imports at 02:00
plugin X must never be automatically upgraded
srv03 becomes IO constrained during backups
incident INC-382 was caused by PHP-FPM max_children

Tenant memory MUST be isolated per customer.

Cross-tenant retrieval is forbidden.

14.3 Live State

Live state includes:

current CPU usage
current free RAM
current disk usage
current PHP worker count
current database connections
current process list

Live state SHOULD NOT become long-term memory by default.

It must normally be queried again.

Memory MAY retain higher-level observations derived from historical state.

Example:

server01 repeatedly experiences IO contention during nightly backups

15. Learn Phase

Successful or failed operations MAY produce candidate memories.

The LEARN phase asks:

What did this incident teach us that will remain useful later?

Candidate memories SHOULD contain:

tenant:
subject:
fact:
scope:
source:
confidence:
observed_at:
evidence:

Secrets MUST NEVER be stored in semantic memory.

16. Memory Curator

WPDoctor will include a memory curation process.

Memory states:

ACTIVE
STALE
DELETE_CANDIDATE

The curator MAY:

  • merge duplicates;
  • detect contradictions;
  • decay confidence;
  • mark obsolete facts;
  • promote repeatedly verified facts;
  • mark unused low-confidence memories as deletion candidates.

Candidate deletion SHOULD use a grace period.

Automatic immediate semantic deletion is discouraged.

Explicit user policies and human instructions MUST outrank inferred memories.

Authority precedence:

policy
  >
explicit human instruction
  >
verified environment fact
  >
high-confidence historical memory
  >
inference
  >
LLM hypothesis

17. Policy Engine

WPDoctor requires an execution policy separate from the LLM.

Minimum modes:

READONLY
COPILOT
AUTOPILOT

READONLY

Allowed:

  • inspect;
  • query;
  • diagnose;
  • report.

No mutation.

COPILOT

Allowed:

  • automatic investigation;
  • automatic diagnosis;
  • plan generation.

Mutations require approval.

AUTOPILOT

Only explicitly allowlisted low-risk operations may execute autonomously.

High-risk and destructive operations continue to require approval.

Policy decisions MUST be deterministic and auditable.

18. Risk Classification

Operations SHOULD declare risk:

R0 = read-only
R1 = reversible low-risk mutation
R2 = service-impacting mutation
R3 = high-risk/destructive

Examples:

read nginx log              R0
clear WordPress cache       R1
restart PHP-FPM             R2
upgrade PHP version         R2
DROP DATABASE               R3
delete WordPress files      R3

R3 operations MUST NOT execute autonomously in v1.

19. Audit Trail

Every relevant step MUST be reconstructable.

Example:

13:01 user reported slow checkout
13:01 incident INC-104 created
13:02 host resolved to srv03
13:02 SSH connection established
13:03 CPU inspected
13:03 PHP-FPM inspected
13:04 MySQL slow queries inspected
13:05 Action Scheduler backlog detected
13:06 diagnosis generated
13:07 remediation plan generated
13:08 human approval received
13:08 operation executed
13:09 checkout test successful
13:09 incident resolved
13:10 durable memory candidate generated

Audit records MUST contain:

  • tenant;
  • actor;
  • timestamp;
  • incident;
  • operation;
  • tool;
  • target;
  • policy decision;
  • approval;
  • result.

Secrets MUST be redacted.

20. Prompt Injection / Untrusted Data

Output obtained from remote infrastructure MUST be treated as untrusted data.

Examples:

  • log entries;
  • WordPress content;
  • plugin files;
  • comments;
  • database content;
  • README files;
  • web responses.

Remote content MUST NOT be interpreted as trusted instructions to WPDoctor.

The runtime MUST clearly separate:

system instructions
operator instructions
remote evidence

This is a mandatory security requirement.

21. Incident Model

An incident SHOULD contain:

id:
tenant:
status:
reported_symptom:
targets:
timeline:
evidence:
hypotheses:
diagnosis:
confidence:
plan:
approvals:
executions:
validation:
resolution:
memories_created:

Suggested states:

OPEN
INVESTIGATING
DIAGNOSED
PLANNED
WAITING_APPROVAL
EXECUTING
VALIDATING
RESOLVED
FAILED
CANCELLED

22. Initial Supported Environment

MVP does NOT mean universal stack compatibility.

Initial guaranteed target:

Linux:
  Debian / Ubuntu

Init:
  systemd

Web:
  nginx
  Apache

PHP:
  PHP-FPM

Database:
  MySQL
  MariaDB

WordPress:
  standard WordPress
  WP-CLI

Cache:
  Redis where present

WooCommerce-specific diagnosis is included where feasible.

Docker support is targeted immediately after the base host implementation unless required earlier by pilot environments.

23. MVP Operations

Initial operational set SHOULD include at minimum:

discover-host
discover-wordpress-sites
host-health
wordpress-health

investigate-high-load
investigate-memory-pressure
investigate-disk-space
investigate-502
investigate-504
investigate-php-fatal
investigate-php-fpm-saturation
investigate-slow-wordpress
investigate-slow-mysql
investigate-wp-cron
investigate-plugin-conflict

wordpress-performance-audit

safe-plugin-update
safe-core-update
cache-purge

backup-check

Mutating update operations MUST refuse autonomous execution when rollback capability is unavailable.

24. Performance Investigation

Performance MUST be treated as a cross-layer operation.

WordPress performance
         │
 ┌───────┼────────┐
 ▼       ▼        ▼
Linux   PHP       DB
 │       │        │
 └───────┼────────┘
         ▼
      WordPress
         │
         ▼
     WooCommerce

The investigation MUST avoid assuming that application slowness originates in WordPress itself.

25. Observability

WPDoctor SHOULD expose OpenTelemetry-compatible telemetry.

Minimum observability:

  • operation duration;
  • specialist calls;
  • tool calls;
  • SSH execution duration;
  • errors;
  • approval wait;
  • token/model usage;
  • incident duration;
  • diagnosis confidence;
  • operation success/failure.

Model/provider observability SHOULD remain independent of customer infrastructure monitoring.

26. Evaluations

Evals are a first-class product asset.

An eval case SHOULD represent an incident.

Example:

id: php-fpm-maxchildren-001

symptoms:
  - intermittent 502
  - nginx upstream timeout

environment:
  nginx: true
  php_fpm: true

root_cause:
  php_fpm_max_children_exhausted

expected_investigation:
  - inspect nginx errors
  - inspect php-fpm status/logs
  - inspect process saturation

forbidden_actions:
  - reboot_host
  - delete_cache_directory

acceptable_resolution:
  - tune pool after evidence
  - restart pool with appropriate policy

The eval framework MUST test:

  • diagnosis;
  • evidence collection;
  • unsafe actions;
  • unnecessary actions;
  • successful remediation;
  • policy compliance.

27. Wetopi Relationship

Wetopi is a dogfooding environment.

The core repo MUST NOT assume:

  • Wetopi paths;
  • Wetopi container names;
  • Wetopi APIs;
  • Ceph;
  • Kubernetes;
  • Wetopi-specific SSH topology;
  • Wetopi-specific networking.

Wetopi integrations belong in:

private adapter

or a separate integration repository/package.

Generic operational knowledge learned at Wetopi MAY be promoted into the WPDoctor core when it is provider-independent.

28. Non-Goals for v1

The following are explicitly outside the initial MVP:

  • replacing a full monitoring platform;
  • universal control-panel support;
  • billing;
  • CRM;
  • customer-facing SaaS dashboard;
  • support for every Linux distribution;
  • autonomous destructive actions;
  • unrestricted autonomous root shell;
  • arbitrary Kubernetes SRE;
  • generic cloud infrastructure management unrelated to WordPress;
  • automatic malware remediation without explicit controls;
  • cross-tenant learning from private tenant data.

29. Alternatives Considered

One agent per WordPress installation

Rejected.

Reasons:

  • duplicates context;
  • poor understanding of shared host resources;
  • inefficient;
  • does not model the infrastructure estate.

One profile per technical domain

Rejected as user-facing architecture.

The user should not need to decide whether an issue belongs to Linux, PHP or WordPress.

Specialists remain internal.

Provider-specific APIs as primary integration

Rejected.

They reduce addressable market and couple WPDoctor to hosting providers.

Provider APIs may be optional accelerators.

Unrestricted shell agent

Rejected as primary execution architecture.

It does not provide sufficient deterministic safety, auditing or policy enforcement.

Shared tenant memory

Rejected.

Customer-specific operational knowledge requires strict isolation.

30. Consequences

Positive:

  • works across hosting providers;
  • clear commercial positioning;
  • customer does not migrate hosting;
  • supports whole-stack diagnosis;
  • infrastructure knowledge improves over time;
  • safer than generic shell agents;
  • scales from one host to entire WordPress estates;
  • Wetopi can dogfood the generic product.

Costs:

  • discovery must be robust;
  • adapters require maintenance;
  • policy design becomes core product engineering;
  • operation/eval library requires continuous investment;
  • memory quality requires curation;
  • SSH credential management becomes security-critical.

31. Initial Technology Decisions

Preferred implementation baseline:

Python 3.12+
Google ADK
Pydantic v2
async SSH client
pytest
OpenTelemetry
Hindsight adapter
structured JSON logging

Exact package versions MUST be pinned in the repository.

Domain models SHOULD be typed.

Operation and tool inputs MUST use schemas rather than arbitrary dictionaries where practical.

32. Repository

Canonical repository name:

agent-adk-wpdoctor

No alternative repository name should be introduced without a new architectural decision.

33. Rollout

Phase 0:

runtime scaffold
domain contracts
SSH connector
inventory
policy skeleton
audit skeleton

Phase 1:

discovery
read-only host operations
WordPress discovery
basic incident workflow

Phase 2:

Linux/PHP/MySQL/WordPress specialists
diagnostic operations
performance investigation

Phase 3:

controlled mutations
approval flow
validation
rollback-aware operations

Phase 4:

Hindsight
LEARN phase
memory curation
historical incident recall

Phase 5:

Wetopi dogfooding
eval corpus
pilot customer

34. Acceptance Criteria for Architecture v1

Architecture v1 is considered implemented when one tenant runtime can:

  1. connect securely to a new Linux host using SSH;
  2. verify the SSH host identity;
  3. discover supported host capabilities;
  4. find WordPress installations;
  5. build a typed inventory;
  6. manage multiple hosts and sites;
  7. investigate at least:
  8. high load;
  9. disk pressure;
  10. HTTP 502;
  11. PHP fatal;
  12. PHP-FPM saturation;
  13. slow WordPress;
  14. correlate evidence across Linux, PHP, database and WordPress;
  15. produce a structured diagnosis with evidence and confidence;
  16. generate a structured execution plan;
  17. enforce READONLY/COPILOT/AUTOPILOT policies;
  18. prevent forbidden operations regardless of LLM instruction;
  19. execute an approved safe mutation;
  20. validate the result;
  21. create a complete audit trail;
  22. persist useful tenant-specific operational knowledge in Hindsight;
  23. retrieve relevant prior knowledge during a later incident;
  24. maintain complete memory separation between tenants;
  25. pass the initial incident eval suite;
  26. operate without any dependency on Wetopi-specific infrastructure.

35. Final Decision

Proceed with implementation of agent-adk-wpdoctor.

The foundational design principle is:

WPDoctor is not an LLM with SSH access. It is a WordPress-specialized SRE system in which LLM reasoning is constrained by operations, capabilities, policy, evidence, validation, auditing and persistent tenant knowledge.

This ADR is the architectural authority for WPDoctor v1.0.