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)

cd backend
npm install
cd ..

Note: This takes 3-5 minutes on first run. If you see PowerShell execution policy errors, use:

cmd /c "cd backend && npm install"

Step 2: Install Dependencies (Frontend)

cd frontend
npm install
cd ..

Step 3: Start Database & File Storage

docker-compose up -d

Verify services are running:

docker-compose ps
# Should show:
# - nutshell_postgres (healthy)
# - nutshell_file_storage (running)

Step 4: Start Backend API

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)

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

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

VITE_API_URL=http://localhost:3001/api

---

🐳 Docker Commands

# 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

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

Verify OTP

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

# Change in frontend/vite.config.ts:
# server: { port: 3001 }

Port 3001 already in use

# Change in backend/.env:
# PORT=3002

Port 5432 already in use

# Change in backend/.env:
# DATABASE_PORT=5433
# And update docker-compose.yml

npm install hangs

# Try using npm ci instead
npm ci

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

Database connection refused

# 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

# 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! 🎉