ESSENTIALS Technical Guide

Active Development

System Overview

Property	Value
Application	VibeCode Builder - Essentials Edition
Location	`/opt/vibecode-builder/essentials/app/`
Port	3020
URL	https://myvcbpro.com
Status	Operational

Server Infrastructure

PM2 Managed Services

All web services are managed by PM2 for auto-restart protection:

Service	Port	PM2 Name	Location
VCB Essentials	3020	vcb-essentials	`/opt/vibecode-builder/essentials/app/server/`
Real Estate App	8090	realestate-app	`/opt/vibecode-builder/user-webapps/greg/realestate_greg_001/`
Grandview Showcase	8095	grandview-showcase	`/opt/vibecode-builder/user-webapps/greg/grandview-myvcbpro/`

PM2 Commands

# View status
pm2 status

# Restart a service
pm2 restart vcb-essentials
pm2 restart realestate-app
pm2 restart grandview-showcase

# Save process list (for auto-restart on boot)
pm2 save

# View logs
pm2 logs vcb-essentials
pm2 logs realestate-app
pm2 logs grandview-showcase

Cloudflare Tunnel Configuration

Tunnel ID: 7e26724e-b529-4277-86ff-97c82d973893

Config: ~/.cloudflared/config-myvcbpro.yml

Hostname	Local Service
myvcbpro.com	http://localhost:3020
www.myvcbpro.com	http://localhost:3020
app.ownsouthwestflorida.com	http://localhost:8090
grandview.myvcbpro.com	http://localhost:8095

Restart Cloudflare Tunnel

# Find and kill existing tunnel
ps aux | grep cloudflared
kill 

# Start tunnel with config
nohup /usr/local/bin/cloudflared tunnel run --config ~/.cloudflared/config-myvcbpro.yml 7e26724e-b529-4277-86ff-97c82d973893 > /dev/null 2>&1 &

Architecture

Application Structure

/opt/vibecode-builder/essentials/ ├── app/ │ ├── public/ # Static frontend files │ │ ├── index.html # Landing page │ │ ├── builder/ # Website builder tools │ │ │ ├── chat/ # AI Chat Builder │ │ │ ├── wysiwyg/ # WYSIWYG Editor │ │ │ ├── forms/ # Forms Maker │ │ │ └── database/ # Database Creator/Viewer │ │ ├── dashboard/ # Dashboard pages │ │ │ ├── index.html # Main dashboard │ │ │ ├── websites.html │ │ │ ├── forms.html │ │ │ └── my-data/ # Database management │ │ ├── design-library/ # Image/PDF management │ │ └── docs/ # Documentation │ ├── server/ # Backend API │ │ ├── index.js # Express server (port 3020) │ │ ├── translator-middleware.js │ │ ├── database-service.js │ │ └── db/ # Database scripts │ └── .env # Environment config (PORT=3020) ├── archive/ # Archived files └── backups/ # Local backups

Technology Stack

Component	Technology
Frontend	HTML5, CSS3, Vanilla JavaScript
Backend	Node.js, Express.js
Database	MySQL (shared)
Authentication	JWT
AI Integration	Rosie / OpenRouter
Tunnel	Cloudflare (port 3020)

Database Schema

Database: vibecode_builder (shared with Enterprise)

Key Tables

users - User accounts and authentication
websites - Website projects
pages - Individual website pages
templates - Template definitions
user_templates - User-created templates
prompt_history - AI prompt logs
credit_transactions - Credit system
admin_pins - Admin access codes
forms - Form definitions (NEW)
form_submissions - Form response data (NEW)
user_databases - User database metadata (NEW)

Forms System

v1.0 - Complete

Forms Maker

Location: /builder/forms/index.html

23+ Field Types: Text, Email, Phone, Number, Address, Date, Date Range, Dropdown, Radio, Checkbox, Picture Choice, Toggle, Rating, Slider, Matrix, File Upload, Rich Text, Banner, Heading, Paragraph, Divider, Page Break
Features: Drag & drop, snap-to-grid, conditional logic, multi-page forms, undo/redo
Design Library Integration: Image picker for Banner and Picture Choice fields

Form Responses Viewer

Location: /builder/forms/responses.html

Table view with sortable columns
Column visibility toggle
Search and date filtering
Edit individual responses
Delete responses
Export to CSV
Stats sidebar (total, today, this week, this month)

Email Notifications (AgentMail)

Owner notifications on submission
Respondent confirmation emails
Customizable HTML templates
Variable substitution: {{form_name}}, {{submission_date}}, {{submission_data}}

Forms API Endpoints

