Project Jarvis Addon Guide

Welcome to the developer guide for Project Jarvis. This document explains how the modular addon engine works and provides a step-by-step tutorial for creating new skills for the Jarvis AI.

Core Concepts

The Jarvis backend is built on a simple but powerful principle: a lean **Core** provides essential services, and all specific features (or "skills") are self-contained **Addons**. The brain that manages this is the AddonManager class.

The AddonManager loads all "active" addons from the database when it starts. You can toggle addons on or off from the admin panel.
When a message is received (from the app, chat, etc.), the manager passes it to each active addon one by one, in order of priority.
The first addon that recognizes the message and returns a response wins. If an addon crashes, it is safely skipped and the error is logged.

Addon File Structure

Every addon is a folder inside the main /addons/ directory. A typical addon has the following files:

install.php (Required): A script that runs once when you install the addon from the admin panel. Its job is to create any necessary database tables or settings.
uninstall.php (Optional but Recommended): A script that runs when you uninstall an addon. It's responsible for cleaning up any database tables or settings created during installation.
module.php (Required): This is the addon's "brain." It contains the main logic for handling messages.
admin.php (Optional): If this file exists, a "Settings" button will automatically appear for the addon in the admin panel, linking to this page.
api.php (Optional): A dedicated API endpoint for the addon that the mobile app can call directly for data (e.g., fetching calendar events).
task.php (Optional): A script that can be run on a schedule by the master cron job.

Tutorial: Creating a "Good Dog" Addon

Let's create a simple skill. When a user says something nice about a dog, Jarvis will respond positively. This demonstrates the basic addon lifecycle.

Step 1: Create the Folder and Files

In your file manager, go to /jarvis/addons/ and create a new folder named good_dog. Inside it, create `install.php`, `uninstall.php`, and `module.php`.

Step 2a: The Installation Script

This addon is simple and doesn't need any database tables. The install script just needs to exist to register the addon. Paste this into /addons/good_dog/install.php:

<?php
// /addons/good_dog/install.php

function good_dog_install(PDO $pdo) {
    // This addon doesn't need any database tables or settings.
    // We just return true to indicate a successful installation.
    return true;
}
?>

Step 2b: The Uninstallation Script

To be a good citizen in the Jarvis ecosystem, an addon should clean up after itself. This is handled by /addons/good_dog/uninstall.php. The function name must be **`addon_folder_name_uninstall`**.

<?php
// /addons/good_dog/uninstall.php

function good_dog_uninstall(PDO $pdo) {
    // If we had created tables, we would drop them here.
    // Example: $pdo->exec("DROP TABLE IF EXISTS good_dog_data;");
    
    // Return true to signal that cleanup was successful.
    return true;
}
?>

Step 3: The Core Logic (The Brain)

This is where the magic happens. The function name must be **`addon_folder_name_handle_message`**. It receives the message and decides whether to act. Paste this into /addons/good_dog/module.php:

<?php
// /addons/good_dog/module.php

function good_dog_handle_message(array $message, PDO $pdo, AddonManager $addonManager) {
    // Get the user's message and make it lowercase for easy checking.
    $user_message = strtolower($message['text']);
    
    // Define the keywords we're looking for.
    $keywords = ['dog', 'puppy', 'good boy'];
    
    // Check if any of our keywords are in the user's message.
    $keyword_found = false;
    foreach ($keywords as $keyword) {
        if (strpos($user_message, $keyword) !== false) {
            $keyword_found = true;
            break; // Stop looking once we find one
        }
    }
    
    // If we found a keyword, we will handle this message.
    if ($keyword_found) {
        // Return a response in the required format.
        // The AddonManager will stop and send this reply.
        return ['type' => 'text', 'content' => 'Dogs are the best!'];
    }
    
    // If our keywords were not found, return null.
    // The AddonManager will then pass the message to the next addon.
    return null;
}
?>

Step 4: Install and Test

Go to your Jarvis Admin Panel, navigate to **Skills (Addons)**, and click **Install** on your new "Good dog" skill. You can now activate or deactivate it with the toggle. To test, go to the chat and say "I saw a cute puppy today." Jarvis will respond correctly!