Overview
Sub Theme is a self-hosted application platform. It provides authentication, user management, horizontal database sharding, email queues, push notifications, and a child app pattern — all running on commodity shared hosting.
Two Repositories
The platform consists of two git repos deployed as siblings in the same webroot:
| Repo | Deploys To | Purpose |
|---|---|---|
wave-networks-core |
public_html/admin/ |
Auth, users, sessions, shard routing, email queue, notifications, shared helpers |
child-app |
public_html/your-app/ |
Template for building apps. Clone it, rename it, build your features on top. |
How It Works
Child apps are separate repos that include the admin core's bootstrap file. One line of PHP gives you everything:
// your-app/include/common.php
include(__DIR__ . '/../../admin/include/common.php');
// You now have:
// $db — core database (read-only from child apps)
// $_SESSION — authenticated user session
// queue_email() — send email via core's queue
// send_notification() — push notifications to users
// All helper functions: h(), sanitize(), db_query(), etc.The child app then opens its own database, runs its own migrations, and includes its own helpers and action files. Core handles auth and shared services. Your app handles business logic.
Three Database Layers
Every child app has access to three database layers:
| Layer | Variable | Access | Contains |
|---|---|---|---|
| Core Main DB | $db |
Read only | Users, sessions, email queue, notification categories |
| Child Main DB | $child_db |
Read/write | Your app's tables (items, settings, whatever you build) |
| Child Shard DBs | $childShardConfigs |
Read/write | Per-user data distributed across shard databases |
Deployment Layout
Agent-Readable Architecture Reference
The complete architecture, all function signatures, coding rules, database schemas, and patterns are available in machine-readable format at:
https://subtheme.com/wave-networks.json
Point your AI coding agent at this URL before starting any build. With this file plus the repo CLAUDE.md files, an agent can build a complete child app with no clarifying questions.
Also available:
https://subtheme.com/agent.json — platform manifest
https://subtheme.com/llms.txt — plain text overview
Key Principles
- No cloud required. Runs on any PHP 8.2+ shared hosting with MySQL.
- No vendor lock-in. You own every line of code. No proprietary SDKs.
- Horizontal scaling built in. Database sharding from day one, not bolted on later.
- Child apps are independent. Each app has its own repo, database, migrations, and theme.
- Shared services are free. Email, notifications, Web Push — included, not metered.
- Centralized error logging. PHP errors from all apps captured to database with admin UI for viewing, filtering, and resolving.
- Service API keys. Scoped API keys for external tool access — CI/CD, monitoring, MCP agents.
- Centralized versioning. Public version API with auto-update checks on the admin dashboard. Detailed changelog with file-level diffs for AI-assisted upgrades.
- AI-agent friendly. Built-in MCP server lets AI agents query errors, resolve issues, and read stats. Plus a machine-readable spec at
/wave-networks.json.