App Droplet Object Overview

The Reasoning Flows component for developing, managing, and publishing web applications and API services.

Purpose

The App Droplet Object is an environment inside Reasoning Flows for building and publishing web applications and API services in PHP or Python. It connects to configured App Droplet servers, so developers can write, test, and deploy applications without leaving the ARPIA platform.

It's the step that takes a Reasoning Flows project from workflow to a running service that other systems or users can reach.

Where It Fits in Reasoning Flows

Extract & Load ingests and structures source data.
Repository Tables register datasets for reuse.
Transform & Prepare cleans and enriches data.
AI & Machine Learning builds and trains predictive or generative models.
Visual Objects deliver insights through dashboards, reports, APIs, or notebooks.
Data Models (Nodes) define the meaning and structure of business entities.
AI Apps combine and orchestrate components into a deployable project.
App Droplet Object publishes applications to servers for production use.

Role: The App Droplet Object turns Reasoning Flows projects into live web or API services hosted on connected servers.

Key Capabilities

Built-in code editor. Develop multi-file applications in the browser, with syntax highlighting and project organization.

Server integration. Connects to preconfigured App Droplet servers for deployment.

Project management. Supports structured file organization and dependency management.

Terminal access. A built-in SSH terminal for command-line work on the connected server.

Publishing. Deploys the project's files to a selected server. [VERIFY: is publishing versioned, with rollback, or does it overwrite files with no history? See Publishing Configuration.]

Development Environments

When you create an App Droplet Object, select the programming language and runtime.

PHP Environment

Runtime: PHP 8.x [VERIFY: exact minor version. PHP 8.0 and 8.1 no longer receive security updates.]

Best for:

Traditional web applications
Dynamic sites and backend interfaces
Integration with existing PHP frameworks

Available extensions:

Database: mysqli, PDO, sqlite3, redis
HTTP & network: curl, ftp, openssl
Image processing: gd, imagick
Data: json, xml, SimpleXML, zip
Other: mbstring, imap

Database connectivity:

<?php
require_once('datakubes-connect.php');
$dk_conn = dk_connect();  // Returns a mysqli instance

$stmt = $dk_conn->prepare(
    "SELECT product_name, revenue FROM sales_gold WHERE region = ?"
);
$stmt->bind_param('s', $region);
$stmt->execute();
$result = $stmt->get_result();

while ($row = $result->fetch_assoc()) {
    echo $row['product_name'] . ": " . $row['revenue'] . "\n";
}

$stmt->close();
$dk_conn->close();

Python Environment

Runtime: Python 3.x [VERIFY: exact minor version]

Best for:

APIs and data-driven microservices
ML model endpoints
Web integrations with Flask or FastAPI
Serving Reasoning Flows outputs

Database connectivity:

import dkconnect

conn = dkconnect.connect()  # Returns a standard DB-API connection
try:
    cursor = conn.cursor()
    cursor.execute(
        "SELECT product_name, revenue FROM sales_gold WHERE region = %s",
        (region,),
    )
    for product_name, revenue in cursor.fetchall():
        print(f"{product_name}: {revenue}")
    cursor.close()
finally:
    conn.close()

The connection helpers keep their original names (datakubes-connect.php, dkconnect) from when Data Models were called Kubes.

Interface Overview

1. Code Area

A lightweight IDE for creating, editing, and organizing project files, designed for web and API development.

2. Publishing Configuration

Defines where and how the application is deployed:

Select a target App Droplet server.
Once a target is set, the Publish button becomes active.
Publishing replaces every file in the target directory with the current version.

Warning: Because publishing overwrites the target directory, always publish to a staging server first, and commit your code to version control before you publish to production.

3. Terminal

A built-in SSH terminal connected to the App Droplet server. Use it to run commands, inspect logs, manage dependencies, and work with the environment directly.

Terminal access to a production server is privileged access. Limit it to the people who need it. [VERIFY: which roles get terminal access, and are terminal sessions logged?]

Typical Use Cases

API services that expose Reasoning Flows outputs, such as model predictions or prepared datasets
Micro frontends or lightweight dashboards for data visualization
FastAPI or PHP applications that automate workflows
Web endpoints that integrate external services or trigger actions
RESTful APIs that serve data from Repository Tables

Example: Building a Prediction API

These examples omit authentication for brevity. Before you expose an endpoint outside your network, add authentication (for example, API keys or tokens) and restrict what data it returns.

Python (FastAPI)

import dkconnect
from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/predictions/{product_id}")
def get_prediction(product_id: int):
    conn = dkconnect.connect()
    try:
        cursor = conn.cursor()
        cursor.execute(
            "SELECT product_name, predicted_sales, confidence "
            "FROM sales_forecast_optimized WHERE product_id = %s",
            (product_id,),
        )
        row = cursor.fetchone()
        cursor.close()
    finally:
        conn.close()

    if row is None:
        raise HTTPException(status_code=404, detail="Product not found")

    return {
        "product_name": row[0],
        "predicted_sales": row[1],
        "confidence": row[2],
    }

PHP (REST endpoint)

<?php
require_once('datakubes-connect.php');
header('Content-Type: application/json');

$product_id = (int)($_GET['product_id'] ?? 0);
if ($product_id <= 0) {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid product_id']);
    exit;
}

$dk_conn = dk_connect();
$stmt = $dk_conn->prepare(
    "SELECT product_name, predicted_sales, confidence
     FROM sales_forecast_optimized WHERE product_id = ?"
);
$stmt->bind_param('i', $product_id);
$stmt->execute();
$row = $stmt->get_result()->fetch_assoc();
$stmt->close();
$dk_conn->close();

if ($row) {
    echo json_encode($row);
} else {
    http_response_code(404);
    echo json_encode(['error' => 'Product not found']);
}

Deployment Workflow

Development (App Droplet Object)
    │
    ├── Write code in the Code Area
    ├── Test via the Terminal
    ├── Commit to version control
    │
    ▼
Publish to Staging
    │
    ├── Select the staging server
    ├── Click Publish
    ├── Verify functionality, logs, and performance
    │
    ▼
Publish to Production
    │
    ├── Select the production server
    ├── Click Publish
    │
    ▼
Live API or application
    https://api.yourcompany.com/endpoint

Best Practices

Deployment

Use App Droplet Objects for all externally facing deployments. Keep production code separate from workflow logic.
Keep separate staging and production servers. Never publish to production without testing on staging first.
Commit to version control before every publish. Publishing overwrites the target directory, so version control is how you roll back.
Combine App Droplets with AI Apps to package workflow and deployment logic together.

Security

Authenticate every external endpoint. Don't publish an API that returns business data without access control.
Use parameterized queries to prevent SQL injection: prepared statements with ? placeholders in PHP, %s placeholders with tuple parameters in Python.
Select only the columns you need. Avoid SELECT * in endpoints, so new columns aren't exposed by accident.
Never hard-code credentials. Use the provided connection helpers instead of writing database credentials into code.
Use SSH keys and HTTPS endpoints.
Limit terminal access on production servers.

Operations

Return correct HTTP status codes (400, 404, 500) with clear error messages, and close connections in finally blocks.
Document deployed services and endpoints in the Reasoning Atlas for traceability and governance.