Skip to content

SchoolPalm Module

This document describes what a SchoolPalm module is and the typical structure of a module package.

This particular README lives inside a concrete module package folder; treat it as a reference template. The goal is to explain the generic module structure so developers can build new modules consistently.

1) What is a SchoolPalm module?

A SchoolPalm module is a self-contained unit of functionality that can be:

  • discovered/installed by the SchoolPalm platform
  • integrated into the runtime via a service provider
  • exposed through:
    • SDK Bridge services (internal APIs)
    • menus/routes/UI entries
    • events (to let other modules react)
  • shipped with:
    • contracts (public API)
    • services (business logic)
    • DTOs (data contracts)
    • migrations/schemas/models (persistence)

Snapshot vs Package (important)

SchoolPalm uses two packaging styles:

  1. Snapshots (used for SDK testing/versioned bundles)

    • stored under storage/app/private/modules/snapshots/...
    • described by snapshot.manifest.json

  2. Packages (“real” installable module code)

    • stored under app/Custom/Packages/...
    • described by manifest.json

This folder is a Package implementation.

2) High-level structure (this package)

This module lives under:

  • app/Custom/Packages/Unnovatebrains/Common/Student/

Key files:

  • manifest.json — identity, SDK compatibility, menu/actions, provider binding, entry points
  • Backend/ — backend implementation of contracts/services/DTOs/events/migrations

Mermaid: module composition 

    flowchart LR
  M[manifest.json] --> P[Service Provider]
  P --> C[Contracts]
  P --> S[Services]
  S --> D[DTOs]
  S --> E[Events]
  M --> U[Menus/Routes (UI entries)]
  M --> DB[Migrations/Schema (persistence)]

3) manifest.json — what it tells SchoolPalm about the module

The manifest is the source of truth for the module’s metadata and integration points, such as:

  • module_key — stable identifier (e.g. unnovatebrains.common.student)
  • namespace — PHP namespace root for the module backend
  • sdk — required SDK name/version compatibility
  • provider.entry — the service provider class SchoolPalm uses to wire the module
  • menus — menu entries and route strings
  • actions — callable routes for module actions
  • migrations — migration directory and whether to run on install/update
  • models — model namespace/autoload settings
  • events — event classes shipped by the module
  • provides / requires.modules — what the module exports and what it depends on

4) Backend structure (Backend/)

Typical backend folders in this module 

Backend/
  Contracts/
    StudentContract.php

  DTOs/
    StudentData.php

  Events/
    Event.php
    StudentCreatedEvent.php

  Facades/
    StudentService.php (SDK-facing façade)

  Models/
    Student.php (Eloquent model)

  Providers/
    UnnovatebrainsCommonStudentServiceProvider.php

  Services/
    StudentService.php (implements the contract)

  Database/
    migrations/
      <timestamp>_create_students_table.php
    Seeders/
      UnnovatebrainsCommonStudentStudentsSeeder.php

Mermaid: internal call flow 

    sequenceDiagram
  participant Caller as SchoolPalm SDK Bridge
  participant Service as StudentService
  participant DTO as StudentData
  participant Model as Student (Eloquent)
  participant Event as StudentCreatedEvent

  Caller->>Service: store(StudentData)
  Service->>Model: create/save()
  Service->>DTO: map Model -> DTO
  Service->>Event: dispatch(dto)
  Event-->>Observers: notify listeners
  Service-->>Caller: StudentData

5) Contracts → Services wiring (service provider)

This package includes a provider:

  • Backend/Providers/UnnovatebrainsCommonStudentServiceProvider.php

It uses a convention-based binding mechanism:

  • it scans Backend/Contracts for contract interfaces
  • for each XContract, it binds it to XService in Backend/Services

This gives you:

  • a stable SDK/API surface (contracts)
  • a replaceable implementation (services)

Mermaid: binding 

    flowchart TD
  P[UnnovatebrainsCommonStudentServiceProvider] --> ScanC[Scan Contracts]
  ScanC --> B1[bind StudentContract => StudentService]

6) DTOs & Events

DTOs (Backend/DTOs/StudentData.php)

DTOs define the shape of data exchanged across the module boundary.

Events (Backend/Events/*)

Events are emitted by services to trigger cross-module side effects. For example:

  • StudentCreatedEvent is dispatched after storing a student.

7) Persistence (migrations/seeders)

This module ships database migrations under:

  • Backend/Database/migrations/

The manifest config specifies migration behavior:

  • run_on_install: true
  • run_on_update: true

Seeders are also shipped under:

  • Backend/Database/Seeders/

8) UI/Menu integration

The module manifest declares menu items and route paths under menus. After installation, the platform uses those definitions to render:

  • admin navigation entries
  • module-specific pages

9) Quick checklist for developers

When implementing/extending a module, ensure:

  • manifest.json identity (module_key, vendor, namespace, sdk)
  • contracts in Backend/Contracts
  • service implementation in Backend/Services matching naming convention (XContract → XService)
  • DTOs in Backend/DTOs
  • event dispatchers in Backend/Events
  • migrations under Backend/Database/migrations

Appendix: main entry points in this package

  • manifest.json
  • Backend/Providers/UnnovatebrainsCommonStudentServiceProvider.php
  • Backend/Contracts/StudentContract.php
  • Backend/Services/StudentService.php
  • Backend/DTOs/StudentData.php
  • Backend/Events/StudentCreatedEvent.php
  • Backend/Database/migrations/*