Business Specification: Applet System

Status: Draft

Problem Statement

IOTA SDK provides robust multi-tenant business management capabilities, but adding new functionality currently requires:

graph TD
    subgraph "Current Pain Points"
        A[Write Go code] -->|High barrier| B[Web developers blocked]
        C[SDK recompilation] -->|Complex| D[Deployment issues]
        E[Core SDK changes] -->|Bottleneck| F[Slow features]
        G[Fork SDK] -->|Maintenance| H[Merge conflicts]
    end

    style A fill:#ef4444,stroke:#b91c1c,color:#fff
    style C fill:#ef4444,stroke:#b91c1c,color:#fff
    style E fill:#ef4444,stroke:#b91c1c,color:#fff
    style G fill:#ef4444,stroke:#b91c1c,color:#fff

1. Writing Go code - High barrier for web developers
2. SDK recompilation - Deployment complexity, version management
3. Core SDK changes - Feature requests bottleneck on SDK team
4. Forking the SDK - Maintenance burden, merge conflicts

Current Pain Points:

• The Website/Ali module (AI chatbot) is embedded in SDK core, but it’s a specialized feature that not all tenants need
• Shyona (AI analytics) required building a full Go module with 15+ services
• Partners want to add custom integrations (Slack, Zapier, custom CRMs) without SDK involvement
• Different tenants have vastly different needs that don’t justify core SDK features

Business Impact:

mindmap
  root((Business Impact))
    Lost Revenue
      Customers need missing features
      Competitors win deals
    Slow Time-to-Market
      Weeks to implement
      Complex deployment
    High Development Cost
      Go expertise required
      Limited developer pool
    Limited Ecosystem
      No third-party developers
      No marketplace

Target Audience

graph LR
    subgraph "Primary"
        A[Internal Team<br/>Full-stack developers]
    end

    subgraph "Secondary"
        B[Partner Developers<br/>Web developers]
    end

    subgraph "Future"
        C[Third-Party Developers<br/>Marketplace publishers]
    end

    A -->|Phase 1| B
    B -->|Phase 2| C

    style A fill:#3b82f6,stroke:#1e40af,color:#fff
    style B fill:#10b981,stroke:#047857,color:#fff
    style C fill:#f59e0b,stroke:#d97706,color:#fff

Primary: Internal Development Team

• Goal: Decouple optional features (AI, website widgets) from SDK core
• Skill Level: Full-stack developers (TypeScript, React, Go)
• Frequency: Creating new applets for client projects

Secondary: Partner Developers

• Goal: Build custom integrations for their clients
• Skill Level: Web developers (TypeScript, React)
• Frequency: Building applets as part of implementation projects

Tertiary: Third-Party Developers (Future)

• Goal: Publish applets to marketplace for distribution
• Skill Level: Varied (need good documentation, templates)
• Frequency: Building and maintaining applets as products

Use Cases

UC1: AI Website Chat (Reference: modules/website)

Current State: Compiled into SDK, requires Go expertise to modify

Desired State: Installable applet with:

• Configuration page for API keys, model selection
• Embeddable chat widget for customer websites
• CRM integration (creates clients, routes messages to chats)
• AI response generation via external APIs (OpenAI, custom)

graph TB
    subgraph "AI Website Chat Applet"
        direction TB
        MAN[manifest.yaml]

        subgraph "Backend"
            CFG[handlers/config.ts]
            THR[handlers/threads.ts]
            MSG[handlers/messages.ts]
            SVC[services/ai-service.ts]
        end

        subgraph "Frontend"
            CFGP[pages/config.tsx]
            CHAT[components/ChatWidget.tsx]
        end

        subgraph "Locales"
            EN[en.json]
            RU[ru.json]
        end
    end

    style MAN fill:#f59e0b,stroke:#d97706,color:#fff
    style Backend fill:#3b82f6,stroke:#1e40af,color:#fff
    style Frontend fill:#10b981,stroke:#047857,color:#fff

UC2: Shyona-Style AI Analytics (Reference: shy-trucks/modules/shyona)

Current State: Full Go module with complex agent framework

Desired State: Applet that provides:

• Natural language business queries
• SQL query generation and execution
• Multi-agent orchestration
• Knowledge base integration
• GraphQL API for frontend

Challenges:

• Complex service orchestration
• Heavy computation (may need Go or WASM)
• Deep SDK integration (GraphQL schema extension)

Possible Approach:

• Core agent framework remains in SDK (reusable)
• Applet defines specific agents, prompts, tools
• Applet provides UI for chat interface

UC3: Custom CRM Integration

