# Subtheme — Wave Networks Ecosystem Reference Implementation

> Subtheme (subtheme.com) is a live reference implementation of the Wave Networks
> PHP ecosystem. It demonstrates two repos working together on shared hosting:
> wave-networks-core (the admin and auth framework) and child-app (a sample
> child application built on top of it).

## Repos

- Core framework: https://github.com/WaveNetworks/wave-networks-core
- Child app example: https://github.com/WaveNetworks/child-app

## Discovery

- Machine-readable manifest: https://subtheme.com/agent.json
- Full architecture + API reference: https://subtheme.com/wave-networks.json
- Documentation: https://subtheme.com/docs
- Live demo: https://subtheme.com/child-app/app/

## Stack

- PHP 8.2, MySQL 8.0, Bootstrap 5.3.2 (Bootswatch), D3.js v7, Docker
- Default theme: sandstone (25 Bootswatch themes + custom theme registration)
- Child app ships a "Glassmorphism" custom theme with SCSS pipeline
- Deploy: Python SFTP script (paramiko) — diffs git history, uploads only changed files

## Architecture

Two repos share one webroot:

    public_html/
      admin/       ← wave-networks-core (auth, users, email, notifications, sharding)
      child-app/   ← child-app template (clone, rename, build your app)
      ../files/    ← user file storage (above webroot, hashed directory tree)

Child apps include admin's common.php to inherit auth, sessions, shard routing,
email queue, push notifications, GDPR compliance, and all helper functions.
Each child app has its own databases and shard databases.

Bootstrap chain: child-app/include/common.php -> admin/include/common.php

## Auth Methods

- Email/password with bcrypt
- OAuth 2.0 (generic provider pattern — configurable per deployment)
- SAML 2.0 SSO
- TOTP two-factor authentication
- Remember-me device tokens

## Key Features

- Horizontal database sharding — built in from day one, users distributed automatically
- SMTP email queue with per-minute/hour throttling and delivery logging
- Web Push notifications via VAPID (no Firebase) with per-category user preferences
- GDPR compliance — consent versioning with re-consent enforcement, data export,
  right to erasure with 30-day cooling-off, immutable audit trail
- Role-based access control (admin, owner, manager, employee)
- MCP server (JSON-RPC 2.0 over stdio) for AI agent integration
- Error logging with MCP-exposed resolution tools
- Service API keys with scoped access (Bearer token auth)
- Profile photo upload with GD thumbnailing and hashed homedir storage
- Docker local dev (8 containers) — same codebase deploys to $5/month shared hosting
- Python SFTP deploy — diffs git history, uploads only changed files
- HTML5 canvas background layer — gamification ready, theme-aware
- D3.js dashboard charts, DataTables with AJAX, debounced live search
- Bootswatch theme switcher with custom theme registration

## Child App Pattern

CRITICAL: Always start a new child app by cloning the template repo:
git clone https://github.com/WaveNetworks/child-app.git your-app-name/
Never create the directory structure from scratch — the template provides auth
pages, common helpers, template.php, JS assets, SCSS pipeline, Docker config,
installer, and the full directory structure. Modify the cloned files, don't
recreate them.

Child apps are separate git repos deployed as siblings of admin/ in the same webroot.
They inherit auth, sessions, sharding, helpers, and migrations from core.
Each child app has its own databases and shards.

What core provides to child apps:
- $db (core main DB, read-only from child apps)
- $_SESSION['user_id'], $_SESSION['shard_id'] (from login)
- prime_shard() / child_prime_shard() for shard routing
- h(), sanitize(), db_query(), db_fetch() helpers
- queue_email() — send email via core's SMTP service
- send_notification() / broadcast_notification()
- All GDPR functions (consent, export, deletion, login history, devices)
- register_theme() for custom theme registration
- Auth pages (login, register, OAuth, SAML, 2FA, re-consent)

Routing: Flat ?page= routing in app/index.php, flat if/elseif action files.
API: Single api/index.php entry point, AJAX via apiPost() helper.

## Docker Development (Multi-App)

Each child app runs as an independent Docker Compose stack with its own admin
databases, branding, and user accounts — fully isolated from other apps on the
same machine. This differs from production shared hosting, where multiple child
apps share a single admin installation.

Key requirements for multi-app Docker:
- Volume names must be prefixed with your app name to avoid conflicts
  (wn_db_main becomes yourapp_admin_main)
- Host ports must be unique per stack (80, 8081, 8082, etc.)
- Each stack gets a fresh admin install with its own config, users, and branding
- After cloning the template, run npm install && npm run build:css to compile
  the glassmorphism theme (SCSS source only, no pre-built CSS)
- The admin installer may overwrite install/.htaccess via the volume mount —
  run git restore install/.htaccess in the admin repo after installation
- Use explicit install URLs: /admin/install/index.php (not just /admin/install/)

See wave-networks.json docker_multi_app section for volume naming examples
and port allocation details.

## MCP Server

An MCP server is part of the Wave Networks ecosystem for authorized agents.
It is not publicly accessible. Authenticates via service API key (Bearer token).
Exposes error log tools: list_errors, get_error, resolve_error, unresolve_error, get_error_stats.

## Public-Facing Website

Every child app can have a public-facing marketing and documentation website.
Clone the subtheme-website repo as your starting point:
git clone https://github.com/WaveNetworks/subtheme-website.git your-site/

Reference implementation: https://subtheme.com

Key pattern:
- Standalone PHP + HTML + CSS — no framework, no build tools, no npm, no database writes
- Uses admin's common_auth.php (NOT common.php) for branding — provides get_branding(),
  h(), and DB access without requiring a login session
- CSS loads from admin and child-app repos via absolute paths (/admin/assets/, /child-app/assets/)
- Has its own docs system: /docs/{section} routes to site/docs/{section}.php partials
- Supports dark/light mode via [data-bs-theme] overrides in site/style.css
- Deployed as a separate git repo to public_html/ root alongside admin/ and child-app/

CRITICAL: Use common_auth.php, never common.php. common.php requires an authenticated
session and will redirect visitors to the login page. common_auth.php provides the same
helpers and branding data without any session guard.

## Agent-Readable Files

Both repos include comprehensive CLAUDE.md files at multiple levels:
- admin/CLAUDE.md — full architecture, coding rules, patterns, database schemas
- admin/db_migrations/CLAUDE.md — migration version rules
- admin/include/actions/CLAUDE.md — action file patterns
- child-app/CLAUDE.md — child app structure, integration patterns, all action names