feat: setup integrated monorepo system with shared packages, API gateway and comprehensive documentation

.npmrc

@@ -0,0 +1,5 @@
+shamefully-hoist=true
+strict-peer-dependencies=false
+public-hoist-pattern[]=*eslint*
+public-hoist-pattern[]=*prettier*
+public-hoist-pattern[]=*typescript*

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)