Skip to content

IMPLEMENTATION_GUIDE.md

Latest commit

 

History

History
569 lines (464 loc) · 12.2 KB

IMPLEMENTATION_GUIDE.md

File metadata and controls

569 lines (464 loc) · 12.2 KB

Implementation Guide - Virtual Development Platform

Quick Start

1. Installation & Setup

# Install dependencies (already done)
npm install

# Run development server
npm run dev

# Navigate to
http://localhost:3000/dashboard

2. Project Structure

project-root/
├── app/
│   ├── dashboard/
│   │   ├── layout.tsx       # Main layout with 3-column design
│   │   ├── page.tsx         # Projects list
│   │   └── [projectId]/
│   │       └── page.tsx     # Editor workspace
│   ├── api/
│   │   ├── projects/route.ts
│   │   ├── files/route.ts
│   │   ├── execute/route.ts
│   │   └── terminal/route.ts
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
│
├── components/
│   ├── TopBar.tsx          # Navigation & controls
│   ├── Sidebar.tsx         # File explorer
│   ├── Editor.tsx          # Monaco editor
│   ├── Terminal.tsx        # Terminal interface
│   ├── Preview.tsx         # Live preview & device emulation
│   └── modals/
│
├── lib/
│   ├── theme.ts            # Design tokens
│   ├── store.ts            # Zustand state management
│   ├── templates.ts        # Project templates
│   ├── execution-engine.ts # Code sandbox
│   ├── websocket.ts        # Real-time sync
│   └── api-routes.ts       # API documentation
│
├── public/
├── package.json
├── tsconfig.json
├── next.config.ts
└── ARCHITECTURE.md         # System architecture

Core Features Implementation

1. Monaco Editor Integration

File: components/Editor.tsx

import Editor from '@monaco-editor/react';

// Features:
// - Syntax highlighting for 100+ languages
// - IntelliSense & auto-completion
// - Multi-tab editing
// - Keyboard shortcuts (Ctrl+S to save)
// - Word wrap & line numbers
// - Theme integration with custom dark theme

Next Steps:

  • Add language detection from file extension
  • Implement code formatting (Prettier)
  • Add code snippets library
  • Enable collaborative editing markers

2. File System Management

File: lib/store.ts - FileNode operations

interface FileNode {
  id: string;
  name: string;
  path: string;
  type: 'file' | 'folder';
  language?: string;
  content?: string;
  children?: FileNode[];
}

TODO - Implement:

// API calls needed:
POST   /api/files              // Create file/folder
GET    /api/files/:projectId   // Fetch file tree
PUT    /api/files/:id          // Update content
DELETE /api/files/:id          // Delete file
POST   /api/files/:id/rename   // Rename
POST   /api/files/:id/move     // Move to folder

3. Code Execution Engine

File: lib/execution-engine.ts

Development Mode (VM2 or Sandbox)

async execute(options: ExecutionOptions) {
  // Supported languages: javascript, python, html, bash
  // Resource limits: 30s timeout, 256MB memory
  // Returns: { status, output, errorLog, durationMs }
}

Production Deployment

Option 1: Docker

FROM node:18-alpine
WORKDIR /sandbox
COPY code.js .
CMD timeout 30 node code.js

Option 2: Firecracker (Recommended)

  • Sub-100ms startup
  • Better isolation
  • Lower overhead

Option 3: AWS Lambda / Google Cloud Functions

  • Automatic scaling
  • Pay per execution

4. Real-Time WebSocket Communication

File: lib/websocket.ts

Client Setup

import { websocketManager, initializeWebSocket } from '@/lib/websocket';

// Initialize on app start
useEffect(() => {
  initializeWebSocket('http://localhost:3000');
}, []);

// Listen for events
websocketManager.on('terminal:output', (data) => {
  console.log(data.output);
});

// Emit events
websocketManager.executeCode(code, language, projectId);

Server Setup (Express with Socket.IO)

const io = require('socket.io')(server);

io.on('connection', (socket) => {
  // Handle terminal commands
  socket.on('terminal:command', async (data) => {
    const result = await executeInSandbox(data.command);
    socket.emit('terminal:output', { output: result });
  });

  // Handle code execution
  socket.on('execute:code', async (data) => {
    const result = await executionEngine.execute(data);
    socket.emit('execute:complete', { result });
  });
});

5. Project Templates

File: lib/templates.ts

Currently includes:

  • ✅ React App (Vite)
  • ✅ Next.js App
  • ✅ Node.js API
  • ✅ Python AI Script
  • ✅ Vanilla HTML/CSS/JS

To Add:

  • TypeScript templates
  • Vue.js / Svelte
  • Flutter emulation
  • Django / Flask
  • FastAPI

6. State Management with Zustand

File: lib/store.ts

const { 
  // Project management
  currentProject, setCurrentProject, projects, addProject,
  
  // Editor tabs
  openTabs, activeTabId, openTab, closeTab, setActiveTab,
  
  // File system
  selectedFileId, setSelectedFile, expandedFolders, toggleFolderExpanded,
  
  // Terminal
  terminalSession, addTerminalOutput, clearTerminal,
  
  // Execution
  isExecuting, lastExecution, setExecuting, setLastExecution,
  
  // UI State
  sidebarVisible, previewVisible, setSidebarVisible, setPreviewVisible,
  
  // Settings
  autoSave, theme, fontSize
} = useAppStore();

API Endpoints

Projects

POST   /api/projects              Create project
GET    /api/projects              List user's projects
GET    /api/projects/:id          Get project details
PUT    /api/projects/:id          Update project
DELETE /api/projects/:id          Delete project
POST   /api/projects/:id/export   Export as ZIP

