# mitchmac/serverlesswp architecture

> Architecture diagram of the GitHub repository mitchmac/serverlesswp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mitchmac/serverlesswp
- Repository: https://github.com/mitchmac/serverlesswp

## Overview

##### Project Type and Purpose
- ServerlessWP is a full-stack, serverless hosting solution for WordPress. It combines a Node.js “API” layer (api/index.js + serverlesswp-node) deployed as serverless functions on Vercel, Netlify, or AWS Lambda with a PHP runtime to serve a standard WordPress core in the `/wp` directory.
- It supports two data-layer options:
- A managed MySQL (or MariaDB-compatible) database (e.g., TiDB)
- A SQLite file stored on demand in S3-compatible object storage

##### File Structure Analysis
Top-level components:
- `/api` – Node.js entrypoint for all HTTP requests; invokes serverlesswp-node to bootstrap PHP/WordPress
- `/util` – Utility scripts for directory management, installation flows, and SQLite+S3 logic
- `/serverless.yml`, `netlify.toml`, `vercel.json` – Deployment configurations for AWS Serverless Framework, Netlify Functions, and Vercel Functions, respectively
- `package.json` – Declares Node.js dependencies, including serverlesswp-node
- `/wp` – A full copy of the WordPress core, plus bundled plugins and themes (e.g., WP Offload Media Lite, SQLite Integration plugin)

##### Key README Insights
- Deploys to Vercel/Netlify/AWS using their serverless functions
- Supports environment-variable configuration for MySQL credentials or SQLite+S3 settings
- Media offload to S3 via the Amazon S3 & CloudFront plugin
- Uses serverlesswp-node to run PHP in a serverless context

##### Main Components
a. User & CDN Layer
- End users (browsers, mobile clients)
- CDN / edge network (Vercel Edge, Netlify Edge) serving cacheable static assets (CSS, JS, images)
b. Serverless Function / API Gateway
- Vercel/Netlify Function or AWS Lambda behind API Gateway
- Entrypoint: `/api/index.js`
- Middleware: serverlesswp-node (spawns PHP process, translates Node event → PHP _SERVER variables)
c. PHP / WordPress Core
- `/wp` directory: core PHP files + plugins + themes
- WP runs in “readonly” mode for static assets, “read/write” mode on dynamic pages or admin actions
d. Data Layer
- Primary: relational database (MySQL/TiDB)
- Optional: SQLite file streamed to/from S3 via util/sqliteS3.js (S3 bucket)
e. Object Storage for Media
- S3-compatible bucket hosting uploads, served via CDN or delivery provider (CloudFront, Cloudflare, KeyCDN, etc.)
- WP Offload Media Lite plugin handles uploads → S3
f. External Services & CI
- GitHub Actions for tests (`.github/workflows/*.yml`)
- Serverless Framework (`serverless.yml`) for AWS
- Third-party services: TiDB Cloud, AWS S3, CDN providers

##### Interactions & Data Flow
1. Browser requests a URL → hits CDN edge
2. If static, CDN returns asset; if dynamic → routes to serverless function
3. Node function (api/index.js)
- Parses event, sets up PHP environment, calls serverlesswp-node
4. PHP process loads `wp/index.php`, runs WordPress bootstrap
5. WordPress queries either the MySQL database (via `wp-config.php` ENV variables) or reads/writes `database.sqlite` on S3 through util/sqliteS3
6. For media uploads, WP plugin intercepts and writes files to S3 bucket; returns S3 URLs
7. Response flows back through Node function → CDN → client

##### Architectural Patterns & Design Principles
- Microservices / serverless functions for isolation and scaling
- Plugin architecture in WordPress for extensibility (media offload, SQLite integration)
- Environment-driven configuration (ENV variables choose MySQL vs SQLite+S3)
- Immutable deployment: WordPress core & plugins are part of Git repository
- Edge caching: static assets served directly from CDN

