From f0cb2555258d9ddd0a500a28dc773050eae6c206 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hu=E1=BB=B3nh=20Th=C6=B0ong?=
 <299259079+HuynhThuong0711@users.noreply.github.com>
Date: Sun, 5 Jul 2026 03:04:40 +0700
Subject: [PATCH] feat: setup integrated monorepo system with shared packages,
 API gateway and comprehensive documentation

---
 .npmrc              |   5 +
 ARCHITECTURE.md     | 379 ++++++++++++++++++++
 IMPLEMENTATION.md   | 840 ++++++++++++++++++++++++++++++++++++++++++++
 package.json        |  39 +-
 pnpm-workspace.yaml |   7 +
 5 files changed, 1263 insertions(+), 7 deletions(-)
 create mode 100644 .npmrc
 create mode 100644 ARCHITECTURE.md
 create mode 100644 IMPLEMENTATION.md
 create mode 100644 pnpm-workspace.yaml

diff --git a/.npmrc b/.npmrc
new file mode 100644
index 0000000..c4d9416
--- /dev/null
+++ b/.npmrc
@@ -0,0 +1,5 @@
+shamefully-hoist=true
+strict-peer-dependencies=false
+public-hoist-pattern[]=*eslint*
+public-hoist-pattern[]=*prettier*
+public-hoist-pattern[]=*typescript*
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..da0ffa2
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,379 @@
+# 🏗️ AI Agent Build System - Architecture Documentation
+
+## Table of Contents
+1. [System Overview](#system-overview)
+2. [Monorepo Structure](#monorepo-structure)
+3. [Service Architecture](#service-architecture)
+4. [Data Flow](#data-flow)
+5. [Technology Stack](#technology-stack)
+6. [Integration Points](#integration-points)
+7. [Deployment](#deployment)
+
+---
+
+## System Overview
+
+The AI Agent Build System is a **monorepo-based platform** that integrates:
+- **CodeXPR** (AI Code Explorer UI)
+- **Sandbox-Ai** (CLI Agent Builder)
+- **Unified Dashboard** (Chat + Tasks + Agent Management)
+- **API Gateway** (Service Orchestration)
+
+### Key Principles
+- ✅ Type-safe across all services
+- ✅ Real-time communication via WebSocket
+- ✅ Scalable microservices architecture
+- ✅ Shared business logic and types
+- ✅ Independent deployment capability
+
+---
+
+## Monorepo Structure
+
+```
+ai-agent-build-system/
+├── apps/                              # Frontend applications
+│   ├── web/                          # Main React dashboard (port 3000)
+│   │   ├── src/
+│   │   │   ├── components/           # Reusable React components
+│   │   │   ├── pages/                # Route pages (Chat, Tasks, Agent)
+│   │   │   ├── hooks/                # Custom React hooks
+│   │   │   ├── stores/               # Zustand state management
+│   │   │   ├── services/             # API client services
+│   │   │   ├── App.tsx               # Main router
+│   │   │   ├── main.tsx              # Entry point
+│   │   │   └── index.css             # Global styles
+│   │   ├── vite.config.ts            # Vite bundler config
+│   │   ├── tsconfig.json
+│   │   └── package.json
+│   └── sandbox-ai/                   # Sandbox CLI app (future)
+│
+├── services/                          # Microservices
+│   ├── api-gateway/                  # Main API Gateway (port 3001)
+│   │   ├── src/
+│   │   │   ├── index.ts              # Express server setup
+│   │   │   ├── routes/               # API route definitions
+│   │   │   ├── middleware/           # Auth, logging, etc.
+│   │   │   ├── websocket/            # WebSocket handlers
+│   │   │   └── utils/                # Helper functions
+│   │   ├── tsconfig.json
+│   │   └── package.json
+│   ├── api-server/                   # Chat & Task service (port 3002)
+│   │   ├── src/
+│   │   │   ├── index.ts
+│   │   │   ├── routes/
+│   │   │   ├── db/                   # Drizzle ORM setup
+│   │   │   └── services/
+│   │   └── package.json
+│   └── agent-service/                # Agent orchestration (port 3003)
+│       ├── src/
+│       ├── package.json
+│
+├── packages/                          # Shared packages
+│   ├── types/                        # TypeScript interfaces & types
+│   │   ├── src/
+│   │   │   ├── index.ts              # Main exports
+│   │   │   ├── api.ts                # API types
+│   │   │   ├── domain.ts             # Domain models
+│   │   │   └── events.ts             # Event types
+│   │   ├── tsconfig.json
+│   │   └── package.json
+│   ├── utils/                        # Utility functions
+│   │   ├── src/
+│   │   │   ├── index.ts
+│   │   │   ├── helpers.ts            # General helpers
+│   │   │   ├── validators.ts         # Input validation
+│   │   │   └── formatters.ts         # Data formatting
+│   │   └── package.json
+│   └── shared/                       # Shared exports
+│       ├── src/index.ts
+│       └── package.json
+│
+├── docker-compose.yml                 # Local dev environment
+├── .env.example                       # Environment template
+├── pnpm-workspace.yaml                # Workspace configuration
+├── turbo.json                         # Turbo build config
+├── tsconfig.json                      # Root TypeScript config
+├── package.json                       # Root package.json
+├── ARCHITECTURE.md                    # This file
+├── IMPLEMENTATION.md                  # Step-by-step setup guide
+└── README.md                          # Quick start guide
+```
+
+---
+
+## Service Architecture
+
+### 1. Frontend Layer (React App)
+
+**Port:** 3000
+**Purpose:** User interface for chat, task management, and agent configuration
+
+**Key Features:**
+- Real-time chat interface
+- Task dashboard with status tracking
+- Agent builder and configuration UI
+- Session history sidebar
+- Dark theme with Tailwind CSS
+
+**Technologies:**
+- React 18 with TypeScript
+- Vite for bundling
+- Zustand for state management
+- Framer Motion for animations
+- Axios for API calls
+- WebSocket for real-time updates
+
+### 2. API Gateway
+
+**Port:** 3001
+**Purpose:** Central routing and orchestration of all backend services
+
+**Responsibilities:**
+- Route requests to appropriate microservices
+- Handle WebSocket connections
+- Authentication & authorization
+- Request/response transformation
+- Rate limiting and caching
+- Logging and monitoring
+
+**Routes:**
+```
+GET  /health              → Health check
+GET  /api/chat/*          → Chat service
+GET  /api/tasks/*         → Task service
+GET  /api/agent/*         → Agent service
+GET  /api/repos/*         → Repository service
+WS   ws://*/socket        → WebSocket endpoint
+```
+
+### 3. Chat & Task Service
+
+**Port:** 3002
+**Purpose:** Manage chat conversations and tasks
+
+**Endpoints:**
+```
+POST   /chats             → Create chat
+GET    /chats             → List chats
+GET    /chats/:id         → Get chat details
+PUT    /chats/:id         → Update chat
+DELETE /chats/:id         → Delete chat
+
+POST   /messages          → Create message
+GET    /messages/:chatId  → Get chat messages
+
+POST   /tasks             → Create task
+GET    /tasks             → List tasks
+GET    /tasks/:id         → Get task details
+PUT    /tasks/:id         → Update task
+DELETE /tasks/:id         → Delete task
+```
+
+### 4. Agent Service
+
+**Port:** 3003
+**Purpose:** Orchestrate AI agents and automation workflows
+
+**Responsibilities:**
+- Agent lifecycle management
+- Workflow execution
+- Tool integration (GitHub, OpenAI, etc.)
+- Event handling and callbacks
+- Result processing and storage
+
+### 5. Database Layer
+
+**PostgreSQL (Port 5432)**
+- Main data store
+- Schema managed by Drizzle ORM
+- Tables: users, chats, messages, tasks, agents, sessions
+
+**Redis (Port 6379)**
+- Session cache
+- Real-time state synchronization
+- Message queue for async jobs
+- WebSocket connection management
+
+---
+
+## Data Flow
+
+### User Chat Interaction
+
+```
+┌─────────────┐
+│  React App  │
+│  (Port 3000)│
+└──────┬──────┘
+       │ WebSocket
+       │ JSON payload
+       ▼
+┌─────────────────────────┐
+│   API Gateway           │
+│   (Port 3001)           │
+│   ├─ Validate input     │
+│   ├─ Authenticate user  │
+│   └─ Route to service   │
+└──────┬──────────────────┘
+       │ HTTP/gRPC
+       ▼
+┌──────────────────────────┐
+│  Chat Service            │
+│  (Port 3002)             │
+│  ├─ Store message        │
+│  ├─ Call AI API (OpenAI) │
+│  └─ Generate response    │
+└──────┬───────────────────┘
+       │
+       ├─→ PostgreSQL (Store)
+       ├─→ Redis (Cache)
+       └─→ WebSocket (Broadcast)
+       │
+       ▼
+┌──────────────────┐
+│  React App       │
+│  Receives update │
+│  Rerender UI     │
+└──────────────────┘
+```
+
+### Task Execution Flow
+
+```
+┌────────────────┐
+│  User Creates  │
+│  Task (React)  │
+└────────┬───────┘
+         │
+         ▼
+┌─────────────────────┐
+│  API Gateway        │
+│  POST /api/tasks    │
+└────────┬────────────┘
+         │
+         ▼
+┌─────────────────────┐
+│  Task Service       │
+│  1. Create record   │
+│  2. Set status:queued
+└────────┬────────────┘
+         │
+         ├→ PostgreSQL
+         ├→ Redis queue
+         └→ Emit event
+         │
+         ▼
+┌──────────────────┐
+│  Agent Service   │
+│  Picks up task   │
+└────────┬─────────┘
+         │
+         ├─→ 1. Analyze
+         ├─→ 2. Plan
+         ├─→ 3. Execute
+         ├─→ 4. Verify
+         │
+         ▼
+┌──────────────────┐
+│  Update task     │
+│  status:completed│
+└────────┬─────────┘
+         │
+         ├→ PostgreSQL
+         ├→ Notify user
+         └→ WebSocket update
+```
+
+---
+
+## Technology Stack
+
+### Frontend
+- **React 18** - UI framework
+- **TypeScript 5.9** - Type safety
+- **Vite 5** - Module bundler
+- **Zustand** - State management
+- **Framer Motion** - Animations
+- **Tailwind CSS** - Styling
+- **Axios** - HTTP client
+- **WebSocket** - Real-time communication
+
+### Backend
+- **Node.js 18+** - Runtime
+- **Express 5** - Web framework
+- **TypeScript** - Type safety
+- **PostgreSQL** - Primary database
+- **Redis** - Cache & queue
+- **Drizzle ORM** - Database abstraction
+- **Pino** - Logging
+- **Zod** - Input validation
+
+### Monorepo & Build
+- **pnpm** - Package manager
+- **Turbo** - Build orchestration
+- **esbuild** - JavaScript bundler
+- **ts-node** - TypeScript execution
+
+### DevOps
+- **Docker** - Containerization
+- **Docker Compose** - Orchestration
+- **GitHub Actions** - CI/CD
+
+---
+
+## Integration Points
+
+### CodeXPR Integration
+- UI components from CodeXPR merged into unified dashboard
+- Chat interface reused
+- Task management system inherited
+- GitHub integration maintained
+
+### Sandbox-Ai Integration
+- CLI commands available via web UI
+- Agent execution engine integrated
+- Session history sync'd
+- Real-time output streaming
+
+### External APIs
+- **OpenAI API** - AI chat and code generation
+- **GitHub API** - Repository operations
+- **Authentication Providers** - Google OAuth, GitHub OAuth
+
+---
+
+## Deployment
+
+### Local Development
+```bash
+pnpm install
+pnpm dev
+```
+
+### Docker Compose (Recommended)
+```bash
+pnpm docker:build
+pnpm docker:up
+```
+
+### Production
+```bash
+pnpm build
+DOCKER_BUILDKIT=1 docker build -t ai-agent-build .
+docker run -d -p 80:3000 ai-agent-build
+```
+
+### Environment Configuration
+See `.env.example` for all required variables.
+
+---
+
+## Next Steps
+
+1. Install dependencies: `pnpm install`
+2. Setup database: `pnpm db:migrate`
+3. Start development: `pnpm dev`
+4. Open browser: http://localhost:3000
+
+For detailed implementation guide, see [IMPLEMENTATION.md](./IMPLEMENTATION.md)
diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md
new file mode 100644
index 0000000..bad0f86
--- /dev/null
+++ b/IMPLEMENTATION.md
@@ -0,0 +1,840 @@
+# 📋 AI Agent Build System - Implementation Guide
+
+## Phase-by-Phase Development Guide
+
+This document provides a complete, step-by-step guide to build, maintain, and extend the integrated AI Agent Build System from zero to production.
+
+### Table of Contents
+1. [Phase 0: Prerequisites & Setup](#phase-0-prerequisites--setup)
+2. [Phase 1: Environment Configuration](#phase-1-environment-configuration)
+3. [Phase 2: Database Setup](#phase-2-database-setup)
+4. [Phase 3: Backend Development](#phase-3-backend-development)
+5. [Phase 4: Frontend Development](#phase-4-frontend-development)
+6. [Phase 5: Integration & Testing](#phase-5-integration--testing)
+7. [Phase 6: Deployment](#phase-6-deployment)
+8. [Maintenance & Troubleshooting](#maintenance--troubleshooting)
+9. [Common Workflows](#common-workflows)
+
+---
+
+## Phase 0: Prerequisites & Setup
+
+### Step 0.1: System Requirements
+
+```bash
+# Check Node.js version (>= 18.0.0)
+node --version
+# Expected: v18.x.x or higher
+
+# Check npm version
+npm --version
+# Expected: 9.x.x or higher
+
+# Install pnpm globally
+npm install -g pnpm@latest
+
+# Verify pnpm
+pnpm --version
+# Expected: 8.x.x or higher
+```
+
+**Required Software:**
+- Node.js 18+ (https://nodejs.org/)
+- pnpm 8+ (https://pnpm.io/)
+- Docker & Docker Compose (https://www.docker.com/)
+- Git (https://git-scm.com/)
+
+### Step 0.2: Clone & Navigate
+
+```bash
+# Clone the repository
+git clone https://github.com/HuynhThuong0711/CodeXPR.git
+cd CodeXPR
+
+# Checkout the integrated-system branch
+git checkout feat/integrated-system
+
+# Verify you're on the right branch
+git branch
+# Output: * feat/integrated-system
+#           main
+
+# View the new structure
+ls -la
+```
+
+### Step 0.3: Initial Project Structure Check
+
+```bash
+# Verify all key directories exist
+test -d packages/types && echo "✓ packages/types" || echo "✗ packages/types missing"
+test -d packages/utils && echo "✓ packages/utils" || echo "✗ packages/utils missing"
+test -d apps/web && echo "✓ apps/web" || echo "✗ apps/web missing"
+test -d services/api-gateway && echo "✓ services/api-gateway" || echo "✗ services/api-gateway missing"
+test -f pnpm-workspace.yaml && echo "✓ pnpm-workspace.yaml" || echo "✗ pnpm-workspace.yaml missing"
+test -f docker-compose.yml && echo "✓ docker-compose.yml" || echo "✗ docker-compose.yml missing"
+```
+
+---
+
+## Phase 1: Environment Configuration
+
+### Step 1.1: Copy Environment Template
+
+```bash
+# Copy the example environment file
+cp .env.example .env
+
+# List what was created
+ls -la | grep env
+```
+
+### Step 1.2: Configure Local Development Variables
+
+Edit `.env` file:
+
+```bash
+nano .env
+# Or use your editor: code .env, vim .env, etc.
+```
+
+Required configurations:
+
+```bash
+# Database
+DATABASE_URL="postgresql://ai-agent:dev-password@localhost:5432/ai_agent_db"
+REDIS_URL="redis://localhost:6379"
+
+# API Server
+API_PORT=3001
+API_HOST=0.0.0.0
+NODE_ENV=development
+LOG_LEVEL=debug
+
+# Web App
+VITE_API_URL=http://localhost:3001
+VITE_WS_URL=ws://localhost:3001
+VITE_APP_ENV=development
+
+# GitHub (Get from https://github.com/settings/tokens)
+VITE_GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+VITE_GITHUB_API_URL=https://api.github.com
+
+# OpenAI (Get from https://platform.openai.com/api-keys)
+VITE_OPENAI_API_KEY=sk-xxxxxxxxxxxxx
+VITE_OPENAI_MODEL=gpt-4o
+
+# Authentication
+AUTH_SECRET=your_random_secret_string_here
+GOOGLE_CLIENT_ID=xxxx.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=your_secret_here
+GITHUB_CLIENT_ID=your_github_app_id
+GITHUB_CLIENT_SECRET=your_github_secret
+```
+
+### Step 1.3: Verify Configuration
+
+```bash
+# Check that .env file is readable
+cat .env | head -20
+
+# Verify it's not committed (should be in .gitignore)
+git status | grep .env
+# Should NOT show .env as tracked
+
+# Make sure it's in gitignore
+echo ".env" >> .gitignore
+echo ".env.local" >> .gitignore
+```
+
+---
+
+## Phase 2: Database Setup
+
+### Step 2.1: Start Database Services
+
+**Option A: Using Docker (Recommended)**
+
+```bash
+# Build Docker images
+pnpm docker:build
+
+# Start services
+pnpm docker:up
+
+# Verify services are running
+docker ps
+# Should see: postgres, redis, api-server, web containers running
+
+# Check PostgreSQL is ready
+pnpm docker:logs postgres
+# Look for: "database system is ready to accept connections"
+```
+
+**Option B: Manual Setup**
+
+```bash
+# Install PostgreSQL 16 (macOS example with Homebrew)
+brew install postgresql@16
+brew services start postgresql@16
+
+# Install Redis
+brew install redis
+brew services start redis
+
+# Verify PostgreSQL
+psql --version
+# Expected: psql (PostgreSQL) 16.x
+
+# Create database
+psql -U postgres -c "CREATE DATABASE ai_agent_db;"
+psql -U postgres -c "CREATE USER 'ai-agent' WITH PASSWORD 'dev-password';"
+psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE ai_agent_db TO 'ai-agent';"
+
+# Verify connection
+psql -U ai-agent -d ai_agent_db -c "SELECT 1;"
+```
+
+### Step 2.2: Install Dependencies
+
+```bash
+# Clear any existing node_modules
+rm -rf node_modules
+rm -rf pnpm-lock.yaml
+
+# Install all workspace dependencies
+pnpm install
+
+# This will:
+# ✓ Download packages from npm
+# ✓ Link workspace packages
+# ✓ Setup symlinks
+# ✓ Install peer dependencies
+
+# Verify installation
+pnpm list --depth=0
+```
+
+### Step 2.3: Database Migration (If Applicable)
+
+```bash
+# When you add database schemas, run migrations
+# pnpm --filter @ai-agent/api-server run db:migrate
+
+# For now, just verify connection
+pnpm db:check 2>/dev/null || echo "DB schema check skipped (schema not yet created)"
+```
+
+---
+
+## Phase 3: Backend Development
+
+### Step 3.1: Understanding the API Gateway
+
+The API Gateway (port 3001) is the main entry point:
+
+```bash
+# Structure
+services/api-gateway/
+├── src/
+│   ├── index.ts           # Express server & WebSocket setup
+│   ├── routes/            # API route handlers
+│   ├── middleware/        # Auth, logging, error handling
+│   └── websocket/         # Real-time communication
+├── package.json
+└── tsconfig.json
+```
+
+### Step 3.2: Start API Gateway in Development
+
+```bash
+# Terminal 1: Start API Gateway
+pnpm dev:api
+
+# Expected output:
+# > @ai-agent/api-gateway dev
+# 🚀 API Gateway running on port 3001
+# WebSocket server ready at ws://localhost:3001
+
+# In Terminal 2: Test the gateway
+curl http://localhost:3001/health
+# Expected response:
+# {"status":"ok","timestamp":"2024-01-20T12:00:00.000Z"}
+```
+
+### Step 3.3: Understanding Backend Services
+
+Each service has its own responsibility:
+
+**API Gateway (Port 3001)**
+- Routes requests to appropriate services
+- Handles WebSocket connections
+- Authentication & authorization
+
+**Chat & Task Service (Port 3002) - Create Later**
+```bash
+# Services to create:
+# POST   /api/chat/create    → Create new chat
+# GET    /api/chat/list      → List chats
+# POST   /api/task/create    → Create task
+# GET    /api/task/list      → List tasks
+```
+
+### Step 3.4: Developing New Endpoints
+
+When adding new endpoints:
+
+```typescript
+// services/api-gateway/src/routes/example.ts
+import { Router } from 'express';
+
+const router = Router();
+
+// GET /api/example
+router.get('/', (req, res) => {
+  res.json({ message: 'Example endpoint' });
+});
+
+// POST /api/example
+router.post('/', (req, res) => {
+  const { data } = req.body;
+  // Process data
+  res.json({ success: true, data });
+});
+
+export default router;
+```
+
+Then register in `src/index.ts`:
+
+```typescript
+import exampleRouter from './routes/example';
+app.use('/api/example', exampleRouter);
+```
+
+---
+
+## Phase 4: Frontend Development
+
+### Step 4.1: Start Web Application
+
+```bash
+# Terminal 1: Already running API Gateway
+pnpm dev:api
+
+# Terminal 2: Start React web app
+pnpm dev:ui
+
+# Expected output:
+# > @ai-agent/web dev
+# VITE v5.0.8 ready in xxx ms
+# ➜  Local:   http://localhost:3000
+# ➜  press h to show help
+```
+
+### Step 4.2: Access the Application
+
+```bash
+# Open in browser
+open http://localhost:3000
+
+# Or manually:
+# - Chrome: http://localhost:3000
+# - Firefox: http://localhost:3000
+# - Safari: http://localhost:3000
+
+# Expected to see:
+# ✓ Logo and title: "🤖 AI Agent Builder"
+# ✓ Navigation menu: Chat, Tasks, Agent
+# ✓ Dark theme (background: #0d0f14)
+```
+
+### Step 4.3: Frontend Structure
+
+```bash
+apps/web/src/
+├── components/          # Reusable components
+│   ├── Layout.tsx       # Main layout
+│   ├── Header.tsx       # Header component
+│   └── ...
+├── pages/               # Page components
+│   ├── ChatView.tsx     # Chat page
+│   ├── TasksView.tsx    # Tasks page
+│   └── AgentView.tsx    # Agent page
+├── hooks/               # Custom React hooks
+│   ├── useApi.ts        # API calls
+│   ├── useWebSocket.ts  # WebSocket communication
+│   └── ...
+├── stores/              # Zustand state
+│   ├── chatStore.ts     # Chat state
+│   ├── taskStore.ts     # Task state
+│   └── ...
+├── services/            # API client
+│   ├── api.ts           # Axios instance
+│   ├── chatService.ts   # Chat API calls
+│   └── ...
+├── App.tsx              # Main router
+└── main.tsx             # Entry point
+```
+
+### Step 4.4: Adding a New Component
+
+```typescript
+// apps/web/src/components/ChatMessage.tsx
+import { motion } from 'framer-motion';
+import type { Message } from '@ai-agent/types';
+
+interface ChatMessageProps {
+  message: Message;
+}
+
+export function ChatMessage({ message }: ChatMessageProps) {
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 20 }}
+      animate={{ opacity: 1, y: 0 }}
+      className={`message message-${message.role}`}
+    >
+      <p>{message.content}</p>
+      <small>{new Date(message.createdAt).toLocaleTimeString()}</small>
+    </motion.div>
+  );
+}
+```
+
+### Step 4.5: Styling with Tailwind
+
+The app uses Tailwind CSS for styling:
+
+```html
+<!-- apps/web/src/components/Button.tsx -->
+<button className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition-colors">
+  Click me
+</button>
+```
+
+---
+
+## Phase 5: Integration & Testing
+
+### Step 5.1: Full Stack Development
+
+Run all services together:
+
+```bash
+# Terminal 1: Database + Redis
+pnpm docker:up
+
+# Terminal 2: API Gateway
+pnpm dev:api
+
+# Terminal 3: Web App
+pnpm dev:ui
+
+# All three running = full stack ready
+# Access at: http://localhost:3000
+```
+
+### Step 5.2: Testing API Endpoints
+
+```bash
+# Install curl (usually pre-installed)
+curl --version
+
+# Test health endpoint
+curl http://localhost:3001/health
+
+# Test chat endpoint
+curl -X GET http://localhost:3001/api/chat
+
+# Test with data (POST)
+curl -X POST http://localhost:3001/api/chat/create \
+  -H "Content-Type: application/json" \
+  -d '{"title":"My first chat"}'
+
+# Test WebSocket connection
+# Use a WebSocket client or browser console:
+const ws = new WebSocket('ws://localhost:3001');
+ws.onopen = () => ws.send('Hello!');
+ws.onmessage = (e) => console.log(e.data);
+```
+
+### Step 5.3: Type Safety Checking
+
+```bash
+# Check TypeScript compilation
+pnpm typecheck
+
+# Expected output:
+# ✓ No TypeScript errors
+
+# If errors occur, fix them immediately:
+pnpm typecheck 2>&1 | head -20  # See first 20 errors
+```
+
+### Step 5.4: Code Linting
+
+```bash
+# Check code quality
+pnpm lint
+
+# Format code automatically
+pnpm format
+
+# Verify files are formatted
+git diff --no-index /dev/null apps/web/src/App.tsx | head -5
+```
+
+---
+
+## Phase 6: Deployment
+
+### Step 6.1: Production Build
+
+```bash
+# Build all apps
+pnpm build
+
+# This runs:
+# 1. typecheck - Ensure types are correct
+# 2. build - Compile TypeScript to JavaScript
+# 3. Optimize bundles
+
+# Check build output
+ls -lah apps/web/dist/
+ls -lah services/api-gateway/dist/
+```
+
+### Step 6.2: Docker Deployment
+
+```bash
+# Build Docker image (production)
+DOCKER_BUILDKIT=1 docker build -t ai-agent-build:latest .
+
+# Run container
+docker run -d \
+  --name ai-agent-prod \
+  -p 80:3000 \
+  -e NODE_ENV=production \
+  -e DATABASE_URL="postgresql://..." \
+  ai-agent-build:latest
+
+# Check logs
+docker logs -f ai-agent-prod
+
+# Access at: http://localhost
+```
+
+### Step 6.3: Environment Variables for Production
+
+```bash
+# Create production .env file
+cat > .env.production << 'EOF'
+NODE_ENV=production
+DATABASE_URL=postgresql://user:pass@prod-db:5432/ai_agent_db
+REDIS_URL=redis://prod-redis:6379
+API_PORT=3001
+VITE_API_URL=https://api.yourdomain.com
+VITE_WS_URL=wss://api.yourdomain.com
+AUTH_SECRET=your_production_secret
+VITE_OPENAI_API_KEY=sk_prod_xxxxx
+VITE_GITHUB_TOKEN=ghp_prod_xxxxx
+EOF
+```
+
+### Step 6.4: Deploy to Cloud (Example: Heroku)
+
+```bash
+# Install Heroku CLI
+# https://devcenter.heroku.com/articles/heroku-cli
+
+# Login to Heroku
+heroku login
+
+# Create app
+heroku create ai-agent-builder
+
+# Set environment variables
+heroku config:set NODE_ENV=production --app ai-agent-builder
+heroku config:set DATABASE_URL=postgresql://... --app ai-agent-builder
+
+# Deploy
+git push heroku feat/integrated-system:main
+
+# View logs
+heroku logs --tail --app ai-agent-builder
+```
+
+---
+
+## Maintenance & Troubleshooting
+
+### Common Issues & Solutions
+
+#### Issue 1: "Port 3000 already in use"
+
+```bash
+# Find process using port 3000
+lsof -i :3000
+
+# Kill the process
+kill -9 <PID>
+
+# Or use different port
+VITE_PORT=3001 pnpm dev:ui
+```
+
+#### Issue 2: "Cannot find module '@ai-agent/types'"
+
+```bash
+# Reinstall dependencies
+pnpm install
+
+# Clear cache
+pnpm store prune
+
+# Verify symlinks
+ls -la node_modules/@ai-agent/
+```
+
+#### Issue 3: Database connection fails
+
+```bash
+# Check if PostgreSQL is running
+psql -U ai-agent -d ai_agent_db -c "SELECT 1;"
+
+# If not running, start it
+brew services start postgresql@16
+
+# Verify connection string in .env
+echo $DATABASE_URL
+
+# Test with psql
+psql $DATABASE_URL
+```
+
+#### Issue 4: WebSocket connection timeout
+
+```bash
+# Check API Gateway is running
+curl http://localhost:3001/health
+
+# Check WebSocket endpoint
+# In browser console:
+const ws = new WebSocket('ws://localhost:3001');
+console.log(ws.readyState);  // 0=CONNECTING, 1=OPEN, 2=CLOSING, 3=CLOSED
+
+# Restart API Gateway
+kill %1  # Stop dev:api
+pnpm dev:api  # Restart
+```
+
+#### Issue 5: TypeScript errors on build
+
+```bash
+# Check for type errors
+pnpm typecheck 2>&1
+
+# Fix with type annotations
+# Add explicit types to functions:
+function processData(input: string): string {
+  return input.toUpperCase();
+}
+
+# Not:
+function processData(input) {  // ❌ Missing type
+  return input.toUpperCase();
+}
+```
+
+### Regular Maintenance Tasks
+
+#### Weekly
+```bash
+# Update dependencies
+pnpm update
+
+# Run tests
+pnpm test
+
+# Check for security vulnerabilities
+pnpm audit
+```
+
+#### Monthly
+```bash
+# Backup database
+pg_dump ai_agent_db > backup_$(date +%Y%m%d).sql
+
+# Update Docker images
+docker pull postgres:16
+docker pull redis:7
+
+# Review logs for errors
+pnpm docker:logs
+```
+
+#### Quarterly
+```bash
+# Audit code quality
+pnpm lint
+
+# Type check everything
+pnpm typecheck
+
+# Update major dependencies
+pnpm update --interactive
+```
+
+---
+
+## Common Workflows
+
+### Workflow 1: Add a New Feature
+
+```bash
+# 1. Create feature branch
+git checkout -b feature/add-notifications
+
+# 2. Update types if needed
+# Edit: packages/types/src/index.ts
+# Add new interfaces
+
+# 3. Create backend endpoint
+# Create: services/api-gateway/src/routes/notifications.ts
+# Register in: services/api-gateway/src/index.ts
+
+# 4. Build and test
+pnpm dev:api
+curl http://localhost:3001/api/notifications
+
+# 5. Create frontend component
+# Create: apps/web/src/components/NotificationCenter.tsx
+
+# 6. Update types and test
+pnpm dev:ui
+# Test at http://localhost:3000
+
+# 7. Commit and push
+git add .
+git commit -m "feat: add notification system"
+git push origin feature/add-notifications
+
+# 8. Create pull request on GitHub
+```
+
+### Workflow 2: Debug Issue
+
+```bash
+# 1. Identify the issue
+echo "Describe what's broken"
+
+# 2. Start all services with logging
+NODE_DEBUG=* pnpm dev:api &
+pnpm dev:ui &
+pnpm docker:logs
+
+# 3. Test the endpoint
+curl -v http://localhost:3001/api/problematic-route
+
+# 4. Check browser console
+# Press F12 → Console → Look for errors
+
+# 5. Add console logs
+# Edit component/service and add:
+console.log('Debug info:', variable);
+
+# 6. Fix the issue
+# Edit the problematic file
+
+# 7. Verify fix
+pnpm typecheck
+pnpm lint
+
+# 8. Test thoroughly
+curl http://localhost:3001/api/fixed-route
+```
+
+### Workflow 3: Prepare for Production Release
+
+```bash
+# 1. Ensure all tests pass
+pnpm test
+
+# 2. Type check
+pnpm typecheck
+
+# 3. Lint
+pnpm lint
+
+# 4. Format code
+pnpm format
+
+# 5. Build
+pnpm build
+
+# 6. Test production build locally
+pnpm preview
+# Test at http://localhost:4173
+
+# 7. Update version
+# Edit: package.json
+# Change: "version": "1.0.1"
+
+# 8. Create changelog
+echo "## v1.0.1 - $(date +%Y-%m-%d)" >> CHANGELOG.md
+echo "- Fixed bug X" >> CHANGELOG.md
+echo "- Added feature Y" >> CHANGELOG.md
+
+# 9. Commit and tag
+git add .
+git commit -m "chore: release v1.0.1"
+git tag -a v1.0.1 -m "Release v1.0.1"
+
+# 10. Push to GitHub
+git push origin feat/integrated-system
+git push origin v1.0.1
+```
+
+---
+
+## Quick Reference
+
+### Essential Commands
+
+```bash
+pnpm install          # Install all dependencies
+pnpm dev              # Start all services
+pnpm dev:ui           # Start web app only
+pnpm dev:api          # Start API gateway only
+pnpm build            # Build for production
+pnpm typecheck        # Check TypeScript
+pnpm lint             # Check code quality
+pnpm format           # Auto-format code
+pnpm docker:build     # Build Docker images
+pnpm docker:up        # Start Docker services
+pnpm docker:down      # Stop Docker services
+pnpm docker:logs      # View Docker logs
+```
+
+### Useful URLs
+
+- **Web App:** http://localhost:3000
+- **API Gateway:** http://localhost:3001
+- **API Health:** http://localhost:3001/health
+- **WebSocket:** ws://localhost:3001
+- **PostgreSQL:** localhost:5432
+- **Redis:** localhost:6379
+
+### File Locations
+
+- **Environment:** `.env` (in project root)
+- **Types:** `packages/types/src/index.ts`
+- **API Gateway:** `services/api-gateway/src/index.ts`
+- **Web App:** `apps/web/src/App.tsx`
+- **Components:** `apps/web/src/components/`
+- **State:** `apps/web/src/stores/`
+
+---
+
+For more details, see [ARCHITECTURE.md](./ARCHITECTURE.md) and [README.md](./README.md)
diff --git a/package.json b/package.json
index c63433b..eb7157b 100644
--- a/package.json
+++ b/package.json
@@ -1,12 +1,37 @@
 {
-  "name": "codexpr-ai-craft-studio",
+  "name": "ai-agent-build-system",
+  "version": "1.0.0",
   "private": true,
-  "version": "0.1.0",
-  "type": "module",
+  "description": "Integrated AI-native agent build system with unified UI",
+  "license": "MIT",
   "scripts": {
-    "dev": "python3 -m http.server 5173",
-    "build": "node scripts/build.mjs",
-    "lint": "node scripts/lint.mjs",
-    "preview": "python3 -m http.server 4173 --directory dist"
+    "preinstall": "npx only-allow pnpm",
+    "install": "pnpm install",
+    "dev": "pnpm -r --parallel run dev",
+    "dev:ui": "pnpm --filter @ai-agent/web run dev",
+    "dev:api": "pnpm --filter @ai-agent/api-gateway run dev",
+    "dev:sandbox": "pnpm --filter @ai-agent/sandbox-ai run dev",
+    "build": "pnpm -r --if-present run build",
+    "build:ui": "pnpm --filter @ai-agent/web run build",
+    "build:api": "pnpm --filter @ai-agent/api-gateway run build",
+    "typecheck": "pnpm -r --if-present run typecheck",
+    "lint": "pnpm -r --if-present run lint",
+    "format": "prettier --write \"**/*.{ts,tsx,json,md}\"",
+    "test": "pnpm -r --if-present run test",
+    "clean": "pnpm -r --if-present exec rm -rf dist node_modules .turbo",
+    "docker:build": "docker-compose build",
+    "docker:up": "docker-compose up -d",
+    "docker:down": "docker-compose down",
+    "docker:logs": "docker-compose logs -f"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "prettier": "^3.1.0",
+    "typescript": "~5.9.2",
+    "turbo": "^1.10.16"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "pnpm": ">=8.0.0"
   }
 }
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
new file mode 100644
index 0000000..8a9be10
--- /dev/null
+++ b/pnpm-workspace.yaml
@@ -0,0 +1,7 @@
+packages:
+  - 'packages/*'
+  - 'apps/*'
+  - 'services/*'
+
+overrides:
+  typescript: '~5.9.2'