Method	Endpoint	Description
GET	`/api/forms`	List user forms
GET	`/api/forms/:id`	Get form details
POST	`/api/forms`	Create new form
PUT	`/api/forms/:id`	Update form
DELETE	`/api/forms/:id`	Delete form
GET	`/api/forms/:id/submissions`	Get form responses
PUT	`/api/forms/:id/submissions/:subId`	Update response
DELETE	`/api/forms/:id/submissions/:subId`	Delete response
POST	`/api/forms/:id/submit`	Submit form (public)

Database System

v2.0 - Complete

Database Creator

Location: /builder/database/index.html

AI Chat: Natural language database creation
Build from Scratch: 8 field types including Formula
CSV Import: Smart field type detection

Database Viewer

Location: /database-viewer.html (consolidated version)

Previous location (archived): /builder/database/viewer.html

View Types (8)

Grid - Traditional spreadsheet layout
List - Compact vertical list with expand/collapse
Cards - Card-based layout with key fields
Gallery - Visual grid with image upload support
Kanban - Drag-and-drop board with status columns
Calendar - Month/Week/Day views with navigation
Timeline - Chronological view with zoom/pan
Compact - Dense table for maximum visibility

Field Types (14)

Text: Single Line, Long Text, Email, URL, Phone
Numbers: Number, Currency, Percent, Rating
Date: Date, Date & Time
Choice: Single Select, Multiple Select, Checkbox
Advanced: Linked Record, Lookup, Formula, Attachment

Features

Drag-and-drop column reordering (persists per user)
Column type configuration with right-click context menu
Linked records between tables
Formula fields with Airtable-style syntax {FieldName}
AI chat sidebar (collapsible)
Export to CSV
Sort via context menu
Field management (edit, duplicate, hide, delete)

API Endpoints

Endpoint	Method	Description
`/api/user/databases`	GET	List user databases
`/api/user/databases/:dbId`	GET	Get database info
`/api/user/databases/:dbId/tables/:tableName`	GET	Get table data
`/api/user/databases/:dbId/query`	POST	Execute SQL query
`/api/user/external-databases/:id/download`	GET	Download SQLite file

LocalStorage Keys

columnOrder_{userId}_{dbId}_{tableName} - Column order
columnTypes_{userId}_{dbId}_{tableName} - Column type config
viewType_{userId}_{dbId}_{tableName} - Selected view type
aiSidebarCollapsed - AI sidebar state

Formula Functions

Category	Functions
Math	ROUND, ABS, SUM
Text	CONCATENATE, LEFT, RIGHT, UPPER, LOWER
Logic	IF, AND, OR, NOT
Date	NOW, TODAY, DATEADD, DATEDIFF

SQLite Infrastructure

User-isolated databases at /data/users/{userId}/{dbId}.db
Real SQLite with full SQL support
API endpoints: /api/user/databases

Builder Chat - Web Page Generation

Overview

The Builder Chat is an AI-powered web page generation system where Rosie (the AI assistant) manages the entire workflow from user request to delivered website.

Workflow Architecture

User Request - User submits natural language description in chat
Rosie Analysis - Rosie analyzes request and spawns appropriate sub-agent
Sub-Agent Coding - AI model (configurable by Admin) generates website code
Quality Review - Rosie reviews output for errors, quality, and UX flow
Quality Score - Auto-generated score (0-100). If < 85, auto-retry initiated
User Feedback - Thumbs up/down. Down = retry (max 3 attempts total)
Preview - Mini-viewport displays generated website

Quality Assurance System

Quality Threshold: 85/100 minimum for approval
Auto-Retry: Triggered when score falls below threshold
Max Attempts: 3 total (initial + 2 retries)
Review Criteria: Code validity, UX flow, visual consistency, responsiveness

AI Model Configuration

Admins configure the AI model for web coding via Settings:

Default: DeepSeek V3 (openrouter/deepseek/deepseek-chat)
Configurable per deployment
Model selection affects coding style and capabilities

UI Components

Left Panel: Chat interface with status indicators, quality score, feedback buttons
Center Panel: Mini-viewport with desktop/tablet/mobile size controls
Right Panel: Page Functions toolbar (Save, Export, Publish, Settings)

UI Layout (Three-Column Design) - v2.0

Left Column (380px): Chat interface with AI-Assistant (Rosie), prompt history, quality score, feedback buttons, credits display
Center Column (flex): Mini-viewport with unified toolbar (size buttons + page functions), website preview with true mobile/tablet simulation
Right Column (220px): Page Functions panel with buttons arranged by popularity (one per row)

Right Sidebar Button Order (by popularity)

