DEV Community: Sharjeel Zubair

A Dashboard for developers! https://spiffy-palmier-f0c5af.netlify.app/ #health #focus

Sharjeel Zubair — Tue, 14 Apr 2026 11:09:04 +0000

spiffy-palmier-f0c5af.netlify.app

I Built a Multi-Tenant School Helpdesk in Laravel — Here's the Full Stack

Sharjeel Zubair — Tue, 14 Apr 2026 10:28:12 +0000

I open-sourced a production-grade, multi-tenant SaaS last week. Here's a tour of what's inside — and every non-obvious architecture decision along the way.

Meet Schoolytics

Schoolytics is an open-source helpdesk for schools. One platform runs an entire district — each school is isolated by subdomain, runs its own branded portal, and has its own users, issues, and CSAT data.

Think Zendesk meets Linear meets a parent-teacher app — MIT-licensed, self-hostable, and free forever.

🏫 Multi-tenant — one deploy, unlimited schools, subdomain-isolated
🔑 Passwordless parent portal — one-time access codes, no app, no account
🤖 AI triage — Python sentiment microservice scores every issue on submission
🧑‍💼 Three-tier RBAC — admin / branch manager / staff, enforced in queries AND policies
📧 Full email stack — transactional mails, in-app notifications, CSAT surveys
🎛 Nova super-admin — provision a new school (tenant + domain + admin + 10 categories + demo data) with ONE click

The stack

Layer	Choice	Why
Framework	Laravel 12 / PHP 8.2	Fastest iteration, Nova, first-party queue/mail/auth
DB	PostgreSQL 16	Row-level multi-tenancy, case-insensitive `ilike`, check constraints
Multi-tenancy	stancl/tenancy v3	Battle-tested, subdomain-based, row-level scoping
RBAC	Spatie Permission (teams mode)	Team-scoped permissions = tenant-scoped for free
Super-admin	Laravel Nova	Built-in resource CRUD, custom actions for provisioning
Frontend	Blade + Alpine + Tailwind + ECharts	No SPA overhead, ships fast, renders on the server
Queue	Database driver (dev), Redis/SQS (prod)	One less moving piece locally
AI	FastAPI (Python)	Isolated, swappable, doesn't bloat Laravel

The interesting decisions

1. Two auth guards, zero overlap

Most multi-tenant apps put super-admins in the same users table with a is_superadmin flag. That's a mistake the first time a bug lets a tenant query return a central user.

Schoolytics has two completely separate models:

// Guard: central → entry: /nova
class CentralUser extends Authenticatable { /* table: central_users */ }

// Guard: web → entry: /admin/login (tenant subdomain)
class User extends Authenticatable {
    use BelongsToTenant, HasRoles;
    // table: users (row-level tenant_id)
}

CentralUser can't have Spatie roles (teams mode requires a tenant context), so the IssuePolicy has a before() hook:

public function before(?Authenticatable $user): ?bool
{
    if ($user instanceof CentralUser) return true; // full access
    return null; // fall through to normal policy methods
}

Two guards. Zero cross-contamination. Superadmin can debug anything without ever needing a tenant role.

2. Row-level multi-tenancy, enforced twice

Every tenant-scoped model uses a BelongsToTenant trait that:

Adds a global scope filtering WHERE tenant_id = tenant('id')
Auto-fills tenant_id on creating

But I don't trust global scopes alone. For sensitive actions I also do an explicit check:

abort_unless($issue->tenant_id === tenant('id'), 404);

Defense in depth. If someone ever calls withoutGlobalScopes() by accident, the explicit check still catches it.

3. Passwordless parent flow

Parents aren't technical. They don't want accounts. They lose passwords. So:

Admin imports roster contacts (CSV/Excel)
System generates an AccessCode, emails/SMSes it
Parent visits schoola.domain.com, enters code, submits their issue
Only one open issue per contact at a time (enforced by a non-closed-issue lookup)
On issue close, access_code.used_at is reset — parent can submit again with the same code

The UX is identical to a "magic link" but synchronous and auditable.

4. Role-scoped queries in ONE place

Three roles see three different slices:

admin — every issue in the tenant
branch_manager — issues in branches they manage
staff — only issues assigned to them

One query scope handles all of it:

public function scopeVisibleTo(Builder $q, User $user): Builder
{
    if ($user->hasRole('admin')) return $q;

    if ($user->hasRole('branch_manager')) {
        return $q->whereIn('branch_id', $user->branches->pluck('id'));
    }

    return $q->where('assigned_user_id', $user->id);
}

Every Issue::query() in every controller calls ->visibleTo(auth()->user()). Forget it once, and the policy still blocks the action. Two layers.

5. AI triage via a separate microservice

When a parent submits an issue, a queued listener POSTs to a FastAPI service:

Laravel  ──event──► PerformAiAnalysis (queued)  ──HTTP──►  Python FastAPI
                                                               │
                                                               ▼
                                                  {sentiment, category, confidence}
                                                               │
                                                               ▼
                                                  IssueAiAnalysis row

