166 lines
10 KiB
Markdown
166 lines
10 KiB
Markdown
# 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.
|
|
|
|
```mermaid
|
|
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).
|
|
```
|