Building Flowork Apps — The Dual-Engine Architecture

In this guide, we cover "Building Flowork Apps — The Dual-Engine Architecture" for the Flowork AI Knowledge Base. Category: app. Language: javascript.

Architecture Overview

Dual-Engine Architecture: (1) ONLINE ENGINE — Pure HTML + JavaScript running in Chromium WebView. No filesystem access. Communicates with Engine via HTTP to localhost:5000. (2) OFFLINE ENGINE — Python/Node.js scripts executed by Go Engine's runner module. Has full OS access. Apps are served at http://localhost:5000/local-apps/{app-name}/index.html

Key Patterns

• manifest.json defines app metadata (name, version, entry_point, engine_type)
• schema.json configures the UI form fields shown in the app launcher
• systemBridge.js is the IPC layer — calls fetch('http://localhost:5000/api/...') for Engine operations
• Online Mode: Pure HTML/JS sandboxed in Chromium — no fs access, only HTTP calls
• Offline Mode: Python/Node.js scripts run by internal/runner module with full OS access
• Apps served from apps/ directory via GoFiber static file server
• .flow files are AES-GCM encrypted ZIP containers for distribution
• AI writes files via POST /api/ai-write { app_id, output_type, files: { 'index.html': '...' } }

Project Structure

├── manifest.json
├── schema.json
├── index.html
├── systemBridge.js
├── icon.svg
├── style.css
├── main.py (optional)
├── requirements.txt (optional)

Implementation Details

manifest.json

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "My Flowork Application",
  "engine_type": "dual",
  "entry_point": "index.html",
  "action": { "default_popup": "index.html" },
  "permissions": ["network", "storage"]
}

schema.json

{
  "name": "My App",
  "description": "What this app does",
  "tier": "free",
  "fields": [
    { "key": "api_key", "label": "API Key", "type": "password" },
    { "key": "mode", "label": "Mode", "type": "select", "options": ["fast", "quality"] }
  ]
}

systemBridge.js

// IPC Bridge: HTML → Go Engine
async function engineWrite(appId, files) {
    const res = await fetch('http://localhost:5000/api/ai-write', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ app_id: appId, output_type: 'app', files })
    });
    return res.json();
}
async function engineExec(appId, command) {
    const res = await fetch('http://localhost:5000/api/ai-exec', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ app_id: appId, output_type: 'app', command })
    });
    return res.json();
}

Troubleshooting

• ⚠️ manifest.json name MUST match the folder name exactly
• ⚠️ schema.json must have valid JSON — no trailing commas
• ⚠️ systemBridge.js can only call localhost:5000 — never external URLs directly from bridge
• ⚠️ icon.svg is MANDATORY — use generate_icon tool to create one
• ⚠️ CSS/JS paths must be relative (./style.css not /style.css)

Summary

This article covers app patterns for Flowork OS. Generated by Flowork AI from verified system architecture.