Why separate? Because:

Python's ML libraries are in Python, not PHP
I can swap the model (fine-tune later) without touching Laravel
The HTTP boundary forces me to think about failure modes (timeouts, retries, circuit breakers)
The sentiment service is stateless — horizontally scalable on its own

6. Nova actions that actually save time

Instead of a 5-step manual tenant setup, ProvisionTenant does it all:

Create Tenant row (UUID)
Create Domain row (subdomain)
Switch into tenant context, run tenant migrations
Seed default roles (admin, branch_manager, staff)
Seed 10 default issue categories
Create School + default Branch
Create first admin User with random password
Email the admin their credentials via TenantProvisionedMail

One click. Thirty seconds. A new school is live.

GenerateDemoData is the cooler one — it seeds a tenant with realistic data matched to the 10 default categories (e.g., Transport gets "Bus late", Academics gets "Math homework concern"), creates branch managers, staff assigned to categories, parents and teachers each with an open issue. You can demo the product to a school in 60 seconds.

7. The queue + tenancy trap

This one bit me hard enough that it got its own postmortem post. TL;DR: never put a tenant-scoped Eloquent model in a queued job's constructor. Pass scalars, call tenancy()->initialize() in handle().

What's in the repo

app/
  Http/Controllers/          → tenant + public portal controllers
  Models/                    → User, Issue, RosterContact, AccessCode, ...
  Policies/                  → IssuePolicy, RosterContactPolicy, ...
  Nova/                      → Tenant, Domain, CentralUser resources + actions
  Jobs/                      → AnalyzeIssueSentiment, LogActivityJob
  Listeners/                 → PerformAiAnalysis
  Mail/                      → 6 transactional mailables
database/
  migrations/                → central schema
  migrations/tenant/         → per-tenant schema
  seeders/                   → roles, default categories, demo data
routes/
  web.php                    → /nova + central admin
  tenant.php                 → /admin + public portal (per-tenant)

~30 migrations, ~40 models, ~20 controllers, ~15 policies, full Nova suite.

What I'd do differently next time

Start with Redis for queue — the database driver was fine until demo day, when AI jobs stacked up
Write the tenancy feature test FIRST — the one that actually boots a queue worker with no tenant context. Would have caught the queue trap in minutes instead of hours.
Pick Livewire over Blade+Alpine for the admin — the filter-form dance gets old; Livewire would halve the code
Use Inertia for the parent portal — it's the one place where a SPA-ish feel would help UX

Try it

git clone https://github.com/sharjeelz/eliflammeem-git.git
cd eliflammeem-git
composer install && npm install
cp .env.example .env && php artisan key:generate
php artisan migrate && php artisan db:seed
composer run dev

Then open http://central.lvh.me:8000/nova. Provision a tenant. Watch the whole thing come alive.

Contribute

⭐ the repo if this saved you a weekend. PRs welcome — the roadmap is on the README:

Arabic + RTL UI
WhatsApp Business API for access-code delivery
SSO for staff
Per-tenant custom branding

🔗 github.com/sharjeelz/eliflammeem-git

What would you have done differently? Drop a comment — genuinely want to hear it.

The Laravel Queue + Multi-Tenancy Trap That Cost Me 3 Hours

Sharjeel Zubair — Tue, 14 Apr 2026 10:15:56 +0000

A postmortem on a bug that passed all my unit tests, all my feature tests, and every manual smoke test — then blew up the first time a real user clicked a button in production.

The setup

I'm building Schoolytics, an open-source multi-tenant helpdesk for schools. Multi-tenancy is row-level: one Postgres database, every tenant-scoped table has a tenant_id column, and every tenant model uses a BelongsToTenant trait that adds a global scope:

trait BelongsToTenant
{
    protected static function bootBelongsToTenant(): void
    {
        static::addGlobalScope('tenant', function (Builder $q) {
            if ($tenantId = tenant('id')) {
                $q->where($q->getModel()->getTable().'.tenant_id', $tenantId);
            }
        });

        static::creating(function ($model) {
            $model->tenant_id ??= tenant('id');
        });
    }
}

Simple, effective. Every query a tenant's code makes is automatically scoped. Forget tenant_id? You physically cannot leak another tenant's data.

The feature

When a parent submits an issue through the public portal, we fire an IssueCreated event. A queued listener calls a Python microservice to analyze sentiment, then writes the result to an issue_ai_analysis row. Straightforward event → queued listener → DB write.

class IssueCreated
{
    public function __construct(public Issue $issue) {}
}

class PerformAiAnalysis implements ShouldQueue
{
    use InteractsWithQueue, SerializesModels;

    public function handle(IssueCreated $event): void
    {
        $score = Http::post(config('services.ai.url'), [
            'text' => $event->issue->description,
        ])->json();

        IssueAiAnalysis::updateOrCreate(
            ['issue_id' => $event->issue->id],
            ['sentiment' => $score['label'], 'confidence' => $score['confidence']]
        );
    }
}

