AgentForge — PRD & System Flow

01

Product Overview

💡 Apa itu AgentForge?

AgentForge adalah platform AI-powered app builder yang mampu membangun aplikasi Fullstack Web, Android Native, dan iOS Native — dengan perbedaan fundamental: semua eksekusi code berjalan di perangkat lokal pengguna, bukan di cloud.

User cukup chat di web interface yang di-host di cloud. AI orchestrator di cloud memahami intent, lalu mengirim instruksi ke AgentForge Agent (aplikasi desktop yang terinstall di laptop) melalui Firebase Realtime Database sebagai jembatan komunikasi.

🎯 Problem yang Dipecahkan

Pain points platform serupa:

• Code berjalan di cloud → data sensitif keluar dari perangkat

• Ketergantungan penuh pada server vendor

• Tidak bisa akses filesystem lokal, database lokal, atau internal tools

• Biaya mahal untuk usage intensif

AgentForge Solution: Kecerdasan di cloud, eksekusi di lokal. Privacy by design.

🧠

Cloud Layer

AI Orchestrator

LLM di cloud memahami request user, merencanakan langkah, dan mengirim task queue ke Firebase.

🌉

Bridge Layer

Firebase Realtime

Database realtime sebagai message bus antara cloud AI dan local agent. Latensi rendah, persistent.

🖥️

Local Layer

MCP Desktop Agent

Aplikasi desktop yang berjalan di background, mengeksekusi semua perintah secara lokal.

02

Arsitektur Sistem

// System Architecture — Three-Layer Model

☁️ Cloud Layer — Hosted by AgentForge

Web UI (Next.js)

AI Orchestrator

Task Queue Manager

Auth Service

Project Manager API

Preview Proxy

↕️ HTTPS + Firebase Realtime DB

🌉 Bridge Layer — Firebase

task_queue/{userId}

agent_status/{userId}

file_output/{userId}

logs_stream/{userId}

preview_tunnel/{userId}

↕️ Firebase SDK (WebSocket)

🖥️ Local Layer — User's Device

AgentForge Agent

MCP Server

File System Manager

Terminal Executor

Runtime (npm/bun)

Dev Server

ngrok/frpc Tunnel

Catatan Keamanan: Firebase hanya menjadi relay message. Konten file code TIDAK tersimpan permanen di Firebase — hanya task instructions dan status. File code 100% berada di filesystem lokal pengguna.

03

System Flow Detail

// Complete Request Flow — Dari Chat ke Running App

💬

User Input

"Buatkan landing page untuk perusahaan kapal ku"

↓

🧠

Cloud — AI Orchestrator

LLM menganalisis request, memilih template, merencanakan task tree

// Task Planning Output
{
  "projectId": "proj_ship_abc123",
  "template": "landing-page-corporate",
  "tasks": [
    { "id": "t1", "type": "scaffold", "action": "init_project" },
    { "id": "t2", "type": "write_file", "path": "src/App.tsx" },
    { "id": "t3", "type": "write_file", "path": "src/components/Hero.tsx" },
    { "id": "t4", "type": "run_command", "cmd": "npm install" },
    { "id": "t5", "type": "run_command", "cmd": "npm run dev" }
  ]
}

↓ push ke Firebase task_queue

🌉

Firebase Realtime DB — Message Bus

Task payload disimpan, trigger WebSocket event ke semua listener

↓ onValue() listener terpicu

🖥️

Local Agent — Task Executor

Agent mengeksekusi setiap task secara berurutan di filesystem lokal

t1 → mkdir ~/AgentForge/proj_ship_abc123 && cp -r template/landing .
t2 → write src/App.tsx (konten dari LLM)
t3 → write src/components/Hero.tsx
t4 → cd proj_ship_abc123 && npm install
t5 → npm run dev → localhost:5173
     → start ngrok tunnel → https://abc.ngrok.io
     → push preview URL ke Firebase

↓ update status & preview URL

🎉

Web UI — Hasil

Preview iframe muncul di browser user. App berjalan di laptop lokal, tampil di web!

04

User Journey Lengkap

1

Registrasi & Install Agent

User mendaftar di app.agentforge.dev. Setelah login, ditampilkan halaman setup dengan tombol download installer sesuai OS. User mendapat Agent Token unik.

Agent Token = JWT yang berisi userId + Firebase credentials terenkripsi. Ini yang menghubungkan agent lokal ke akun cloud.

2

Local · Setup

Install & Aktivasi Agent

User menginstall AgentForge Agent. Saat pertama run, agent meminta paste Agent Token. Agent otomatis menginstall dependencies dan mengkonfigurasi background service.

$ agentforge-agent --token eyJhbGc...
✓ Token valid — connected as user@email.com
✓ Firebase listener active
✓ Node.js v20 detected
✓ ngrok configured
✓ Agent running on port 41337
# Agent siap menerima instruksi!
        

3

Mulai Project Baru

User membuka Web UI, klik "New Project". UI menampilkan status agent: ● Online. User memilih workspace folder dan mulai chat.

4