##### Essential Elements
- CDN / edge network
- Serverless function boundary
- Node.js ↔ PHP bridge (serverlesswp-node)
- WordPress core directory
- Plugin/utility modules (S3 offload, SQLite integration)
- Data planes: MySQL vs SQLite+S3
- Media storage in S3

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Client & CDN"
        Client(("Client")):::external
        CDN[/"CDN Edge"/]:::external
    end

    subgraph "Serverless Function Layer"
        API["Serverless Function\n(api/index.js)"]:::compute
        Bridge["serverlesswp-node\nmiddleware"]:::compute
        subgraph "Utility Scripts"
            Dir["directory.js"]:::compute
            Install["install.js"]:::compute
            SQLiteS3["sqliteS3.js"]:::compute
            Upgrade["upgrade-wp.sh"]:::compute
        end
    end

    subgraph "PHP & WordPress"
        PHP["PHP Process"]:::compute
        WP["WordPress Core\n(/wp)"]:::compute
        MU["Must-Use Plugin\n(serverlesswp.php)"]:::compute
        MediaPlugin["Media Offload Plugin"]:::compute
        SQLitePlugin["SQLite Integration Plugin"]:::compute
    end

    subgraph "Data & Storage"
        MySQL[(MySQL Database)]:::storage
        SQLite[(SQLite File on S3)]:::storage
        S3[(S3 Bucket)]:::external
    end

    subgraph "CI & Deployment"
        ServerlessConfig["serverless.yml"]:::external
        NetlifyConfig["netlify.toml"]:::external
        VercelConfig["vercel.json"]:::external
        E2E["e2e.yml"]:::external
        UpdateCI["update-wp.yml"]:::external
        TestDocker["Dockerfile"]:::external
        DBTest["run-db-test.sh"]:::external
        S3Test["run-s3-test.sh"]:::external
        InstallerTest["installer.php"]:::external
        BuildTest["build-test.sh"]:::external
    end

    Client -->|"HTTP request"| CDN
    CDN -->|"dynamic route"| API
    API -->|"invokes"| Bridge
    Bridge -->|"spawns"| PHP
    PHP -->|"loads bootstrap"| WP
    WP -->|"loads MU plugin"| MU
    WP -->|"loads plugins"| MediaPlugin
    WP -->|"loads plugins"| SQLitePlugin
    PHP -->|"read/write"| MySQL
    PHP -->|"read/write"| SQLite
    SQLite -->|"stream"| S3
    MediaPlugin -->|"uploads media"| S3
    S3 -->|"serves media"| CDN

    classDef requestFlow fill:#D0E7FF
    classDef storage fill:#D0FFD6
    classDef external fill:#FFE0B3
    classDef compute fill:#E8E8E8

    class Client,CDN,API,Bridge,PHP,WP,Dir,Install,SQLiteS3,Upgrade,MU,MediaPlugin,SQLitePlugin requestFlow
    class MySQL,SQLite storage
    class S3,ServerlessConfig,NetlifyConfig,VercelConfig,E2E,UpdateCI,TestDocker,DBTest,S3Test,InstallerTest,BuildTest external
    class API,Bridge,Dir,Install,SQLiteS3,Upgrade,PHP,WP,MU,MediaPlugin,SQLitePlugin compute

    click API "https://github.com/mitchmac/serverlesswp/blob/main/api/index.js"
    click Bridge "https://github.com/mitchmac/serverlesswp/blob/main/package.json"
    click WP "https://github.com/mitchmac/serverlesswp/tree/main/wp/"
    click MU "https://github.com/mitchmac/serverlesswp/blob/main/wp/wp-content/mu-plugins/serverlesswp.php"
    click MediaPlugin "https://github.com/mitchmac/serverlesswp/tree/main/wp/wp-content/plugins/amazon-s3-and-cloudfront/"
    click SQLitePlugin "https://github.com/mitchmac/serverlesswp/tree/main/wp/wp-content/plugins/sqlite-database-integration/"
    click Dir "https://github.com/mitchmac/serverlesswp/blob/main/util/directory.js"
    click Install "https://github.com/mitchmac/serverlesswp/blob/main/util/install.js"
    click SQLiteS3 "https://github.com/mitchmac/serverlesswp/blob/main/util/sqliteS3.js"
    click Upgrade "https://github.com/mitchmac/serverlesswp/blob/main/util/upgrade-wp.sh"
    click ServerlessConfig "https://github.com/mitchmac/serverlesswp/blob/main/serverless.yml"
    click NetlifyConfig "https://github.com/mitchmac/serverlesswp/blob/main/netlify.toml"
    click VercelConfig "https://github.com/mitchmac/serverlesswp/blob/main/vercel.json"
    click E2E "https://github.com/mitchmac/serverlesswp/blob/main/.github/workflows/e2e.yml"
    click UpdateCI "https://github.com/mitchmac/serverlesswp/blob/main/.github/workflows/update-wp.yml"
    click TestDocker "https://github.com/mitchmac/serverlesswp/tree/main/test/Dockerfile"
    click DBTest "https://github.com/mitchmac/serverlesswp/blob/main/test/run-db-test.sh"
    click S3Test "https://github.com/mitchmac/serverlesswp/blob/main/test/run-s3-test.sh"
    click InstallerTest "https://github.com/mitchmac/serverlesswp/blob/main/test/installer.php"
    click BuildTest "https://github.com/mitchmac/serverlesswp/blob/main/test/build-test.sh"
```
