Building a Multi-Tenant Architecture to Scale SchleeGleixner’ Brand Asset Delivery

About the project

SchleeGleixner, is a design agency specializing in brand design, logo creation, colour palettes, and corporate identities. SchleeGleixner needed a scalable solution to manage and deliver design work to multiple clients simultaneously but struggled with maintaining separate, branded environments for each client while using a single Statamic installation.

As a solution, we implemented a subdomain-based multi-tenancy architecture on Statamic CMS, that enabled SchleeGleixner to operate one centralized Statamic installation where each client exists as an isolated tenant with their own branded subdomain (e.g., clientname.schlegleixner.com).

The deliverable was a production-ready, tested multi-tenancy foundation that the client could build upon independently.

Important: This project was delivered in June 2024. At the time, it was built on Statamic 4.5 with Eloquent Driver 3.3. Statamic 5 has since been released. The multi-tenancy architecture remains compatible, though driver customizations may require updates for migration.

PS: No front-end customization was done in this project as the client wanted to do this themselves.

B2B Client:

SchleeGleixner

Development & Deployment:

4 months

Technologies:

Laravel

Statamic

Multitenancy

Client's Pain-Point

SchleeGleixner needed a Statamic-powered architecture for their internal workflows but could not make it work.

As explained earlier, our client needed a centralized Statamic installation that could serve multiple clients simultaneously, each in their own isolated environment. SchleeGleixner already committed to Statamic for good reasons: its modern architecture, proven multi-tenancy capabilities, and database-backed flexibility.

Switching platforms was therefore not an option, hence, the need to get their existing approach working. Building a subdomain-based multi-tenancy was the identified solution suitable for their internal workflow.

Prior, was an implementation roadblock in the execution of critical pieces from SchleeGleixner. Observations highlighted a knowledge gap between theory and implementation for which critical pieces were not connecting:

Tenant isolation was not complete - Data was leaking between tenants
Authentication was not properly scoped to tenant
Assets were not isolating correctly
The debugging trail had gone cold

A well orchestrated multi-tenancy architecture requires deep familiarity with Laravel's request lifecycle, middleware chains, and database-level scoping. More importantly, it requires experience debugging these systems when the expected behaviour does not materialize.

SchleeGleixner needed prior expertise in problem-solving for such challenges. Our client needed an expert who could identify where tenant-awareness was breaking down, debug through the Statamic Eloquent driver to find the gaps, and implement the missing pieces without rewriting their entire approach. SchleeGleixner did not need a new platform, rather an infrastructure expertise to unlock the multi-tenancy foundation they had already chosen.

WHAT IS MULTI-TENANCY?

Multi-tenancy is an architecture that can be used either with a single database or multiple databases. It is a sort of architecture that allows for specific use cases as the one presented here. It is versatile and offers flexibility. In certain situations multiple databases might be required.

There can be different approaches to the implementation. One could add more complexity to the architecture if needed to handle a lot of load. It's an extensible approach and for the given use case it worked just fine.

For this specific case, rather than using Statamic as a traditional website CMS, SchleeGleixner leveraged Statamic CMS as an internal operations platform - a design delivery system. Statamic CMS offered a fixed set of pages and form builder, through which SchleeGleixner's designers could then create structured workflows to upload assets (logos, brand materials, colour schemes) and present them as interactive, responsive deliverables to clients. Each client receives a branded mood board experience within their isolated tenant environment.

For our client, multi-tenancy was a requirement because it enabled complete client design customization and user configurations by eliminating the overhead of managing multiple Statamic installations while maintaining strict, distinct and secure data isolation.

Each tenant maintained:

1. Separate user management and authentication;

2. Isolate asset storage;

3. Custom branding in the control panel;

4. Tenant specific configurations.

Git-based collaborative workflow via GitHub

We provisioned a private repository within our Laramate organization and granted our client - SchleeGleixner, collaborative access. This enabled version-controlled, asynchronous development by allowing their development team to download the codebase, review implementation incrementally through small commits, understand certain changes, and extend the multi-tenancy foundation independently.

For this project, we solely delivered an infrastructure handoff other than code deployment, plus, demonstrated functional tenant isolation and identification (Tenant A from Tenant B). Each tenant is distinct and cannot access another tenant's data, assets, or users.

How Multi-Tenancy was Orchestrated in SchleeGleixner ?

1. Architecture Decision

We built an empty Statamic installation configured for subdomain-driven multi-tenancy with a single centralized database. The subdomain acts as the tenant identifier. For instance, when a request comes in at clientA.schlegleixner.com, the system automatically resolves which tenant is being accessed and scopes all subsequent operations to that tenant's data.

2. Subdomain Structure

Each client receives their own branded subdomain under SchleeGleixner's domain. For example, clientA.schlegleixner.com and clientB.schlegleixner.com operate as completely separate environments. If Laramate became a client, accessing laramate.schlegleixner.com would present a fully branded welcome page with their corporate identity thus creating a white-label experience where each client perceives the platform as custom-built for them.

3. Single Database Approach