AI Orchestrator Merencanakan Task

LLM menerima pesan user + context. AI menggunakan ReAct pattern: Reason → Act → Observe → ulang. AI memecah request jadi atomic tasks.

Task Types

📁 scaffold — buat struktur folder/file

✏️ write_file — tulis/edit file

🗑️ delete_file — hapus file

⚡ run_command — jalankan CLI command

📦 install_deps — npm/pip install

🌐 start_server — jalankan dev server

🔍 read_file — baca isi file → balik ke AI

🪲 read_logs — baca error log → AI debug

Execution Modes

🔗 Sequential — satu per satu (default)

write file A → write file B → npm install

⚡ Parallel — bersamaan

write Hero.tsx + write Footer.tsx bersamaan

5

Local · Execution

Agent Mengeksekusi Task

AgentForge Agent menerima task dari Firebase, mengeksekusi satu per satu, dan melaporkan hasilnya. Jika error, AI melakukan auto-debug loop.

Auto-Debug Loop: Jika task gagal → agent kirim stderr → AI generate fix → kirim write_file baru → retry. Max 5 iterasi otomatis.

6

Local · Preview

Preview via Tunnel

Setelah dev server jalan, agent otomatis membuka ngrok tunnel dan push URL publik ke Firebase. Web UI menampilkan preview dalam iframe.

// Firebase update dari agent
preview_tunnel/user123/proj_ship: {
  url: "https://a1b2c3.ngrok.io",
  port: 5173,
  status: "running",
  pid: 48291
}
        

7

Iterasi via Chat

User bisa terus chat untuk edit. AI memahami konteks, generate task minimal, agent eksekusi, hot-reload di preview.

8

Deploy ke Hosting

Jika user ingin publish, agent menjalankan build command, lalu mengupload artifact ke hosting. Proses deploy berjalan di lokal.

05

AgentForge Desktop Agent

Struktur Aplikasi Agent

Agent adalah aplikasi Tauri yang berjalan sebagai background service dengan system tray icon.

agentforge-agent/
├── main/
│   ├── firebase-listener.ts  # WebSocket listener
│   ├── task-executor.ts      # Core executor
│   ├── file-manager.ts       # FS operations
│   ├── shell-runner.ts       # Command executor
│   ├── tunnel-manager.ts     # ngrok/frpc
│   └── security.ts           # Sandbox & whitelist
├── installer/
│   ├── windows/  # NSIS installer
│   ├── linux/    # .deb + systemd
│   └── macos/    # .dmg + launchd
└── ui/
    └── tray.ts   # System tray menu
      

Security Model

Hanya task dari Firebase user sendiri yang dieksekusi — diverifikasi dengan Firebase UID. Zero-trust.

Sandbox Rules:

✅ Boleh: Akses folder workspace yang sudah di-approve user

✅ Boleh: Jalankan npm/node/python/git dalam project folder

❌ Tidak boleh: Akses folder di luar workspace

❌ Tidak boleh: Network request ke selain localhost + npm registry

❌ Tidak boleh: Jalankan command yang tidak ada di whitelist

⚠️ Perlu konfirmasi user: Install binary baru, akses port tertentu

Firebase Schema — Task Protocol

// Firebase Realtime Database Schema
{
  "task_queue": {
    "{userId}": {
      "{projectId}": {
        "{taskId}": {
          "type": "write_file | run_command | read_file | ...",
          "payload": { /* task-specific data */ },
          "status": "pending | running | success | failed",
          "priority": 1,
          "dependsOn": ["taskId_prev"],
          "createdAt": 1711234567890,
          "result": { /* stdout, stderr, returnCode */ }
        }
      }
    }
  },
  "agent_status": {
    "{userId}": {
      "online": true,
      "version": "1.2.0",
      "os": "darwin",
      "lastHeartbeat": 1711234567890,
      "activeProjects": ["proj_abc"]
    }
  },
  "preview_tunnel": {
    "{userId}": {
      "{projectId}": {
        "url": "https://xyz.ngrok.io",
        "status": "running"
      }
    }
  },
  "logs_stream": {
    "{userId}/{projectId}/{taskId}": {
      "lines": ["line1", "line2"]
    }
  }
}
  

06

Firebase Bridge — Detail

Kenapa Firebase?

Firebase Realtime Database dipilih sebagai bridge karena:

🔌 Persistent WebSocket — auto-reconnect, no polling

⚡ Latensi rendah — sub-100ms delivery

🔐 Security Rules — user hanya akses data miliknya

📦 SDK multi-platform — JS, Node.js, mobile

💰 Gratis sampai 1GB + 10GB/bulan transfer

Firebase Security Rules

{
  "rules": {
    "task_queue": {
      "$userId": {
        ".read": "auth.uid === $userId",
        ".write": "auth.uid === $userId",
        "$projectId": {
          ".indexOn": ["status", "priority"]
        }
      }
    },
    "agent_status": {
      "$userId": {
        ".read": "auth.uid === $userId",
        ".write": "auth.uid === $userId"
      }
    },
    "preview_tunnel": {
      "$userId": {
        ".read": "auth.uid === $userId",
        ".write": "auth.uid === $userId"
      }
    }
  }
}
      