Green tests. Works in tinker. Ships.

The crash

First real submission in production:

Illuminate\Database\Eloquent\ModelNotFoundException
No query results for model [App\Models\Issue].

But the issue exists. I can SELECT * FROM issues WHERE id = 189 and see it. The listener is being called with an event whose payload clearly references issue 189 — and then Laravel throws ModelNotFoundException trying to rehydrate it.

The trap

Here's the lifecycle of a queued listener:

Controller fires event(new IssueCreated($issue))
Laravel sees the listener is ShouldQueue, serializes the event via SerializesModels
The event is not serialized as the full Issue object — just App\Models\Issue + the primary key (189). This is the whole point of SerializesModels; it keeps payloads tiny and always fresh.
Worker boots, pulls the job, and calls (new Issue)->newQueryForRestoration(189)->firstOrFail() to rebuild the model.

Step 4 is where it dies. The worker process has no tenant context yet — it just started. Which means tenant('id') returns null. Which means BelongsToTenant's global scope generates:

SELECT * FROM issues
WHERE id = 189
  AND issues.tenant_id IS NULL   -- 💀
LIMIT 1

No rows. ModelNotFoundException.

The kicker: this never fails in sync mode (there's no serialization round-trip), and tests typically use Queue::fake() or sync drivers. The bug is invisible until you run a real queue worker against a real tenant request.

Laravel's stancl/tenancy does ship a QueueTenancyBootstrapper that restores tenant context on the worker — but it fires after SerializesModels::restoreModel() runs. Too late. The model is already dead.

The fix

Never put a tenant-scoped Eloquent model directly into a queued event or job. Store scalars, and initialize tenancy yourself inside handle():

class IssueCreated
{
    public function __construct(
        public readonly int    $issueId,
        public readonly string $tenantId,
    ) {}
}

class PerformAiAnalysis implements ShouldQueue
{
    public function handle(IssueCreated $event): void
    {
        // Tenant model itself is NOT tenant-scoped — safe to find()
        $tenant = \App\Models\Tenant::find($event->tenantId);
        tenancy()->initialize($tenant);

        try {
            $issue = Issue::findOrFail($event->issueId);

            $score = Http::post(config('services.ai.url'), [
                'text' => $issue->description,
            ])->json();

            IssueAiAnalysis::updateOrCreate(
                ['issue_id' => $issue->id],
                ['sentiment' => $score['label'], 'confidence' => $score['confidence']]
            );
        } finally {
            tenancy()->end();
        }
    }
}

And dispatch it with plain values:

event(new IssueCreated(
    issueId:  $issue->id,
    tenantId: tenant('id'),
));

Three rules I now enforce in code review:

Queued events and jobs store scalars only. No Eloquent models in constructor signatures.
Every handle() method that touches tenant data calls tenancy()->initialize() first and tenancy()->end() in finally.
The Tenant model itself must never use BelongsToTenant (otherwise you can't look it up without already having tenant context — chicken-and-egg).

Why `SerializesModels` is still the right default

The trap is real, but the trait exists for good reasons: tiny payloads, always-fresh data, no stale-attribute bugs. The fix isn't to abandon it — it's to recognize that the trait assumes a single global database context, which breaks the moment you add a tenant dimension.

If you're on single-tenant Laravel, keep passing models. If you're on multi-tenant Laravel with row-level isolation, scalars + manual tenancy()->initialize() are your friend.

How I caught it for good

I added a simple feature test that actually runs the queue:

it('processes queued listeners with correct tenant context', function () {
    $tenant = Tenant::factory()->create();
    tenancy()->initialize($tenant);

    Queue::connection('sync')->... // won't catch it
    // Use actual database queue driver:
    config(['queue.default' => 'database']);

    $issue = Issue::factory()->create();
    event(new IssueCreated(issueId: $issue->id, tenantId: $tenant->id));

    tenancy()->end(); // simulate worker boot with no context
    $this->artisan('queue:work --once --stop-when-empty')->assertExitCode(0);

    expect(IssueAiAnalysis::withoutGlobalScopes()
        ->where('issue_id', $issue->id)->exists())->toBeTrue();
});

Ending tenancy before the worker runs is the critical line — it reproduces what Supervisor does in production.

TL;DR: If you're using stancl/tenancy with row-level isolation and queued events/jobs, never put a tenant-scoped Eloquent model in a queued payload. Pass the ID + tenant ID as scalars, call tenancy()->initialize() in handle(). Your tests won't catch this — only a real queue worker will.

Source code: https://github.com/sharjeelz/eliflammeem-git — the pattern lives in app/Listeners/PerformAiAnalysis.php.

If this saved you 3 hours, drop a ⭐ on the repo. If you've hit it before, I'd love to hear your fix in the comments.