In this specific environment, we chose a single database over multi-database architecture. The overhead of managing multiple databases adds complexity without improving security. You could still gain access to the database driver and access all databases regardless. Multiple databases are not an added security layer. Physical database separation becomes necessary only at enterprise scale with strict compliance requirements. For this project size, that overhead was not justified.

4. Database Structure

Data separation happens through tenant scoping at the application level. Using Stencil's tenancy package, we implemented a tenant_id column across all relevant tables. Every row carries its tenant identifier: Tenant A's data has tenant_id = 1, Tenant B's has tenant_id = 2, and so on. A dedicated tenants table maps subdomains to tenant IDs and stores tenant-specific configuration (names, branding settings, etc.). The rest is programming, ensuring every query, every file operation, every asset retrieval respects tenant boundaries.

5. Security Through Proper Programming

Data security between tenants is achieved through rigorous scoping - every database query filtered by tenant_id, every file path namespaced by tenant, every authentication check scoped to the current tenant. We validated this through comprehensive testing to ensure no cross-tenant data leakage.

6. Development Environment

We used DDEV to replicate the production multi-subdomain structure locally. The development environment ran with full subdomain support: clientA.ddev.site, clientB.ddev.site, clientC.ddev.site, allowing us to test tenant isolation thoroughly before deployment. This local-production parity was critical for debugging edge cases in tenant switching and data scoping.

7. Testing

We provided a PHP Unit test suite covering tenant separation, authentication scoping, and asset isolation. These tests validate that Tenant A cannot access Tenant B's data, users, or files under any circumstance. The test suite serves as both validation and documentation, proving the multi-tenancy implementation is robust and provides a safety net for future development.

HOW DOES IT WORK ?

We delivered an empty Statamic installation with no starter kits, no pre-built themes. While Statamic offers starter kits to accelerate development (design systems, page builders, boilerplate content), we deliberately built without.

The foundation uses Statamic's Eloquent driver to persist all content and configuration to the database, enabling true multi-tenancy at the data layer. This approach gave SchleeGleixner full control to build their design delivery workflows without inheriting unnecessary structure.

Tenant resolution within SchleeGleixner: Tenant identification happens automatically via subdomain. When a request hits clientA.schlegleixner.com, middleware intercepts the subdomain, queries the tenants table, resolves the tenant ID, and injects it into the application container. Every subsequent operation: database queries, file storage, authentication checks, inherits this tenant context.

The technical implementation is then followed by a root domain routing. This is configured in Laravel's routes/web.php. The root domain (schlegleixner.com) serves as the landing page or administrative interface, while subdomains route to tenant-specific environments. In our case, to the content and user management which is fully database-backed. All content entries, user accounts, and permissions live in the database with tenant_id foreign keys. This allows dynamic, tenant-specific content without filesystem coupling.

Then there is super user access. The Statamic super user can authenticate into any tenant environment - a deliberate design choice by SchleeGleixner for administrative oversight. This cross-tenant access is scoped to super users only; regular tenant users remain isolated and so is email and queue isolation. Emails, queues, and jobs are tenant-scoped. When a job is dispatched, it carries the tenant_id in its payload, ensuring background processes (email notifications, asset processing) execute within the correct tenant context. Stencil's tenant-aware job traits handle this automatically.

In addition to email and queue isolation, it is asset isolation. Here, (logos, brand materials, deliverables) are encapsulated per tenant. File paths are namespaced by tenant_id, preventing cross-tenant access. A client accessing clientA.schlegleixner.com can only retrieve assets stored under Tenant A's directory. Statamic's content structures (blueprints, field sets) are shared across tenants. This centralization is intentional to SchleeGleixner's design delivery process which follows a standardized workflow. Sharing these structures means updates to the content model propagate to all tenants instantly, maintaining consistency without manual synchronization.

Stored in the filesystem using Statamic's default file driver are roles and groups. While content and users are database-backed, permission structures remain file-based. This hybrid approach balances flexibility (tenant-specific users) with simplicity (globally defined roles). These permissions grant authentication and asset access. Image retrieval requires authentication. We implemented an authenticated route that validates three conditions before serving an image:

(1) the user is logged into the current tenant and has an active session

(2) the requested image belongs to that tenant's asset directory

If any condition fails, the request is denied. This ensures tenant A users cannot construct URLs to access tenant B's assets. Authentication and asset ownership are enforced at the application layer, not just filesystem permissions. When a client visits clientA.schlegleixner.com, they're prompted to log in.

Once authenticated, their session is scoped to Tenant A. They can browse Tenant A's content, upload assets to Tenant A's storage, and view Tenant A's deliverables. But they cannot see or even request resources from Tenant B. The tenant boundary is absolute.

THE CHALLENGE

Stencyl's multi-tenancy package handled tenant identification and database scoping, but Statamic's Eloquent driver was not fully tenant-aware out of the box. Certain operations: global variable management, asset handling, and specific user management flows, were not automatically scoping to the active tenant. The driver was written without multi-tenancy as a first-class concern, meaning some methods bypassed tenant context entirely when reading or writing data. To achieve complete isolation, we used XDebug to trace where tenant context was being lost.