Files

GET    /api/files?projectId=:id   Get file tree
POST   /api/files                 Create file
GET    /api/files/:id             Get file content
PUT    /api/files/:id             Update content
DELETE /api/files/:id             Delete file
POST   /api/files/:id/rename      Rename
POST   /api/files/:id/move        Move to folder

Execution

POST   /api/execute               Execute code
POST   /api/terminal/run          Run terminal command
POST   /api/packages/install      Install NPM package
DELETE /api/execute/:processId    Kill process

Deployment

POST   /api/deploy/preview        Generate preview
POST   /api/deploy/serverless     Deploy to cloud
GET    /api/deploy/:projectId/status  Check status

Authentication

POST   /api/auth/register         Register
POST   /api/auth/login            Login
POST   /api/auth/logout           Logout
POST   /api/auth/refresh          Refresh token

Database Schema

PostgreSQL Tables

-- Users
CREATE TABLE users (
  id UUID PRIMARY KEY,
  email VARCHAR UNIQUE NOT NULL,
  username VARCHAR UNIQUE NOT NULL,
  password_hash VARCHAR NOT NULL,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- Projects
CREATE TABLE projects (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  name VARCHAR NOT NULL,
  description TEXT,
  template_type VARCHAR NOT NULL,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW(),
  is_public BOOLEAN DEFAULT FALSE
);

-- Files
CREATE TABLE files (
  id UUID PRIMARY KEY,
  project_id UUID REFERENCES projects(id),
  path VARCHAR NOT NULL,
  content TEXT,
  language VARCHAR,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- Execution Logs
CREATE TABLE execution_logs (
  id UUID PRIMARY KEY,
  project_id UUID REFERENCES projects(id),
  command VARCHAR,
  output TEXT,
  error_log TEXT,
  status VARCHAR,
  duration_ms INTEGER,
  created_at TIMESTAMP DEFAULT NOW()
);

Component Implementation Checklist

Completed ✅

  • Theme system with scientific UI colors
  • Zustand store setup
  • TopBar component
  • Sidebar with file explorer
  • Monaco Editor integration
  • Terminal component
  • Preview panel with device emulation
  • Dashboard layout
  • Project templates
  • Execution engine
  • WebSocket setup

TODO

  • Authentication system (Login/Register)
  • API route implementations
  • Database integration (PostgreSQL)
  • File operations backend
  • Code execution in sandboxes
  • WebSocket server setup
  • Project export (ZIP)
  • Settings modal
  • Collaboration features
  • Deploy button integration
  • Share functionality
  • Revision history
  • AI code assistant
  • Plugin system

Environment Variables

Create .env.local:

# WebSocket
NEXT_PUBLIC_SOCKET_URL=http://localhost:3000

# API
NEXT_PUBLIC_API_URL=http://localhost:3000/api

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/devplatform

# Authentication
JWT_SECRET=your-secret-key-here

# Storage
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_S3_BUCKET=

# Execution Engine
DOCKER_HOST=tcp://localhost:2375
EXECUTION_TIMEOUT=30000
MEMORY_LIMIT=256

# Email
SMTP_HOST=
SMTP_PORT=
SMTP_USER=
SMTP_PASSWORD=

Development Commands

# Start dev server
npm run dev

# Build for production
npm run build

# Run production build
npm start

# Run linter
npm run lint

# Format code
npm run format

# Run tests (when added)
npm test

Performance Optimization

Frontend

  • Code splitting with dynamic imports
  • Image optimization
  • Service workers for offline support
  • Virtual scrolling for large file trees

Backend

  • Database connection pooling
  • Redis caching for frequently accessed files
  • CDN for static assets
  • Load balancing for WebSocket

Execution

  • Container image caching
  • Memory pooling for sandboxes
  • Lazy loading of dependencies

Security Checklist

  • HTTPS/WSS encryption
  • JWT token validation
  • CSRF protection
  • SQL injection prevention (use parameterized queries)
  • XSS prevention (sanitize HTML)
  • Sandbox resource limits
  • File path validation
  • Rate limiting
  • CORS configuration
  • Input validation

Deployment

Vercel (Frontend)

npm install -g vercel
vercel deploy

Docker (Full Stack)

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]
docker build -t devplatform .
docker run -p 3000:3000 devplatform

Kubernetes (Production Scale)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: devplatform
spec:
  replicas: 3
  selector:
    matchLabels:
      app: devplatform
  template:
    metadata:
      labels:
        app: devplatform
    spec:
      containers:
      - name: devplatform
        image: devplatform:latest
        ports:
        - containerPort: 3000
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: url

Testing Strategy

// Unit tests for components
// Integration tests for APIs
// E2E tests for user workflows
// Performance tests for execution engine

// Use Jest + React Testing Library
npm install --save-dev jest @testing-library/react

Monitoring & Logging

// Winston for logging
import winston from 'winston';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});

Next Steps

  1. Backend API Implementation

    • Set up Express server
    • Implement PostgreSQL integration
    • Add JWT authentication

  2. Sandbox Execution

    • Docker integration for code execution
    • Resource limit enforcement
    • Process management

  3. WebSocket Server

    • Socket.IO server setup
    • Event broadcasting
    • Message queuing

  4. Database

    • PostgreSQL setup
    • Prisma ORM integration
    • Migration scripts

  5. Testing

    • Unit test suite
    • Integration tests
    • E2E test automation

  6. Deployment

    • Docker containerization
    • Kubernetes manifests
    • CI/CD pipeline (GitHub Actions)

  7. Advanced Features

    • Collaboration/multi-user editing
    • AI-assisted code completion
    • Built-in deployment
    • Version control integration
    • Plugin marketplace