💾 Save - Green button (most frequently used)
👁️ Preview - Open website preview in new tab
🚀 Publish - Publish website live
✏️ Visual Editor - Open WYSIWYG editor
📁 Load Existing - Load saved website
📋 Templates - Browse template gallery
📤 Export - Export website files
⚙️ Settings - Builder settings

Viewport Simulation

Desktop: Full width with standard viewport meta
Tablet (768px): iPad-sized with proper viewport scaling
Mobile (375px): iPhone-sized with mobile viewport meta tag
Viewport meta tag injected dynamically based on selected size

Toolbar Functions

Button	Function	Location
Desktop/Tablet/Mobile	Viewport size switching	Center toolbar (left)
Home	Page navigation dropdown	Center toolbar (right)
Add Page	`addNewPage()`	Center toolbar
Rename	`renamePage()`	Center toolbar
Delete	`deletePage()`	Center toolbar
Undo/Redo	Change history (placeholder)	Center toolbar
Preview	`openPreview()`	Right sidebar
Load Existing	`loadExistingWebApp()`	Right sidebar
Save	`saveWebsite()`	Right sidebar
Visual Editor	`openVisualEditor()`	Right sidebar
Template	`openTemplateGallery()`	Right sidebar
Publish	`publishWebsite()`	Right sidebar

File Locations

Builder: /builder/chat/index.html
Legacy Builder: /builder/chat/archive/index-legacy.html
Theme Support: Uses theme-loader.js for user-saved themes

API Endpoints

Authentication

Method	Endpoint	Description
POST	`/api/auth/login`	User login
POST	`/api/auth/signup`	User registration
POST	`/api/auth/verify-pin`	PIN verification

Websites

Method	Endpoint	Description
GET	`/api/websites`	List user websites
GET	`/api/websites/:id`	Get website details
POST	`/api/websites`	Create new website
PUT	`/api/websites/:id`	Update website
DELETE	`/api/websites/:id`	Delete website

PODS Architecture

Frontend PODS

POD	Location	Version	Purpose
Websites	`dashboard/websites/`	v1.2.1	Website management
Templates	`dashboard/templates/`	v1.0.0	Template management

Backend PODS

POD	Location	Purpose
Prompts	`server/pods/prompts/`	Prompt history API

Environment Variables

PORT=3016
DB_HOST=localhost
DB_USER=vibecode
DB_PASSWORD=vcb123secure
DB_NAME=vibecode_builder
JWT_SECRET=vcb_production_secret_key_2026_pro
OPENROUTER_API_KEY=sk-or-v1-...
NODE_ENV=production
AI_PROVIDER=rosie
VCB_BRIDGE_URL=http://127.0.0.1:3016

Deployment

Start Server (via PM2)

cd /opt/vibecode-builder/essentials/app/server
pm2 start index.js --name vcb-essentials
pm2 save

Manual Start (for testing)

cd /opt/vibecode-builder/essentials/app/server
node index.js

Note: .env file in parent directory is symlinked to server/ for proper config loading

Development Notes

Current Status

✅ Landing page cloned and operational
✅ Server running on port 3020
✅ Cloudflare tunnel configured
✅ Database connection established
✅ "Essentials Edition" branding applied

Known Issues

User dashboard is placeholder only
Builder page not yet cloned
Rosie welcome message disabled (multiline string bug)

Builder Tools

Tool	Location	Status
AI Chat Builder	`/builder/chat/`	Active
WYSIWYG Editor	`/builder/wysiwyg/`	Active
Forms Maker	`/builder/forms/`	v1.0
Database Creator	`/builder/database/`	v2.0
Idea Factory	`/builder/idea-factory/`	Active
Template Gallery	`/builder/template-gallery/`	Active

Dashboard Pages

Page	Location	Description
Dashboard Home	`/dashboard/`	Main dashboard with sidebar
My Websites	`/dashboard/websites/`	Website management
My Templates	`/dashboard/user-templates/`	Template management
My Forms	`/dashboard/forms.html`	Form management
My Data	`/dashboard/my-data/`	Database management
Design Library	`/design-library/`	Image/PDF management

Current Status

✅ Modular folder structure implemented
✅ Forms system with email notifications
✅ Database system with SQLite
✅ 16 themes with theme loader
✅ Design Library integration
✅ User dashboard with sidebar navigation
✅ Technical and User guides

Server Location: /opt/vibecode-builder/essentials/

Server Log: /root/.pm2/logs/vcb-essentials-out.log

Backup Location: /archive/backups/

Zena Backup: /home/winston/backups/essentials/

Last Updated: 2026-05-23 | Version: 4.0 | Maintainer: Rosie (Operations)