Skip to content

The SchoolPalm System

This document explains what SchoolPalm is, how it is structured, what it does at the system level, and how vendor-authored course/module packages are integrated.

1) What SchoolPalm is

SchoolPalm is an education platform that supports multiple schools (e.g., primary/secondary/tertiary) using a single codebase.

From the platform perspective, the system provides:

  • role-based application experiences (admin/staff/student/guardian)
  • tenant separation so each school is isolated
  • configuration-driven curriculum/academic structure
  • an ecosystem mechanism to run vendor-authored course modules (packaged as versioned “snapshots”)

2) System architecture (high-level)

2.1 Multi-tenancy (school isolation)

SchoolPalm is built around tenant isolation using the stancl/tenancy approach.

Key aspects:

  • Tenancy is identified using domain/subdomain/path middleware.
  • When a tenant request is initialized, tenant-scoped Laravel configuration, database connections, filesystem roots, cache, and routes become tenant-aware.

Relevant config:

  • config/tenancy.php
  • app/Providers/TenancyServiceProvider.php

Outcome:

  • multiple schools can operate on the same platform without mixing data.

2.2 Core platform design

At runtime, SchoolPalm separates:

  • central platform concerns (identity, tenant bootstrap, module registry/runtime integration)
  • tenant/domain concerns (the actual school data and workflows)

The main user-facing experience is driven through:

  • Laravel controllers/routes
  • a JavaScript frontend rendered via Inertia (and the Vite build pipeline)

2.3 Storage and scaling strategy

The architecture assumes that:

  • large uploaded content should be stored as files (filesystem/external object storage), while the database holds references/metadata
  • historical/archive data can be handled with different strategies to keep the active workload performant

3) What SchoolPalm does (core functions)

3.1 Role-based portals

SchoolPalm exposes different portal experiences depending on the authenticated user role.

At the routing level, most web application routes are protected with auth middleware and then organized by controllers (Portals, Staff, Guardian, Student, Bursar, etc.).

3.2 Curriculum + academic configuration

The platform exposes configuration such as:

  • supported academic levels
  • curricula definitions
  • role definitions

This configuration is used both for the platform UI and for SDK/module compatibility.

3.3 Running vendor-authored courses/modules

SchoolPalm supports third-party vendor modules as versioned packages.

4) Vendor module system: snapshots & module bridge

4.1 What “module snapshots” are

Vendor modules are integrated through a snapshot mechanism:

  • each vendor module is identified by a module_key
  • vendors publish multiple versions
  • SchoolPalm resolves a specific snapshot package (zip) from a registry
  • module snapshots include their own manifest and packaged implementation

The snapshot registry is stored at:

  • storage/app/private/modules/snapshots/registry.json

Example registry shape:

  • module namespace → module key → version → { file, path, created_at }

4.2 Snapshot delivery APIs

SchoolPalm provides SDK endpoints to retrieve platform config and to download module snapshots.

Routes:

  • routes/central-api.php

Controller:

  • app/Http/Controllers/Api/SdkApiController.php

Endpoints:

  • GET /sdk/config/{item?}
    • returns platform config items (levels/curricula/roles) and SDK metadata
  • GET /sdk/modules/{module_key}/{version}/snapshot
    • looks up snapshot metadata using SnapshotRegistry
    • validates path + filename
    • returns the snapshot zip for that module/version

4.3 Runtime binding for snapshot code

Snapshot modules can include backend contracts/services that are registered when a module’s provider loads.

One example is the vendor snapshot provider pattern:

  • storage/app/private/modules/snapshots/Unnovatebrains/Common/Student/Backend/Providers/SnapshotServiceProvider.php

This provider:

  • loads a module manifest (snapshot.manifest.json)
  • registers bindings for interfaces/contracts and their corresponding services using deterministic filesystem discovery

5) Tech stack (as used in this project)

Backend

  • PHP (Laravel)
  • Laravel Framework: controllers/routes, service providers, app bootstrapping
  • Inertia (inertiajs/inertia-laravel): server-driven pages with JS frontend integration
  • Fortify / authentication support (as present via dependencies)
  • Tenancy: stancl/tenancy for multi-tenant isolation
  • Module bridge: schoolpalm/module-bridge for snapshot/module integration

Relevant endpoints are implemented under:

  • routes/*.php and app/Http/Controllers/*

Frontend

  • Vite + Vue + Inertia
  • Tailwind + supporting UI libraries (Quasar, etc.) via package.json

Build & runtime commands

The project defines a combined dev script (php artisan serve + queue + Vite build/dev).

6) Where to look next (project navigation)

  • schoolpalm_architecture.md — architecture notes
  • config/tenancy.php — tenant identification and bootstrappers
  • app/Providers/TenancyServiceProvider.php — tenant bootstrap wiring
  • routes/central-api.php — SDK endpoints
  • app/Http/Controllers/Api/SdkApiController.php — config and snapshot download logic
  • config/sdk.php — module/snapshot paths and registry location
  • storage/app/private/modules/snapshots/registry.json — snapshot registry data

7) Summary (developer-oriented)

SchoolPalm is a Laravel/Inertia education platform that uses tenant isolation for school separation and provides an SDK-facing integration mechanism for vendor-authored course modules. Vendor content is distributed as versioned snapshot packages resolved via a registry and delivered through /sdk/* endpoints, with providers capable of registering module contracts/services into the platform runtime.