# Quick Start Guide
## ⚠️ Hardware Requirements
**MULTIPLE MONITORS REQUIRED FOR OPTIMAL WORK ENVIRONMENT**
- **Minimum**: 2 monitors (webapp + one environment app)
- **Recommended**: 3-4 monitors (webapp + Unity3D + Resonite + VRChat/VRoid)
- **Optimal**: 4+ monitors for full multi-app workflow
**Why?** The robotics webapp is designed for professional multi-monitor control stations. Single monitor setups work but require constant alt-tabbing, reducing efficiency and real-time monitoring capabilities.
See [Hardware Requirements](./HARDWARE_REQUIREMENTS.md) for detailed specifications.
## ⚠️ IMPORTANT: Mock Data vs Real Data
**The robotics webapp runs in MOCK DATA mode by default.** This allows you to explore the interface without setting up MCP servers.
**To enable REAL functionality**, you must:
1. Set up the required MCP servers (see [MCP_SETUP.md](./MCP_SETUP.md))
2. Start the MCP servers
3. Start the backend
4. Start the frontend
The webapp will clearly indicate when mock data is being used with red warning banners.
## Quick Start (Mock Data Mode)
### 1. Install Dependencies
```powershell
cd D:\Dev\repos\robotics-webapp
npm install
```
### 2. Start Frontend (Development)
```powershell
npm run dev
```
The app will be available at `http://localhost:4444` (or the port shown in terminal).
**Note:** Without the backend and MCP servers, you'll see "MOCK DATA MODE" warnings on all pages.
## Quick Start (Real Data Mode)
### 1. Set Up MCP Servers
Follow the detailed guide in [MCP_SETUP.md](./MCP_SETUP.md) to:
- Install all 7 MCP servers (Unity3D, VRChat, Avatar, OSC, VRoid, Resonite, Local LLM)
- Configure them
- Start them on their respective ports (8001-8007)
**For AI/LLM features**, also set up:
- Ollama (for local models) - See [AI/LLM Features](./AI_LLM_FEATURES.md)
- LM Studio (optional, for local models)
- Cloud API keys (optional, OpenAI, Anthropic, Google)
**For Workflow System**, see:
- [Workflow System Guide](./WORKFLOW_SYSTEM.md) - Create and execute preprogrammed flows
### 2. Start Backend
```powershell
cd D:\Dev\repos\robotics-webapp\backend
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
python main.py
```
Backend runs on `http://localhost:8354`
### 3. Start Frontend
```powershell
cd D:\Dev\repos\robotics-webapp
npm run dev
```
### 4. Verify Connection
- Check each page for green "MCP Server Connected" banners
- If you see red "MOCK DATA MODE" banners, check:
- MCP servers are running
- Backend can reach MCP servers
- Ports are not blocked
## Status Indicators
### 🟢 Green Banner
**"MCP Server Connected - Using real data"**
- MCP server is running and accessible
- Real tool calls are being made
- Data is coming from actual MCP servers
### 🔴 Red Banner
**"MOCK DATA MODE - MCP Server Not Connected"**
- MCP server is not running or not accessible
- Using simulated/mock data
- Tool calls are simulated (not real)
### 🟡 Yellow Banner
**"Checking connection..."**
- Currently checking MCP server status
- Will update to green or red shortly
## What Works in Mock Mode?
- ✅ All UI pages and navigation
- ✅ Visual interface exploration
- ✅ Simulated data display
- ✅ Mock tool call responses
## What Requires Real MCP Servers?
- ❌ Actual Unity3D scene manipulation
- ❌ Real VRChat avatar control
- ❌ Live VRM avatar loading
- ❌ Real OSC communication
- ❌ Actual VRoid Studio automation
- ❌ Live Resonite world management
## Next Steps
1. **Explore Mock Mode**: Run `npm run dev` and explore the interface
2. **Read Setup Guide**: See [MCP_SETUP.md](./MCP_SETUP.md) for detailed setup
3. **Enable Real Mode**: Set up MCP servers to unlock full functionality
4. **Check Status**: Look for green banners indicating real connections
## Troubleshooting
### "MOCK DATA MODE" on all pages?
1. Check if backend is running: `http://localhost:8354/api/health`
2. Check if MCP servers are running (see [MCP_SETUP.md](./MCP_SETUP.md))
3. Check backend logs for connection errors
4. Verify environment variables in `backend/.env`
### Backend won't start?
1. Check Python version: `python --version` (needs 3.8+)
2. Install dependencies: `pip install -r requirements.txt`
3. Check port 8354 is not in use
4. Review error messages in terminal
### Frontend won't start?
1. Check Node.js version: `node --version` (needs 18+)
2. Clear cache: `rm -rf node_modules package-lock.json && npm install`
3. Check port 4444 is not in use
4. Review error messages in terminal
## Support
- **Setup Issues**: See [MCP_SETUP.md](./MCP_SETUP.md)
- **Architecture**: See [MCP_INTEGRATION.md](./MCP_INTEGRATION.md)
- **AI/LLM Features**: See [AI_LLM_FEATURES.md](./AI_LLM_FEATURES.md)
- **Code Quality**: See [CODE_QUALITY.md](./CODE_QUALITY.md)
- **Development**: See [docs/DEVELOPMENT_WORKFLOW_2025.md](./DEVELOPMENT_WORKFLOW_2025.md)
