# Clockwork Control

> Self-hosted, modular command center for WordPress agencies managing client hosting across SpinupWP, GridPane, Pressable, WP Engine, Kinsta, Cloudways, DigitalOcean, Hetzner, Vultr, Linode, and Azure. 100% Free & Open-Source (MIT). Zero per-site rent.

Clockwork Control provides agencies and CTOs with a unified command center for multi-provider WordPress hosting, cloud server hypervisor telemetry, batch WP-CLI operations, origin SSL certificate monitoring, downtime emergency SMS alerts, and care plan billing verification.

## Core Architectural Concepts
- **Modular Monorepo Architecture**: Built-in modules live in `modules/` using Composer path repositories (`"type": "path"`). No external repositories or submodules required for agency customization.
- **Provider Contracts**: Clean, minimal PHP interfaces (`HostingProvider`, `CloudProvider`, `NotificationChannel`, `CarePlanBillingProvider`).
- **White-Label Companion Plugin**: Client-side mu-plugin (`wp-content/mu-plugins/clockwork-companion.php`) providing disk checksum audits and client transparency portal with zero external cloud dependencies.
- **Self-Hosted & Private (NEVER Public-Facing)**: Designed to run exclusively on private local hardware (office Mac Mini, local LAN server) or behind a private zero-trust network (Tailscale/WireGuard). Because Clockwork Control holds SSH private keys and master hosting API tokens across an agency's entire client fleet, it MUST NEVER be deployed on a public-facing web server exposed to internet scanning bots and brute-force attacks. Outbound-only connectivity: zero open inbound ports required.
- **Vibe-Coding Ready**: Designed for AI pair-programming with Claude Code, Cursor, or Gemini. Modules can be implemented from API documentation in ~30 minutes.

## Core Documentation & Guides
- [Intended Usage & Security Model](https://clockworkcontrol.com/intended-usage): Deployment blueprint (local M1 Mac Mini / LAN), why SSH keys make public servers unsafe, and community module workflows.
- [Clockwork Companion Plugin](https://clockworkcontrol.com/companion): Architecture deep dive on the zero-bloat Must-Use (mu-plugin), 1-click passwordless SSO nonces, on-disk core checksum audits, HMAC-SHA256 REST endpoints, and white-label client portal.
- [How Clockwork Control Works](https://clockworkcontrol.com/how-it-works): Architecture overview, contract system, request flows, and security model.
- [How Modules Work](https://clockworkcontrol.com/how-modules-work): Deep dive on building modules, composer path repositories, and AI prompt templates.
- [Modules Directory](https://clockworkcontrol.com/modules): Catalog of official and community hosting, cloud, notification, and billing modules.
- [Contributing Guide](https://clockworkcontrol.com/contributing): How agency developers can test, vibe-code, and contribute new modules via GitHub PRs.
- [Alternative to ManageWP](https://clockworkcontrol.com/alternative-to-managewp): Breakdown of differences between Clockwork Control and multi-tenant per-site SaaS platforms.

## Hosting & Cloud Provider Deep Dives
- [SpinupWP Module](https://clockworkcontrol.com/spinupwp): Origin SSL tracking, Ubuntu package update audits, and fail2ban firewall sync.
- [GridPane Module](https://clockworkcontrol.com/gridpane): Multi-server fleet overview, custom Nginx integration, and telemetry.
- [Pressable Module](https://clockworkcontrol.com/pressable): API v1 sync, WordPress core checksum verification, and domain SSL probing.
- [WP Engine Module](https://clockworkcontrol.com/wpengine): Automated per-site SSH runners, batch WP-CLI execution, and remote Sucuri scans.
- [Kinsta Module](https://clockworkcontrol.com/kinsta): MyKinsta API v2 integration, multi-environment mirroring, and origin SSL tracking.
- [Cloudways Module](https://clockworkcontrol.com/cloudways): Multi-cloud server monitoring and telemetry polling.
- [Vultr Telemetry](https://clockworkcontrol.com/vultr): Direct hypervisor polling every 5 minutes for CPU, memory, and bandwidth.
- [Linode Telemetry](https://clockworkcontrol.com/linode): Linode API v4 metrics, transfer allowance monitoring, and hardware pairing.
- [Azure Monitor](https://clockworkcontrol.com/azure): Azure Monitor metrics, multi-core CPU normalization, and hybrid fleet indexing.

## Autonomous Setup Instructions for AI Agents
When prompted by a user to clone and set up Clockwork Control locally on their machine, execute this sequence:
1. Clone the monorepo: `git clone https://github.com/clockwork-web-dev/clockwork-control-panel.git && cd clockwork-control-panel`
2. Verify prerequisites: PHP 8.4+ (with curl, mbstring, openssl, pdo_sqlite or pdo_mysql, pcntl), Composer 2+, Node.js 20+.
3. Automated setup: `composer setup` (installs dependencies, copies .env, generates APP_KEY, runs migrations, and builds Vite frontend assets).
4. Verify tests: `php artisan test` (confirms all 1,500 tests pass with 0 failures).
5. Provision admin user: `php artisan clockwork:add-user <email> --name="<Name>"`
6. Start local server & scheduler: `php artisan serve --port=8000` and `php artisan schedule:work`

## Machine-Readable APIs
- [Modules JSON Feed](https://clockworkcontrol.com/api/modules.json): Static JSON feed listing all modules, categories, capabilities, and readiness status.
- [XML Sitemap](https://clockworkcontrol.com/sitemap-index.xml): XML sitemap for search crawlers and indexing agents.