Fallback Strategy

Primary

Firebase Realtime DB

WebSocket persistent. Optimal untuk latensi rendah.

Fallback

Firebase Firestore

Jika Realtime DB overload, switch ke Firestore dengan polling 500ms.

Alternative

Self-hosted WebSocket

Untuk enterprise plan, self-hosted broker untuk zero data residency.

07

Feature Requirements

Fitur	Deskripsi	Layer	Priority	Phase
Chat Interface	Multi-turn chat dengan context awareness, code highlighting, streaming	Cloud	P1	MVP
Agent Installer	Auto-update, setup wizard, dependency checker	Local	P1	MVP
File Tree View	Visualisasi struktur project, realtime update	Cloud	P1	MVP
Live Preview	Iframe via ngrok tunnel, auto-refresh	Bridge	P1	MVP
Code Editor	Monaco editor, sync dua arah dengan filesystem lokal	Cloud	P1	MVP
Log Streaming	Terminal output realtime di web UI	Bridge	P1	MVP
Auto-Debug Loop	AI otomatis baca error, generate fix, retry max 5x	Cloud	P2	Beta
Git Integration	Auto git init, commit per iterasi, push ke GitHub	Local	P2	Beta
Multi-Framework	React, Vue, Next.js, SvelteKit, Astro, Flask, Kotlin, Swift	Cloud	P2	Beta
Deploy One-Click	Deploy ke Vercel/Netlify/Railway + Play Store/App Store	Local	P2	Beta
Multi-Agent	AI agents spesialisasi: Designer, Backend Dev, Tester	Cloud	P3	v2.0
Voice Input	Instruksi via voice, transcribe, kirim ke AI	Cloud	P3	v2.0
Team Collaboration	Multiple users, shared agent sessions	Cloud	P3	v2.0

08

Technology Stack

☁️ Cloud Platform

⚡Next.js 14 (App Router)

🎨Tailwind CSS + Radix UI

📡tRPC / REST API

🗄️PostgreSQL (Supabase)

🔐Clerk Auth

🧠 AI Orchestrator

🤖Claude 3.5 Sonnet

⚡Claude 3 Haiku

🔧Custom Tool Calling

📋ReAct Loop Pattern

🌉 Bridge

🔥Firebase Realtime DB

🔐Firebase Auth

📜Security Rules

🖥️ Local Agent

⚡Tauri v2 (Rust)

📦Node.js 20 LTS

🔥Firebase SDK

🌐ngrok / frpc

📝fs-extra

⚙️execa (shell)

📦 Distribution

🪟NSIS (Windows)

🐧.deb + systemd

🍎.dmg + launchd

🔄Auto-update

🚀 Infrastructure

▲Vercel

☁️GCP

📊Posthog

🐛Sentry

Kenapa Tauri bukan Electron? Tauri menggunakan native WebView (~5MB vs ~150MB) dan konsumsi memori lebih rendah. Penting untuk app background 24/7.

09

Roadmap & Milestones

Phase 0 · Pre-Work

Foundation

Firebase schema design
Agent prototype
AI tool calling spec
Task protocol

⏱ 3 minggu

Phase 1 · MVP

Core Loop

Web UI chat
Agent installer
Scaffold + write tasks
ngrok tunnel preview
React template

⏱ 6 minggu

Phase 2 · Beta

Polish

Auto-debug loop
Code editor sync
Git integration
Multi-framework
One-click deploy

⏱ 8 minggu

Phase 3 · v1.0

Launch

Team workspace
Billing integration
Auto-update agent
Public launch

⏱ 6 minggu

Phase 4 · v2.0

Scale

Multi-agent system
Voice input
Plugin marketplace
Enterprise plan

⏱ 3 bulan

10

Business Model

Starter

Free/mo

1 active project
100 AI messages/bulan
Agent installer
Community templates
ngrok tunnel (1 jam/sesi)

Pro — Populer

$19/mo

Unlimited projects
2.000 AI messages/bulan
Priority tunnel (24/7)
Auto-debug loop
Git integration
One-click deploy
All frameworks

Team

$49/mo

5 team members
10.000 AI messages/bulan
Shared workspaces
Custom AI model (BYO key)
Priority support

Enterprise

Custom

Unlimited members
Self-hosted option
On-premise AI model
SSO / SAML
SLA 99.9%

🏆 Competitive Advantage

vs Lovable/Bolt: Code eksekusi 100% lokal, data tidak keluar perangkat

vs Cursor/Windsurf: Zero setup IDE, cukup browser + agent kecil

vs GitHub Copilot: Full-stack orchestration, end-to-end dari idea ke running app

🎯 Target Market

Primary: Developer Indonesia & SEA yang privacy-conscious, startup, freelancer

Secondary: Non-developer yang ingin prototype cepat tanpa coding

Enterprise: Perusahaan yang tidak bisa code keluar jaringan internal