SchoolPalm Module Bridge

Architecture Overview

Understanding SchoolPalm’s modular architecture, the Module Bridge runtime engine, and the relationship between Core, SDK, and modules.

1. Introduction

SchoolPalm is a modular Educational Operating System (EOS) designed for schools. Unlike monolithic school management systems, SchoolPalm treats every feature—Students, Fees, Library, Attendance, etc.—as an independent module that can be installed, updated, or removed without affecting the core platform.

This architecture overview describes the four fundamental components of the SchoolPalm ecosystem, how they interact, and the design principles that ensure consistency, reliability, and developer productivity.

2. Ecosystem Components at a Glance

🔑 Key insight: Core and SDK never run modules directly. Both delegate to the Module Bridge, which provides a stable, contract-driven execution layer.

3. High-Level Architecture Diagram

    flowchart TB
    subgraph Production
        Core["SchoolPalm Core<br/>Production System"]
    end
    subgraph Development
        SDK["Module SDK<br/>Development Sandbox"]
    end
    subgraph SharedRuntime
        Bridge["Module Bridge<br/>Runtime Engine"]
    end
    subgraph Modules
        M1[Students Module]
        M2[Fees Module]
        M3[Library Module]
    end
    
    Core -->|uses| Bridge
    SDK -->|uses| Bridge
    Bridge -->|loads & executes| Modules
  

Data Flow Note

The Module Bridge is not a separate service. It is a library composed of PHP contracts and runtime bindings embedded into both the SchoolPalm Core and Module SDK.

However, conceptually, it acts as a shared abstraction layer that defines how modules are discovered, loaded, and executed across environments.

4. Detailed Component Descriptions

4.1 SchoolPalm Core (Production System)

Purpose: Runs the live school environment with real users, real data, and real integrations.

Responsibilities:

• Hosts the Module Bridge
• Discovers installed modules via registry
• Routes HTTP requests to module actions
• Manages infrastructure (database, storage, authentication)
• Executes lifecycle operations (install, upgrade, uninstall) using the bridge’s pipeline system

Does NOT do:

• Does not contain module-specific business logic
• Does not contain UI templates for modules
• Does not define module actions

All module-specific logic is delegated to individual modules.

4.2 Module Bridge (Core Runtime Engine)

The Module Bridge is the central contract and execution engine of the entire SchoolPalm ecosystem.

It provides:

Base Module Contract: Abstract class SchoolPalm\ModuleBridge\Core\Module that all modules must extend. Runtime Binding Mechanism: Uses class_alias to bind host’s concrete base module to the contract, enabling same module code to run in Core or SDK.

Action Resolver Contract: Defines route-to-action mapping. Relation Subsystem: Module declaration and hydration of relationships across environments.

Contract Query Builder: Fluent, Laravel-style query abstraction (ContractQueryBuilder) without tying to specific database/ORM. Installer Pipeline: Orchestrates validation, registration, snapshotting, asset preparation.

The bridge is not a standalone service—it is embedded in both Core and SDK, ensuring identical execution rules.

4.3 Module SDK (Development Sandbox)

Purpose: Safe, isolated environment for module development and testing. Responsibilities: Includes same Module Bridge version, simulates Core runtime, offers scaffolding/validation commands, never runs production data. Why not develop inside Core? Prevents accidental damage, allows rapid iteration, catches contract violations early.

4.4 Modules

Definition: Independent feature packages extending SchoolPalm’s functionality. Structure: Must extend Module abstract class and implement required methods (registerActions(), registerRelations()). Contents: UI components, action classes, business logic, migrations, config. Installation: Via bridge’s installer pipeline; can be enabled/disabled/removed without recompiling core. Examples: Students Management, Fees Collection, Library Circulation, Attendance Tracking.

5. Module Bridge Deep Dive

5.1 What the Bridge Guarantees

The Module Bridge is the execution contract between your modules and their host (Core or SDK).

It guarantees:

• Environment neutrality: modules don’t know whether they’re running in Core or SDK.
• Consistent orchestration: actions, relations, queries, and lifecycle steps follow the same rules everywhere.
• Contract-driven execution: contracts describe what to do; the host decides how to execute.

    flowchart TB
    subgraph Host[Host Application]
        Core[Core runtime] 
        SDK[SDK runtime]
    end

    subgraph Bridge[Module Bridge]
        Bind[Runtime binding]
        Resolve[Action resolution]
        Relate[Relation hydration]
        Query[Contract query forwarding]
        Install[Installer pipeline]
    end

    Modules[Modules] --> Bind --> Resolve --> Relate --> Query --> Modules

    Core -->|uses| Bridge
    SDK  -->|uses| Bridge
  

5.2 Runtime Binding via class_alias

All modules extend SchoolPalm\ModuleBridge\Core\Module.

Each host binds its concrete base implementation to the bridge contract:

SchoolPalm\ModuleBridge\Core\Module

use SchoolPalm\ModuleBridge\Support\Bridge;
Bridge::bind(ConcreteBaseModule::class);

The bridge uses class_alias so the module is compiled once, but executed against the correct base implementation in Core or SDK.

5.3 Action Resolution Contract

