Raydium and Multi-Tenancy
A living reference for architects, engineers, and product owners
Purpose
Raydium is a micro-framework that lets a single codebase operate any number of fully isolated “tenants” (client sites, regional brands, white-label instances, etc.). WordPress itself remains untouched: for each request Raydium decides which tenant you’re serving, loads only that tenant’s environment, and then boots an ordinary single-site WordPress run. Isolation lives entirely in configuration, not in forked code or patched core.
Core Ideas at a Glance
| Principle | What It Means in Practice |
|---|---|
| Up-stream orchestration | All tenant logic happens before WordPress loads. WP gets standard constants; it never “knows” multiple tenants exist. |
| Config over forks | Tenants are defined by simple JSON & .env files—not separate Git repos—so updates ship once. |
| Service container discipline | Every shared resource (DB, cache, mail, logs) is requested from a lightweight dependency-injection container that’s already seeded with the tenant’s settings. |
| Middleware pipeline | Request processing is a lineup of small, swappable steps (security, tenant resolution, auth, logging…) that you can reorder without touching WP hooks. |
High-Level Lifecycle
Incoming Request
│
▼
1. Framework Boot
– load global env & settings
– build service container
│
▼
2. Tenant Resolution
– map host / path → tenant ID
– merge tenant-specific env & config
│
▼
3. Middleware Chain
– security headers
– authentication
– rate limits, logging, etc.
│
▼
4. WordPress Hand-Off
– include wp-blog-header.php
– WP runs exactly once, with tenant’s
DB credentials & table prefix
│
▼
5. Response
– send headers & body
– record per-tenant logs / metricsTenant Anatomy
| Layer | Global Default | Tenant Override (optional) |
|---|---|---|
| Database | One shared server or cluster | Separate credentials / table prefix |
| Cache | Shared Redis / Memcached | Unique namespace per tenant |
| Logs | Central storage directory | Sub-folder %tenant_id%/… |
| Feature Flags | Off by default | Enable per tenant via env variable |
| Templates / Assets | Common theme & assets | Tenant-specific theme folder (inheritance supported) |
Developer Workflow
- Add a TenantCreate a record in the tenant map, copy a template env file, fill in DB credentials and any flags.
- Run LocallyHost alias → tenant domain; the framework routes each host to its env on the fly.
- Ship UpdatesMerge once, deploy once; every tenant automatically receives the fix or feature.
- DebugTail the tenant’s dedicated log folder or watch aggregated dashboards—no mixed messages.
Operational Gains
| Challenge without Raydium | How Multi-Tenancy Solves It |
|---|---|
| Patch explosion (same hot-fix in 30 repos) | One patch, one pipeline, all tenants updated |
| Data-leak risk (shared WP multisite tables) | Isolated tables / DBs chosen per request |
| Slow spin-up (new repo, new CI job) | Add JSON entry + env file → site is live |
| Plugin compatibility doubts | WordPress core stays vanilla, so 99 % of plugins “just work” |
Beta Caveats
- API still fluid – File names and middleware IDs may rename; track release notes.
- Docs lag edge-cases – Exotic tenancy rules (wildcard paths, CLI cron) are evolving.
- Governance required – Because tenants share code, reckless commits can affect all sites; keep CI quality gates strict.
Roadmap Highlights
- GUI Tenant Manager – Web UI for non-technical staff to add/edit tenants.
- Tenant-Scoped Asset Builds – Automatic theme & CSS/JS compilation per tenant.
- First-class Docker/K8s Charts – Blue-green deployments with tenant-aware health probes.
- Pluggable Auth Middleware – Drop-in SSO or JWT modules without touching core.
Should You Adopt Now?
| Good Fit | Not Yet |
|---|---|
| Agencies/SaaS juggling 5–100+ client sites with one dev team | Projects locked to shared cPanel hosting |
| Teams comfortable editing env/JSON & using Composer in CI/CD | Stakeholders needing point-and-click set-up today |
| Early adopters who can give beta feedback | Regulated industries forbidding beta dependencies |
Key Takeaway
Raydium’s multi-tenancy is invisible to WordPress and transparent to users. By moving every tenant decision into a thin PHP shell before the WP bootstrap, you get:
- Isolation worthy of separate installs
- Maintenance speed of a single repo
- Zero intrusion into WordPress core
If that balance—isolate data, unify code—matches your long-term scalability goals, Raydium is already proving itself in the field. Clone, experiment, and help shape the 1.0 release.