When we first conceptualized Al-Maktab, our vision was to build a system for a single madrasa. But within three weeks of announcing the project, we received inquiries from three different types of organizations:

  • An independent residential madrasa in Sylhet with 350 students.
  • A charitable Waqf foundation operating twelve distinct institutions across northern Bangladesh.
  • A regional Islamic education coordination council overseeing fifty-two affiliated village maktabs.

Each of these organizations had radically different scales, budgets, and operational capabilities. The Waqf foundation wanted a unified dashboard where their executive board could monitor total fee collections across all twelve campuses. The independent madrasa wanted full autonomy with zero shared data. And the village maktabs needed only attendance and SMS notifications, with zero interest in complex accounting or CCTV streaming.

We realized immediately: Al-Maktab could not be a traditional single-tenant script. It had to be a true multi-tenant SaaS platform.

Why Multi-Database Isolation Was Non-Negotiable

In modern web development, multi-tenancy is usually implemented in one of two ways:

  1. Single Database (Row-Level Multitenancy): All tenants share the exact same database tables. Every query includes WHERE tenant_id = 42.
  2. Multi-Database (Physical Separation): Every tenant institution gets its own completely separate, dedicated database schema.

Many SaaS startups choose row-level multitenancy because it is cheaper and simpler to maintain. But for Islamic institutions in Bangladesh, this was not merely an architectural debate—it was an absolute trust requirement.

A madrasa principal entrusts his software provider with deeply sensitive community information: student residential addresses, parent financial statuses, confidential staff salaries, and donation ledgers. If a software bug or an improperly scoped query accidentally exposes Madrasa A's payroll or student files to Madrasa B's administrator, the platform is finished.

We chose the multi-database architecture powered by spatie/laravel-multitenancy. Each madrasa operates inside its own isolated MySQL database. When an HTTP request hits darul-uloom.al-maktab.com:

// Spatie Multitenancy Execution Lifecycle
[Inbound Request: https://sylhet-hifz.al-maktab.com/admin]
       │
       ▼
TenantResolverMiddleware
  ├── Inspects Host header (sylhet-hifz)
  ├── Queries Central Database: 'tenants' table
  ├── Finds Tenant model (ID: 14, DB: 'tenant_sylhet_hifz')
  │
  ▼
TenantSwitchDatabaseConnectionTask
  ├── Dynamically switches 'tenant' DB connection config
  ├── Purges PDO statement cache for previous tenant
  └── Binds active Tenant instance to Laravel Service Container
       │
       ▼
Application Code Runs Safely Inside Isolated Database

With this architecture, even if a junior developer writes a raw database query that forgets a filter clause, it is mathematically impossible to leak data from another madrasa. The connection physically points to a database that contains only that institution's records.

Per-Tenant Dynamic Feature Flags

Al-Maktab features 35 comprehensive production modules: from Hifz tracking, biometric attendance, and fee management to CCTV live monitoring, transport routes, and AI diagnostic reports.

However, throwing 35 complex menus at a small village maktab is poor software design. They will feel overwhelmed, confused, and alienated. Conversely, a large 1,000-student residential campus requires every single module operating at full throttle.

We implemented a high-performance, cached feature flag system. In the Super Admin panel, the platform administrator can toggle any of the 35 modules on or off with a single switch. When a module (such as cctv_streaming or hostel_gate_pass) is disabled for a tenant:

  • The corresponding navigation items disappear from the Filament admin panel.
  • All associated web routes are automatically gated behind a 404 Not Found response.
  • Scheduled background cron tasks skip that tenant during daily processing.

The 30-Second Tenant Onboarding Pipeline

In our early tests, provisioning a new tenant required manual database creation, running artisan migration scripts, and creating seed records via SSH. It took twenty minutes of developer time per madrasa.

We fully automated this workflow through an asynchronous job queue. Today, when an institution registers on Al-Maktab:

  1. The system allocates an isolated MySQL database schema (tenant_{subdomain}).
  2. It executes all migrations across the fresh database in a background process.
  3. It seeds default roles (Muhtamim, Ustad, Accountant, Warden, Guardian) and standard permission sets.
  4. It populates the 30+ default Bengali SMS notification templates.
  5. It generates the initial administrator credentials and sends an automatic welcome SMS with login instructions directly to the principal's phone.

The total elapsed time from registration submission to the principal logging into his fully branded dashboard is under 28 seconds.

Zero-Downtime Multi-Database Migrations

The single greatest operational challenge of multi-database architecture is running schema updates. When we ship a new feature that adds a column to the hifz_session_logs table, that migration must run across dozens of individual tenant databases without causing service interruptions.

We wrote custom deployment commands that parallelize migration execution using worker pools, automatically skipping inactive tenants and reporting detailed telemetry to Slack if any individual database encounters a schema lock. This guarantees that whether we are serving ten madrasas or ten thousand, our platform evolves cleanly and reliably.

Mustafa Kamal Hossain

Mustafa Kamal Hossain

Founder & Principal Engineer at Manfi. Passionate about Laravel, SaaS architecture, and high-performance engineering.