Routes map to module actions through an action resolver contract:

interface ActionResolver {
    public function resolve(string $moduleName, string $actionPath): Action;
}

5.4 Execution Responsibility Model (Core Principle)

A key design principle of the Module Bridge is strict separation of responsibilities:

• Core and SDK provide their own infrastructure implementations
• Modules remain fully environment-agnostic
• The Module Bridge ensures consistent orchestration across both environments

This guarantees that modules do not depend on:

• database systems
• runtime environment (Core vs SDK)
• infrastructure implementation details

Instead, modules rely entirely on the Bridge contract layer.

5.5 Relation Subsystem

The Module Bridge provides a declarative relationship system so modules can define cross-module relationships in a consistent way.

Example: Relation Definition

class StudentModule extends Module {
    public function registerRelations(RelationRegistry $registry): void {
        $registry->hasMany(FeeModule::class, 'student_id');
    }
}

Bridge builds a unified registry and hydration engine, working identically in Core (SQL) and SDK (SQLite/in-memory).

5.6 Contract Query Builder

Modules express intent using ContractQueryBuilder.

$query = ContractQueryBuilder::for(StudentModule::class)
    ->where('grade', '>=', 10)
    ->with('fees')
    ->orderBy('name');

$students = $query->get();

Query stores only intent. Execution is delegated to the host’s querySearch service—decoupling modules from the underlying ORM while keeping fluent syntax.

Query Execution Model

• modules use a contract-based query abstraction layer
• the Bridge does NOT execute database queries directly
• the Bridge forwards query definitions to the host application
• the host executes the actual database operations

This ensures:

• database independence at module level
• consistent query behavior across environments
• separation between domain logic and infrastructure

5.7 Installer Pipeline (Mermaid Diagram)

    flowchart LR
    V[Validation] --> R[Registration] --> DB[Database] --> A[Asset Publishing] --> S[Snapshot]

    P[Installer Pipeline in Module Bridge] --> V
  

The installer pipeline orchestration lives in the bridge (src/Pipeline/*). Core and SDK therefore process module installation identically.

6. Runtime Execution Flow (Action System)

When a user makes a request to SchoolPalm Core:

    sequenceDiagram
    participant User
    participant Core as SchoolPalm Core
    participant Bridge as Module Bridge
    participant Module as Specific Module
    
    User->>Core: GET /students/list?grade=10
    Core->>Bridge: Route to module & action
    Bridge->>Bridge: Resolve module (e.g., Students)
    Bridge->>Module: Instantiate module
    Bridge->>Module: Call action "list" with params
    Module->>Bridge: Use ContractQueryBuilder
    Bridge->>Core: Delegate query execution
    Core-->>Bridge: Return hydrated data
    Bridge-->>Module: Return results as contracts
    Module-->>Bridge: Return view / response
    Bridge-->>Core: Finalise HTTP response
    Core-->>User: HTML / JSON response
  

Bridge resolves module and action but contains no business logic.

Modules use query abstraction; host executes actual database queries. Relations hydrated by bridge before module receives results.

7. Module Development with the SDK

The Module SDK replicates Core’s runtime environment, enabling developers to:

Scaffold a module: php artisan module:make Students.

Implement actions, relations, UI inside module directory. Test locally: http://sdk.test/students/list. Validate contract: php artisan module:validate. Package module (ZIP/PHAR).

Because SDK uses the identical Module Bridge library, any module working in SDK works identically in Core.

8. Registry and Pipeline Systems

8.1 Dynamic Module Registry

Stores installed module names, versions, actions, relations, timestamps, snapshots. Registry API identical across Core and SDK, though backends may differ (database vs file).

8.2 Lifecycle Pipeline

Install → Validate → Register → Migrate → Publish Assets → Snapshot
Upgrade → Validate version → Apply upgrade script → Update registry
Uninstall → Validate dependencies → Revert snapshot → Remove registry entry

Orchestrated by InstallerPipeline; host provides concrete implementations for file system, database, asset publishing.

9. Benefits for Stakeholders

10. Conclusion

SchoolPalm’s architecture is built on a strict separation of concerns across its core components:

• SchoolPalm Core provides the production infrastructure that powers real-world school operations.
• Module Bridge provides the stable runtime contract and execution engine that connects all parts of the ecosystem.
• Module SDK provides a safe and isolated development sandbox for building and testing modules.
• Modules provide the actual business functionality and feature implementations.

The Role of the Module Bridge

The Module Bridge is the linchpin of the entire architecture.

It ensures that modules remain:

• Environment-independent
• Consistently executed across systems
• Properly resolved at runtime
• Structurally compliant via shared contracts

By abstracting and managing key system responsibilities such as:

• Runtime binding
• Action resolution
• Relation handling
• Contract-based queries
• Lifecycle pipeline orchestration

the Module Bridge guarantees that modules are fully portable between development and production environments.

Final Impact

This architecture achieves several critical outcomes:

• Reduces integration and deployment bugs
• Accelerates module development and testing
• Ensures behavioral consistency between SDK and Core
• Enables independent evolution of the platform and modules
• Prevents ecosystem fragmentation as the system scales