XDebug is a step debugging tool for PHP applications. By setting breakpoints at multiple junctions - data writes, global variable access, asset storage operations, we interrupted execution at runtime and inspected the call stack. This revealed exactly which driver methods were not respecting tenant scope when storing or retrieving globals. Once identified, we overrode those methods to enforce tenant filtering, ensuring the Statamic control panel became fully tenant-aware. With the driver corrected, everything else fell into place: authenticated asset routes, scoped authentication, isolated queues - all standard implementations once the foundational driver issue was resolved.

A key insight of this case study is that multi-tenancy failures often hide in framework drivers, not application code. XDebug's runtime inspection allowed us to pinpoint the gap in hours rather than days of trial-and-error debugging. This is the expertise gap SchleeGleixner's team faced: knowing where to look when tenant isolation breaks down.

Nevertheless, in retrospect to our technical implementation and as a potential open source contribution, we should have contributed these driver overrides back to the Statamic repository as a pull request (PR). The fact that minor changes were needed to make the Eloquent driver fully tenant-aware indicates a gap in the official implementation; one that likely affects others building multi-tenant systems on Statamic. Filing a PR would have improved the core package and made it easier for the broader community to implement multi-tenancy without encountering the same roadblocks. Moving forward, we prioritize contributing back to open-source projects when we discover framework limitations. These contributions strengthen the ecosystem and reduce friction for future developers tackling similar architectural challenges.

Why Statamic for a Multi-Tenancy Architecture?

SchleeGleixner chose Statamic for its superior developer experience. It offers modern architecture, clean codebase, and intuitive APIs that make it significantly more pleasant to work with, leading to a better developer experience often abbreviated as DX. This encompasses everything from API design to documentation quality to local development workflows, and Statamic excels here.

As a Multi-Tenancy foundation, Statamic's architecture is primarily built on file-based storage. It offers a first-party eloquent-driver to use a database, which makes it perfectly suitable for a multitenancy environment. SchleeGleixner knew multi-tenancy was possible with Statamic (it's a proven use case).

Additionally, Statamic was chosen for platform continuity. SchleeGleixner was already using Statamic for internal workflows. Switching would mean retraining their team, rewriting existing tools, and abandoning institutional knowledge. Therefore, extending their existing Statamic foundation was the pragmatic choice.

BENEFITS OF CHOSEN TECH STACK

Stencyl's Tenancy Package

We chose Stencyl over Spatie's tenancy package for its superior subdomain routing customization. Stencil's tenant-aware job traits handled background process scoping automatically. When a queue job dispatches, it carries tenant context without manual intervention.
The package's configurability lets us adapt tenant identification, database scoping, and asset isolation to SchleeGleixner's specific workflows.

Statamic CMS

Native database-backed architecture designed for multi-tenancy; versatile form builder enabled operations platform design with tenant-aware control panel and proper tenant isolation.

Laravel

Statamic's underlying framework provided architectural bedrock with Eloquent ORM for tenant-scoped database operations via global scopes and model observers; subdomain routing handled tenant identification with a mature ecosystem supporting middleware chains, service containers, and request lifecycle management.

DDEV (Local Development Environment)

DDEV's Docker containerization replicated the production multi-subdomain structure locally - clientA.ddev.site, clientB.ddev.site, clientC.ddev.site provided local-production parity essential for debugging tenant-switching edge cases and validating isolation before deployment.

XDebug (Step debugging)

XDebug proved crucial for troubleshooting tenant-awareness gaps in the Eloquent driver. Runtime breakpoints analyzed complexities, debugged problems, limitations or missing implementations alongside code inspection. XDebug eliminated guesswork.

Statamic Eloquent Driver

The Eloquent driver enabled database-backed content storage, provided object-relational mapping for clean data handling and integrated smoothly with Laravel's ecosystem.

Overall, the tech stack synergy was a straightforward process. First, there was already awareness of the task and all the pathways needed to fulfill the task in the best way possible. The combination of DDEV for local environment, XDebug for debugging, Statamic for the CMS layer, Laravel as the foundation, and Stencil's tenancy package for multi-tenancy created a solid, efficient development experience. Statamic for the client's given objective was a good option. The project confirmed that Stencil's tenancy package was the right choice because it gave configuration options that made it easy to adapt to the use case.

For SchleeGleixner (at the time this project was delivered); dozens of tenants, moderate traffic, a single database with application-level scoping was optimal. But its architectural extensibility won't crumble when requirements change. That is the value of choosing tools that align with your use case rather than forcing your use case into tools.

Why Choose Us as Laravel Experts

When clients reach out to us, they often do so specifically because we have the answers to their pain-points.

We have mastered the Laravel framework intimately, and we know how to use it.

We understand how to structure Laravel applications for complex projects, bi-directional system integration, maintainability, performance optimization, proper security implementation measures, website accessibility, and how to integrate Laravel with other and older systems.

For our future clients considering custom software development, Laravel represents an excellent choice, and partnering with us, Laravel experts, ensures that choice pays dividends.