# Demure Workspace – Production Architecture & Development Specification

## Goal

Build Demure Workspace as a cloud-based Application Development Environment (ADE) similar to Replit, Bolt.new, Lovable, and Cursor.

This is not a chatbot with a code editor. It is a complete browser-based development environment with real-time editing, live preview, isolated workspaces, AI-assisted coding, and automatic application updates.

---

# Core Architecture

The platform should consist of the following services:

Frontend (React + TypeScript)

* File Explorer
* Code Editor (Monaco Editor)
* AI Chat
* Live Terminal
* Console
* Git Panel
* Database Panel
* Preview Panel (iframe)
* Project Settings

Backend API (Node.js + Express)

* Authentication
* Workspace Manager
* File Manager
* Build Manager
* AI Orchestrator
* Deployment Service
* Git Service
* Database Service
* WebSocket Gateway

Workspace Runtime

Every project must run inside its own isolated Docker container.

Each workspace contains a complete project:

/workspace/{project-id}

Inside each workspace:

package.json
vite.config.ts
src/
public/
node_modules/
.env
README.md

No project files should be stored inside the React frontend.

The backend owns all project files.

---

# Live Preview

The preview must not render React components directly.

Instead:

AI edits a file

↓

Backend writes file

↓

Filesystem updates

↓

Vite detects change

↓

Hot Module Replacement rebuilds affected modules

↓

Development server updates

↓

Preview iframe instantly reflects changes

The iframe should load a dedicated preview URL, not localhost.

Example:

https://preview.demure.app/workspace/{workspace-id}

Each workspace has its own preview URL.

---

# File Editing

The AI should never edit React state directly.

Instead:

Read project tree

↓

Read requested files

↓

Generate updated code

↓

Write file

↓

Save file

↓

Notify frontend via WebSocket

↓

Preview updates automatically

The backend is the single source of truth.

---

# WebSockets

Use WebSockets for:

* AI streaming
* Build progress
* File changes
* Terminal output
* Console logs
* Preview status
* Deployment progress
* Git status

Do not rely on polling.

---

# File Watching

Every workspace should run a file watcher.

When any file changes:

* Detect change
* Trigger Vite HMR
* Notify frontend
* Update preview automatically

No manual refresh.

---

# Preview Pipeline

User Prompt

↓

AI

↓

Generate code

↓

Write file

↓

Vite rebuild

↓

HMR

↓

Preview iframe updates

Target preview latency:

150–500 ms for normal edits.

---

# Folder Structure

Frontend

src/

app/

components/

features/

editor/

preview/

terminal/

files/

chat/

database/

deploy/

hooks/

services/

store/

utils/

styles/

types/

pages/

Backend

server/

routes/

controllers/

services/

workspace/

docker/

websocket/

filesystem/

build/

deployment/

git/

database/

auth/

ai/

models/

jobs/

shared/

Workspace

/workspace/{project}

src/

public/

package.json

vite.config.ts

node_modules/

---

# Preview Environment

Each project runs:

npm install

npm run dev

inside its Docker container.

The backend automatically creates and destroys containers.

Containers must be isolated.

---

# AI Responsibilities

The AI must:

* Read project files
* Understand project structure
* Edit existing files
* Create new files
* Delete files
* Rename files
* Run builds
* Run tests
* Stream progress
* Explain changes

The AI should never overwrite the entire project unless explicitly instructed.

---

# Frontend Features

Required panels:

* Explorer
* Search
* AI Chat
* Monaco Editor
* Terminal
* Console
* Live Preview
* Database Explorer
* Deploy Panel
* Git Panel
* Environment Variables
* Settings

Resizable panels.

Persistent layout.

Tabbed editor.

Multiple open files.

---

# Build Pipeline

When AI modifies code:

1. Save file
2. Trigger Vite
3. Build affected modules
4. HMR update
5. Preview refresh
6. Stream status to UI

The user should always see progress.

Example:

Reading files...

Updating components...

Installing dependencies...

Running Vite...

Compiling...

Refreshing preview...

Done.

---

# Performance Goals

Workspace startup:

< 5 seconds

Preview updates:

150–500 ms

AI streaming:

Immediate token streaming

Terminal latency:

Real-time

WebSocket reconnect:

Automatic

---

# Scalability

Use:

Docker containers

Redis

PostgreSQL

Object Storage

Nginx reverse proxy

WebSockets

Queue workers

Stateless backend services

Projects should scale to thousands of concurrent workspaces.

---

# Acceptance Criteria

The application should feel like a professional cloud IDE.

Users should be able to:

* Create projects
* Edit files
* Chat with AI
* Watch code stream live
* See preview update automatically
* Run terminal commands
* Install packages
* Connect databases
* Deploy applications
* Manage Git repositories

No manual page refreshes should ever be required for code changes.

The platform should be production-ready, modular, scalable, and maintainable.