Aggregator/QUICK_START.md

# Quick Start Guide - Nutshell MVP

## ⚡ 5-Minute Setup

### Prerequisites
- Node.js 18+ installed
- Docker & Docker Compose installed
- Git (optional)

### Step 1: Install Dependencies (Backend)

```bash
cd backend
npm install
cd ..
```

**Note**: This takes 3-5 minutes on first run. If you see PowerShell execution policy errors, use:
```bash
cmd /c "cd backend && npm install"
```

### Step 2: Install Dependencies (Frontend)

```bash
cd frontend
npm install
cd ..
```

### Step 3: Start Database & File Storage

```bash
docker-compose up -d
```

Verify services are running:
```bash
docker-compose ps
# Should show:
# - nutshell_postgres (healthy)
# - nutshell_file_storage (running)
```

### Step 4: Start Backend API

```bash
cd backend
npm run dev
```

You should see:
```
✓ Database connection established
✓ API server running on http://localhost:3001
✓ Health check: http://localhost:3001/api/health
```

### Step 5: Start Frontend (New Terminal)

```bash
cd frontend
npm run dev
```

You should see:
```
  VITE v4.x.x  ready in xxx ms

  ➜  Local:   http://localhost:3000/
```

### Step 6: Test the App

1. Open browser: **http://localhost:3000**
2. You should see the Nutshell homepage with 3 service cards
3. Click "Login" → Enter phone (any format, e.g., "+7 999 123 45 67")
4. Check terminal for OTP code (appears as `[MOCK SMS] OTP for ...`)
5. Enter the 6-digit OTP
6. You're logged in! 🎉

---

## 📝 Environment Setup

### Backend Configuration

**File**: `backend/.env`

```env
NODE_ENV=development
PORT=3001
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=nutshell
DATABASE_PASSWORD=nutshell_dev_password
DATABASE_NAME=nutshell_db
JWT_SECRET=your_jwt_secret_key_change_this_in_production
SMS_PROVIDER=mock  # Use 'mock' for development (logs to console)
```

### Frontend Configuration

**File**: `frontend/.env`

```env
VITE_API_URL=http://localhost:3001/api
```

---

## 🐳 Docker Commands

```bash
# Start all services
docker-compose up -d

# Stop services
docker-compose down

# View service status
docker-compose ps

# View logs
docker-compose logs postgres    # Database logs
docker-compose logs             # All services

# Reset database (delete all data)
docker-compose down -v
docker-compose up -d

# Access PostgreSQL CLI
docker exec -it nutshell_postgres psql -U nutshell -d nutshell_db
```

---

## 📱 Testing the API

### Request OTP
```bash
curl -X POST http://localhost:3001/api/auth/request-otp \
  -H "Content-Type: application/json" \
  -d '{"phone": "+7 999 123 45 67"}'
```

### Verify OTP
```bash
curl -X POST http://localhost:3001/api/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{"phone": "+7 999 123 45 67", "otp": "123456"}'
```

Response includes JWT token and user info.

---

## 🔧 Troubleshooting

### Port 3000 already in use
```bash
# Change in frontend/vite.config.ts:
# server: { port: 3001 }
```

### Port 3001 already in use
```bash
# Change in backend/.env:
# PORT=3002
```

### Port 5432 already in use
```bash
# Change in backend/.env:
# DATABASE_PORT=5433
# And update docker-compose.yml
```

### npm install hangs
```bash
# Try using npm ci instead
npm ci

# Or clear cache
npm cache clean --force
npm install
```

### Database connection refused
```bash
# Ensure PostgreSQL is running
docker-compose ps

# If not healthy, restart:
docker-compose restart postgres
docker-compose logs postgres
```

### Can't connect to API from frontend
```bash
# Check backend is running on port 3001
curl http://localhost:3001/api/health

# Check frontend .env has correct API URL
cat frontend/.env

# Or update vite proxy in vite.config.ts
```

---

## 📊 Project Structure

```
D:\Nutshell\Site Aggreagator\
├── backend/                    # Node.js API (Phase 1 ✓)
│   ├── src/
│   │   ├── app.ts             # Express server
│   │   ├── database.ts        # TypeORM config
│   │   ├── entities/          # Database models
│   │   ├── middleware/        # Auth, validation
│   │   ├── routes/            # API endpoints
│   │   └── services/          # Business logic
│   ├── package.json
│   ├── tsconfig.json
│   └── .env.example
├── frontend/                   # React SPA (Phase 3 prep)
│   ├── src/
│   │   ├── pages/             # Page components
│   │   ├── components/        # Reusable components
│   │   ├── context/           # Auth context
│   │   ├── i18n/              # Translations
│   │   └── utils/             # API client
│   ├── index.html
│   ├── package.json
│   └── vite.config.ts
├── processing/                 # Python (Phase 2 prep)
│   └── model_validator.py
├── docker-compose.yml         # Services config
├── README.md                  # Full documentation
└── QUICK_START.md            # This file
```

---

## ✅ Verification Checklist

- [ ] Node.js installed: `node --version`
- [ ] Docker running: `docker ps`
- [ ] Backend dependencies installed: `ls backend/node_modules`
- [ ] Frontend dependencies installed: `ls frontend/node_modules`
- [ ] PostgreSQL running: `docker-compose ps`
- [ ] Backend started: `http://localhost:3001/api/health` returns 200
- [ ] Frontend started: `http://localhost:3000` loads homepage
- [ ] Can request OTP via API or frontend login
- [ ] Can verify OTP and receive JWT token
- [ ] Logged-in user sees Orders dashboard

---

## 🚀 Next Steps (Phases 2-7)

1. **Phase 2**: 3D model processing & cost calculation
2. **Phase 3**: Full frontend order flow
3. **Phase 4**: Engineer dashboard
4. **Phase 5**: Manager dashboard  
5. **Phase 6**: Multi-language support
6. **Phase 7**: Deployment & optimization

See `README.md` for detailed phase breakdown.

---

## 📞 Support

- **Backend API docs**: Check `/api/health` endpoint
- **Full documentation**: See `README.md`
- **Database schema**: Check `backend/src/entities/`
- **Issues**: Check terminal logs for error messages

Happy building! 🎉