vibn-agent-runner/VIBNCODE_PLAN.md

VibnCode: Cloud-Powered Agent Desktop IDE Architecture & Implementation Plan

This is the original product VISION. For the live, prioritized work (with exact files, steps, status, and what's already shipped), use VIBNCODE_THIN_CLIENT_CHANGES.md. Infra/deploy details are in VIBNDEV.md; new-thread bootstrap context is in ai-new-thread.md.

Project Name: vibncode (formerly TalkCody)
Target Architecture: Desktop Thin Client with Monaco + Native Cloud Hosting Integration
Backend Platform: Vibnai Cloud Infrastructure (vibn-frontend, vibn-agent-runner, Gitea, Coolify)
Status File Location: master-ai/VIBNCODE_PLAN.md

---

1. System High-Level Architecture Diagram

vibncode functions as a high-fidelity window into your cloud-hosted workspace, routing all actions, skills, and terminal commands to the vibn-agent-runner and Gitea/Coolify backend.

graph TD
    %% Styling
    classDef client fill:#E1F5FE,stroke:#0288D1,stroke-width:2px;
    classDef runner fill:#EDE7F6,stroke:#5E35B1,stroke-width:2px;
    classDef infra fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px;

    subgraph Client [Desktop client - vibncode]
        UI[React 19 / Monaco Editor UI]
        State[Zustand Stores / Local SQLite DB Cache]
        Tauri[Tauri v2 App Wrapper]
    end

    subgraph CloudRunner [Cloud Workspace - vibn-agent-runner]
        Runner[Agent Session Runner Engine]
        Workspace[Sandboxed Project Dir: /workspaces]
        Tools[Vibn Platform & Sentry Tools]
    end

    subgraph Infrastructure [Vibnai Platform]
        DB[(PostgreSQL Database)]
        WebAPI[Next.js API Server: vibn-frontend]
        Gitea[(Gitea Git Server)]
        Coolify[Coolify Server Hosting]
    end

    %% Connections
    UI <-->|1. Event Streams & File Sync| WebAPI
    UI -->|2. Start/Cancel Execution| WebAPI
    WebAPI -->|3. Route Exec Request| Runner
    Runner <-->|4. Code Edits & Shell Runs| Workspace
    Runner -->|5. Save Output & File Changes| WebAPI
    WebAPI <-->|6. Write State & Logs| DB
    Runner <-->|7. Push/Pull/Clone Code| Gitea
    Runner -->|8. Manage & Deploy Apps| Coolify
    Workspace -->|9. Pull Guidelines| Gitea

    class UI,State,Tauri client;
    class Runner,Workspace,Tools runner;
    class DB,WebAPI,Gitea,Coolify,Workspace infra;

---

2. Structural Requirements & Feature Specification

2.1 Rebranding to vibncode

• All codebase identifiers, folder structures, logs, config registries, and binary product properties are renamed from talkcody to vibncode / VibnCode to prevent trademark leaks.
• The application bundle identifier is modified to com.vibnai.vibncode.

2.2 Preservation of the Desktop UI Experience

• The Monaco Editor, collapsible multi-panel grid, dark theme, and rich agent step logs are preserved exactly.
• All compiler execution and file system checks are offloaded to your secure cloud container runner.

2.3 Cloud-Hosted Live Browser Preview Pane

• Split-Screen Interface: Adjacent to the Monaco code editor, we inject a live webview/iframe tab.
• Wildcard DNS Mapping: The pane points directly to your dynamic wildcard URL generated during a dev server boot: https://[projectSlug]-[devServerPort].preview.vibnai.com
• Instant Hot-Module Replacement (HMR): As the cloud agent or the developer edits files, Vite or Next.js compiles the changes inside the cloud container in milliseconds. Traefik reverse-proxies the stream, causing the embedded browser pane to update instantly on-screen without requiring a manual refresh.

2.4 Autonomous Gitea & Coolify Environment Administration

• We add tabs to the left navigation panel matching the modules of your Vibnai Web Dashboard:
  1. Code [📝]: Monaco editor, virtual filesystem browser.
  2. Plan [📋]: Synchronized feature checklist showing requirements directly tied to fs_projects.phase_data.
  3. Host [🚀]: Lists running Coolify application containers, database states, environment credentials (.env), and displays live resource monitors (RAM, CPU, Build Logs).
  4. Market [📊]: Suggests GBP categories, researches competitor domains (DataForSEO), and performs technical site scrapes.
  5. Preview [🌐]: Embedded browser preview tab rendering the wildcard live deployment URL.
• Autonomous Agent Tools: The AI is equipped with Gitea and Coolify administration commands (e.g. git_commit_and_push, apps_create_database, apps_deploy, hosting_set_env, project_recent_errors). The AI can provision databases, modify env keys, verify compiling logs, and fix its own code bugs inside the sandboxed cloud workspaces autonomously.

---

3. Database & Database Synchronization Specifications

3.1 Mapping Local Client States to PostgreSQL

We will link vibncode's local state structures with your vibn-frontend PostgreSQL databases:

• Project Lists: Retrieved via GET /api/projects querying the fs_projects and fs_users tables.
• Active Agent Session: Instantiated via POST /api/projects/[projectId]/agent/sessions and updated by vibn-agent-runner sending PATCH /api/projects/[projectId]/agent/sessions/[sessionId] with outputLine and changedFile updates.
• Virtual File Tree: Read via GET /api/workspace/tree which performs a directory scrape of /workspaces/[giteaRepo] and renders a visual file browser in the desktop client's sidebar.

---

4. Key Code Paths & Planned Refactoring

To implement this architecture elegantly, the following specific files will be refactored:

4.1 Client-Side Refactoring (Tauri / React)

1. src/services/file-service.ts: Replace @tauri-apps/plugin-fs reads/writes with authorized cloud workspace endpoints:
   • GET /api/workspace/tree \rightarrow Scrapes Gitea directory tree.
   • POST /api/workspace/file/read \rightarrow Fetches content for Monaco.
   • POST /api/workspace/file/write \rightarrow Writes edits back to the cloud.
2. src/services/execution-service.ts:
   • Redirect startExecution() to trigger POST /api/projects/[projectId]/agent/execute on the server instead of running the loop inside the local app process.
   • Connect to vibn-frontend's SSE or session poll endpoint to map logs, changed file notifications, and status streams directly to Zustand.
3. src/components/chat/embedded-preview.tsx (New Component):
   • Incorporate a split-screen panel with an <iframe src="https://[subdomain].preview.vibnai.com" /> which shows/hides adjacent to the Monaco Editor when a dev server is booted.

4.2 Server-Side Porting (vibn-agent-runner)

1. Incorporate Parallel Agent Brain:
   • Extract TalkCody's tool-dependency-analyzer.ts and tool-executor.ts (TypeScript) and port them inside vibn-agent-runner/src/orchestration/.
   • This equips your cloud runner with 4-level Smart Concurrency (batching parallel reads and serializing write reviews inside Docker).
2. Enable the Ralph Loop Autonomy:
   • Inject ralph-loop-service.ts into your runSessionAgent() background executor. This ensures that when the agent outputs self-reflection keywords, the cloud-runner automatically spawns a continuation cycle until the task is complete.

---

5. Component-Level Service Redirections (The Vibn Integration Bridge)

To preserve the rich desktop UI completely intact and prevent breaking any complex React views, we map all native local OS dependencies inside src/components/ to go over our cloud services instead of rewriting the files individually:

5.1 Virtualizing file-editor-content.tsx & file-tree.tsx

• The Component: The Monaco Editor panel and the Sidebar File Tree.
• Current State: Calls repositoryService.readFileContent(path) and fastDirectoryTreeService.buildDirectoryTree(rootPath) which invoke local Rust file-readers and Tauri FS plugins.
• Re-engineered Bridge: We modify repositoryService and fastDirectoryTreeService to POST to your secure Next.js POST /api/mcp endpoint with the actions "fs.read" and "fs.tree". This fetches the file content and directories list directly from Gitea inside the /workspaces Docker environment and populates Monaco seamlessly.

5.2 Redirecting empty-repository-state.tsx

• The Component: The welcoming dashboard panel shown when no local repository folder is opened.
• Current State: Prompts the developer to select a folder on their local hard drive.
• Re-engineered Bridge: When the developer logs in and selects a project on the projects-page.tsx, we automatically set the active project root_path to the cloud repository path (derived from the database) and immediately trigger the virtual directory tree, bypassing local disk queries entirely.

5.3 Bridging file-preview.tsx (Chat Attachments)

• The Component: The attachment downloader inside your chat messages (saving images/videos locally).
• Current State: Uses Tauri's save dialog and plugin-fs to write bytes to the local Downloads folder.
• Re-engineered Bridge: We modify this to download attachments directly from your GCP Cloud Storage bucket / R2 CDN (https://cdn.vibnai.com/attachments/...) over HTTP using the native browser download manager.

---

6. Phased Implementation Roadmap

PHASE 1: System Rebranding & Desktop App Clean-up
 ├── Rebrand 'talkcody' to 'vibncode' globally across folders & package assets.
 ├── Modify Tauri config JSONs with the bundle ID 'com.vibnai.vibncode'.
 └── Disable local compilers and mock local SQLite caches.

PHASE 2: Backend API Development in Next.js
 ├── Implement virtual file endpoints (POST /api/workspace/file/read, GET /tree).
 └── Establish SSE / WebSockets stream routes for agent output lines.

PHASE 3: UI Layout & Cloud Connection Setup
 ├── Implement left-nav tabs: Plan, Host, Market, and Code.
 ├── Hook file explorer & Monaco to read/write cloud files.
 └── Embed wildcard preview tab pointing to *.preview.vibnai.com.

PHASE 4: Orchestrating the Cloud Agent Brain
 ├── Migrate TalkCody's parallel analyzer & Ralph Loop to vibn-agent-runner.
 └── Enable full, autonomous environment management (Gitea, Sentry, Coolify API).