sequenceDiagram
    participant SF as Salesforce
    participant APP as CRM Applet
    participant SDK as IOTA SDK
    participant DB as Database

    Note over APP: Event Handler
    SDK->>APP: client.created event
    APP->>SF: Create contact
    SF-->>APP: Success
    APP->>DB: Log sync status

    Note over APP: Scheduled Sync
    APP->>DB: Get modified clients
    APP->>SF: Batch update
    SF-->>APP: Results
    APP->>DB: Update sync timestamps

Scenario: Partner wants to sync clients with Salesforce

Applet Provides:

• Configuration page for Salesforce credentials
• Event handlers for client.created, client.updated
• Scheduled sync job (hourly full sync)
• UI widget showing sync status on client detail page

UC4: Custom Reporting Dashboard

Scenario: Tenant needs specialized financial reports

Applet Provides:

• Custom SQL queries (read-only)
• Visualization components (charts, tables)
• PDF export functionality
• Scheduled email reports

UC5: Third-Party Webhook Handler

Scenario: Receive webhooks from Stripe, process payments

Applet Provides:

• HTTP endpoint for webhook reception
• Event handlers to create payment records
• Configuration for webhook secret validation

Requirements

In Scope

mindmap
  root((Requirements))
    Runtime
      HTTP handlers
      Event handlers
      Scheduled tasks
      External HTTP
      Database access
      Secret management
    UI
      Navigation items
      Full pages
      Widgets
      SDK components
      Localization
    DX
      TypeScript
      React/Next.js
      Hot reload
      CLI tools
      Clear errors
    Admin
      Install/uninstall
      Enable/disable
      Configuration
      Logs & metrics

Runtime Capabilities:

• HTTP endpoint handlers (GET, POST, PUT, DELETE)
• Event handlers (subscribe to SDK domain events)
• Scheduled tasks (cron-based)
• External HTTP requests (with security controls)
• Database read access (existing SDK tables)
• Database write access (with permissions)
• Custom database tables (with approval)
• Secret management (API keys, tokens)

UI Capabilities:

• Register navigation items
• Register full pages
• Inject widgets into existing pages
• Use SDK UI components for consistency
• Custom styling within design token constraints
• Localization/i18n support

Developer Experience:

• TypeScript support with full type definitions
• React/Next.js for frontend development
• Hot reload during development
• Local development server
• CLI for packaging and deployment
• Clear error messages and debugging

Administration:

• Install/uninstall applets per tenant
• Enable/disable applets
• Configure applet-specific settings
• View applet logs and metrics
• Permission review before installation

Out of Scope (Initial Version)

• Real-time WebSocket support
• Background workers (long-running processes)
• File system access
• Native code execution
• Cross-tenant data access
• SDK core modification
• GraphQL schema extension (complex, security concerns)
• WASM modules (future consideration)

Future Scope

• Applet marketplace/registry
• Applet versioning and updates
• Applet reviews and ratings
• Revenue sharing for paid applets
• WASM for compute-intensive applets
• GraphQL schema extension (controlled)
• Multi-applet communication

Success Criteria

graph LR
    subgraph "Success Metrics"
        A[Website/Ali<br/>extracted] --> B[Partner builds<br/>integration]
        B --> C[UI looks<br/>native]
        C --> D[Install in<br/>< 5 min]
        D --> E[Security<br/>maintained]
    end

    style A fill:#10b981,stroke:#047857,color:#fff
    style B fill:#10b981,stroke:#047857,color:#fff
    style C fill:#10b981,stroke:#047857,color:#fff
    style D fill:#10b981,stroke:#047857,color:#fff
    style E fill:#10b981,stroke:#047857,color:#fff

1. Website/Ali can be extracted from SDK core into an installable applet
2. Partner can build a custom integration in TypeScript without Go knowledge
3. UI looks native - applet pages indistinguishable from SDK pages
4. Installation is simple - admin can install from package in < 5 minutes
5. Security is maintained - no tenant isolation bypass, no SSRF, no data leaks

Assumptions

• Developers have TypeScript/React experience
• Tenants have reliable internet for external API calls
• SDK team will maintain component library for UI consistency
• Initial distribution is file-based (no marketplace)

Risks & Mitigations

Risk	Impact	Mitigation
Applet breaks tenant	High	Sandboxing, resource limits, disable on error
Security vulnerability	Critical	Permission model, code review for marketplace
Performance degradation	Medium	Resource quotas, monitoring, circuit breakers
UI inconsistency	Medium	Mandatory component library, design tokens
Maintenance burden	Medium	Clear versioning, deprecation policy
Complex debugging	Medium	Good logging, error traces, dev tools

---

Next Steps

• Review Architecture for system design
• See Runtime Options for engine comparison
• Check Permissions for security model