Flowork OS Architecture — Complete System Overview

In this guide, we cover "Flowork OS Architecture — Complete System Overview" for the Flowork AI Knowledge Base. Category: general. Language: go.

Architecture Overview

Flowork OS is a 3-layer system: (1) Go Engine (main.go → flowork-engine.exe) — the core backend compiled to a single portable .exe using Go's embed.FS. It uses GoFiber v2 for HTTP on port 5000. (2) Electron GUI (main.js → gui.exe) — provides native window management, BrowserView tabs, and preload.js for IPC bridge between renderer and main process. (3) Cloudflare Website (floworkos.com) — hosts the Vue.js frontend SPA, API endpoints via Cloudflare Pages Functions, and KV storage for licenses and knowledge base.

Key Patterns

• Go embed.FS embeds entire UI into the .exe binary for full portability
• GoFiber v2 serves HTTP/REST API on localhost:5000 with CORS configured for both local and cloud origins
• Electron's contextBridge.exposeInMainWorld('floworkDesktop', {...}) creates the IPC bridge
• Single Instance Lock prevents multiple engine instances from running simultaneously
• Port 5000 force-kill on startup ensures clean boot even after crashes
• EngineDir variable locks all file paths to the .exe directory for portable operation
• License verification via Cloudflare TLS endpoint with offline cache fallback
• Auto-update system checks floworkos.com/update-engine.txt for version matching

Project Structure

├── main.go
├── main.js
├── preload.js
├── renderer.js
├── ai-builder.html
├── index.html
├── internal/config/
├── internal/runner/
├── internal/socket/
├── internal/workflow/
├── internal/packer/
├── internal/vault/
├── internal/watcher/
├── internal/trigger/
├── internal/history/

Implementation Details

main.go (Boot Sequence)

func main() {
    initEngineDir()   // Lock absolute path to .exe location
    initLicense()     // Verify subscription via Cloudflare TLS
    lockWorkingDirectory()
    killPreviousInstances()
    forceKillPort5000()
    checkUpdate()
    
    app := fiber.New(fiber.Config{
        DisableStartupMessage: true,
        BodyLimit: 500 * 1024 * 1024,
    })
    // ... register all API routes
    app.Listen(":5000")
}

preload.js (IPC Bridge)

contextBridge.exposeInMainWorld('floworkDesktop', {
    clearCache: () => ipcRenderer.invoke('app:clear-cache'),
    openAiBuilder: () => ipcRenderer.invoke('app:open-ai-builder'),
    navigate: (id, url) => ipcRenderer.invoke('app:navigate', id, url),
    aiBrowserCapture: (deviceId) => ipcRenderer.invoke('app:ai-browser-capture', deviceId),
    aiBrowserExec: (deviceId, script) => ipcRenderer.invoke('app:ai-browser-exec', deviceId, script),
    openAppTab: (appId, appName, appUrl) => ipcRenderer.invoke('app:open-app-tab', appId, appName, appUrl),
});

Troubleshooting

• ⚠️ Port 5000 already in use → engine auto-kills existing process on startup
• ⚠️ gui.exe not found → engine falls back to opening system browser
• ⚠️ License token expired → engine auto-downgrades to FREE tier
• ⚠️ File paths using relative paths break when packaged as .exe → always use filepath.Join(EngineDir, ...)

Summary

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