PedOS Plugin SDK Wiki

Architecture Overview

PedOS is the LearnAdapt app runtime for educational plugins. A PedOS plugin is installed only after it declares metadata, permissions, package files, runtime surfaces, and evidence boundaries. The installed app runs at /plugin/{slug} inside the LearnAdapt shell.

Two Build Paths

Developers and non-coders use different creation paths, but both must produce the same SDK-compliant package.

PedOS 1.1 Lumina Runtime Matrix

PedOS 1.1 Lumina is the platform and SDK release. PedOS App Runtime v2 is the installed-app compatibility layer inside that release. Agentic Studio and developer ZIP submissions must stay inside this matrix unless a future PedOS version explicitly adds a new option.

Deterministic Preflight Agent

Agentic Studio runs a deterministic preflight helper before the generative agent team starts. This helper does not call an AI provider and does not spend LearnAdapt credits. It supports both guided-brief and free-form-prompt authoring, checks whether the request is specific enough, normalizes it into the current PedOS 1.1 Lumina / App Runtime v2 matrix, and verifies that the account has enough LearnAdapt credits to cover the high-end build estimate.

Agentic Studio Team

The user's prompt is treated as the client brief. The agents must behave like a professional development team, not like a demo generator.

1. Product/SRS analyst extracts users, non-goals, constraints, evidence boundary, and acceptance criteria.
2. Pedagogical designer, UX designer, and solution architect work in parallel after the brief stabilizes.
3. Full-stack developer and data/evidence engineer build the package and the minimum data contract.
4. QA/security reviewer blocks unsafe code, broken runtime bridge, over-collection, raw technical jargon, and static demos.
5. Release manager prepares metadata, icon, screenshots, version, support notes, and admin review notes.

Package Structure

my-plugin/
  manifest.json
  php/
    init.php
  js/
    main.js
  css/
    style.css
  migration.sql
  assets/
    icon.png
  screenshots/
  README.md
  LICENSE

• manifest.json is required for metadata, permissions, evidence category, runtime surfaces, and review status.
• php/init.php is the guarded PHP entry point. It renders only when the current route is /plugin/{slug}.
• js/main.js and css/style.css must be slug-scoped and loaded from /plugins/{slug}/current/.
• README.md, icon, and screenshots are required for a professional directory listing.
• migration.sql is optional and must use slug-prefixed, idempotent tables.

manifest.json

The manifest is the app contract. It should be explicit enough for admin review, directory discovery, installation, runtime permission checks, and future versioning.

{
  "name": "Quick Check Exit Ticket",
  "slug": "quick_check_exit_ticket",
  "version": "1.0.0",
  "description": "A quick end-of-lesson check with confidence and follow-up planning.",
  "category": "Formative Assessment",
  "author": { "name": "Developer or Studio Builder" },
  "telemetry": {
    "profile": "learning_evidence",
    "data_classes": ["interaction", "learning_evidence"],
    "requires_learning_data": true,
    "requires_bkt_ready": true
  },
  "runtime": {
    "version": "pedos_app_runtime_v2",
    "launch": { "display": "app_shell", "route": "/plugin/quick_check_exit_ticket" },
    "permissions": [
      "context:read",
      "settings:read",
      "settings:write",
      "storage:user",
      "telemetry:learning_evidence",
      "analytics:read"
    ],
    "host_surfaces": ["standalone_app", "dashboard_my_apps", "settings_panel", "analytics_panel"]
  }
}

PedOS Runtime APIs

Installed apps should use the host runtime instead of creating plugin-local APIs.

Hook System

PedOS exposes a PHP hook pattern for lifecycle and approved platform extension points.

<?php
if (!class_exists('LearnAdapt_Hook_System')) {
    return;
}

LearnAdapt_Hook_System::add_action('pedos_plugin_my_plugin_install', function ($context) {
    // Initialize approved defaults or run idempotent setup.
});

$path = parse_url($_SERVER['REQUEST_URI'] ?? '', PHP_URL_PATH);
if ($path !== '/plugin/my_plugin') {
    return;
}
?>
<section class="my_plugin-app" data-plugin-slug="my_plugin">
  <h1>My Plugin</h1>
</section>

Evidence and xAPI

Every app chooses the minimum evidence category needed for its purpose. User-facing labels stay human-readable; internal profiles stay in admin/developer/research surfaces.

Security Model

• No eval, exec, shell_exec, system, passthru, proc_open, assert, or unsafe deserialization.
• No hidden external network access unless explicitly approved in the manifest.
• No plugin-local mutation endpoints for settings, storage, or telemetry.
• No learner/teacher-facing raw JSON, xAPI statements, internal profile tokens, or developer diagnostics.
• All output must escape user-provided content.
• All SQL migrations must be reviewed, idempotent, and slug-prefixed.

Submission and Review Lifecycle

1. Build package through Agentic Studio or developer ZIP upload.
2. Run SDK schema and package validation.
3. Preview inside the sandbox/runtime shell.
4. Iterate until the app is useful, interactive, and human-facing.
5. Submit to directory review.
6. Admin validates route, assets, permissions, evidence category, UI copy, screenshots, and runtime behavior.
7. Approved app appears in Plugins Directory.
8. User installs into My Apps and opens the app in the PedOS shell.
9. Approved evidence is captured and shown through app analytics.

Database Conventions

Plugins should use platform APIs where possible. If durable tables are approved, migrations must use strict namespacing.

CREATE TABLE IF NOT EXISTS my_plugin_attempts (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  user_id INT NOT NULL,
  item_key VARCHAR(120) NOT NULL,
  result_success TINYINT(1) DEFAULT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_my_plugin_user (user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Frontend Conventions

• Use slug-prefixed classes and IDs.
• Use buttons, inputs, sliders, menus, and tabs that match LearnAdapt styling.
• Show plain-language data notices when evidence is collected.
• Provide empty, loading, error, success, and review states.
• Do not expose internal diagnostics to educators or learners.

Testing and Validation

Every app must pass the same evidence-backed test path before it is considered real.

1. Route check: /plugin/{slug} returns a valid app shell.
2. Asset check: CSS and JS load from /plugins/{slug}/current/.
3. Interaction check: controls respond and update UI state.
4. Telemetry gate: anonymous writes are rejected; installed-user writes follow the approved profile.
5. Analytics check: user-facing analytics summarize activity without raw technical logs.
6. Review check: admin can inspect technical details separately.

Minimal Plugin Example

<?php
$pluginSlug = 'quick_check_exit_ticket';
$path = parse_url($_SERVER['REQUEST_URI'] ?? '', PHP_URL_PATH);
if ($path !== '/plugin/' . $pluginSlug) {
    return;
}
?>
<section class="quick_check_exit_ticket-app" data-plugin-slug="quick_check_exit_ticket">
  <h1>Quick Check Exit Ticket</h1>
  <label>What is one thing you understand now?</label>
  <textarea class="quick_check_exit_ticket-response"></textarea>
  <button class="quick_check_exit_ticket-submit">Submit check</button>
</section>