Aggregator/README.md

# Nutshell Manufacturing Aggregator - MVP

**Status**: Phase 1 - Backend Bootstrap ✓

A web platform for managing manufacturing orders (3D printing, milling, turning) with automated model processing and cost calculation.

---

## Project Structure

```
D:\Nutshell\Site Aggreagator\
├── backend/                    # Node.js + Express API
│   ├── src/
│   │   ├── app.ts             # Main Express application
│   │   ├── database.ts        # TypeORM database connection
│   │   ├── entities/          # Database models
│   │   │   ├── User.ts        # User accounts (customer, engineer, manager, admin)
│   │   │   ├── Order.ts       # Manufacturing orders
│   │   │   ├── Model3D.ts     # 3D model files with validation data
│   │   │   ├── Pricing.ts     # Pricing configuration
│   │   │   └── Translation.ts # Multi-language strings
│   │   ├── middleware/
│   │   │   └── auth.ts        # JWT authentication middleware
│   │   ├── routes/
│   │   │   └── auth.ts        # Authentication endpoints (/auth/request-otp, /auth/verify-otp)
│   │   └── services/
│   │       └── AuthService.ts # OTP generation, verification, token creation
│   ├── package.json
│   ├── tsconfig.json
│   └── .env.example           # Environment variables template
├── frontend/                   # React SPA (Phase 3)
├── processing/                 # Python 3D model processing (Phase 2)
├── docker-compose.yml         # PostgreSQL + file storage services
├── nginx.conf                 # File storage server configuration
└── README.md                  # This file
```

---

## Phase 1: Backend Bootstrap - COMPLETE ✓

### Implemented

1. **Database Schema** (PostgreSQL with TypeORM)
   - `users` - Customer, engineer, manager, admin accounts
   - `orders` - Manufacturing order details (service type, status, costs, delivery)
   - `models` - 3D model files with validation results
   - `pricing` - Material costs, machine rates, markups
   - `translations` - Multi-language UI strings

2. **Authentication System**
   - SMS OTP generation and verification
   - JWT token creation (24-hour expiry)
   - Phone-based user creation (new users auto-registered)
   - Rate limiting on OTP requests

3. **API Endpoints** (Phase 1)
   - `POST /api/auth/request-otp` - Request OTP for phone
   - `POST /api/auth/verify-otp` - Verify OTP and get token
   - `GET /api/health` - Health check

4. **Infrastructure**
   - Docker Compose with PostgreSQL service
   - Nginx file storage container
   - TypeScript configuration
   - Express middleware (CORS, JSON parsing)

---

## Quick Start

### Prerequisites
- Node.js 18+
- Docker & Docker Compose
- PostgreSQL client (optional, for manual DB inspection)

### Setup

1. **Install dependencies**
   ```bash
   cd backend
   npm install
   ```

2. **Configure environment** (copy template)
   ```bash
   cp backend/.env.example backend/.env
   # Edit backend/.env if needed (defaults work for dev)
   ```

3. **Start services** (PostgreSQL + File Storage)
   ```bash
   docker-compose up -d
   ```

4. **Start API server**
   ```bash
   cd backend
   npm run dev
   ```
   Server runs at `http://localhost:3001`

5. **Test health endpoint**
   ```bash
   curl http://localhost:3001/api/health
   ```

---

## API Documentation

### Authentication Flow

#### 1. Request OTP
```bash
curl -X POST http://localhost:3001/api/auth/request-otp \
  -H "Content-Type: application/json" \
  -d '{"phone": "+7 (XXX) XXX-XXXX"}'
```

**Response**:
```json
{
  "success": true,
  "data": { "message": "OTP sent successfully" },
  "errors": [],
  "timestamp": "2026-07-15T10:30:00Z"
}
```

**Note**: In development mode (`SMS_PROVIDER=mock`), OTP is logged to console:
```
[MOCK SMS] OTP for 79991234567: 123456
```

#### 2. Verify OTP
```bash
curl -X POST http://localhost:3001/api/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{"phone": "+7 (XXX) XXX-XXXX", "otp": "123456"}'
```

**Response**:
```json
{
  "success": true,
  "data": {
    "token": "eyJhbGc...",
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phone": "79991234567",
      "role": "customer",
      "email": null,
      "name": null
    }
  },
  "errors": [],
  "timestamp": "2026-07-15T10:30:00Z"
}
```

#### 3. Use Token for Authenticated Requests
```bash
curl -X GET http://localhost:3001/api/orders \
  -H "Authorization: Bearer <token_from_verify_otp>"
```

---

## Database Management

### Docker Commands

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

# Stop services
docker-compose down

# View logs
docker-compose logs postgres

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

# View database schema
\dt          # List tables
\d orders    # Describe orders table
```

### Useful SQL Queries

```sql
-- View all users
SELECT id, phone, role, created_at FROM users;

-- View all orders
SELECT id, user_id, service_type, status, preliminary_cost, final_cost FROM orders;

-- View orders by status
SELECT status, COUNT(*) FROM orders GROUP BY status;
```

---

## Environment Variables

Edit `backend/.env` to configure:

```env
NODE_ENV=development                    # development | production
PORT=3001                               # API server port
DATABASE_HOST=localhost                 # PostgreSQL host
DATABASE_PORT=5432                      # PostgreSQL port
DATABASE_USER=nutshell                  # Database user
DATABASE_PASSWORD=nutshell_dev_password # Database password
DATABASE_NAME=nutshell_db               # Database name
JWT_SECRET=your_jwt_secret_key...      # Change in production!
JWT_EXPIRATION=24h                      # Token expiration
UPLOAD_DIR=/data/uploads                # File storage path
SMS_PROVIDER=mock                       # mock | twilio
```

---

## Next Phases

### Phase 2: 3D Model Processing & Cost Calculation
- Integrate Python trimesh for model validation
- Build `/api/models/validate` endpoint
- Build `/api/orders/{id}/cost` endpoint
- Three.js 3D preview component

### Phase 3: Frontend - React SPA
- Customer order flow pages
- 3D model preview + parameters
- Phone-based checkout
- Order tracking dashboard

### Phase 4: Engineer Dashboard
- Order validation interface
- Model review + notes editing
- Final cost approval

### Phase 5: Manager Dashboard
- Subcontractor assignment
- Pricing management
- Order analytics

### Phase 6: Multi-Language Support
- i18n integration
- Russian + English translation

### Phase 7: Deployment
- Production build & SSL setup
- Performance optimization
- Security hardening

---

## Development Notes

### TypeScript Compilation
```bash
cd backend
npm run build    # Compile to dist/
npm start        # Run compiled code
npm run dev      # Run with ts-node (watch mode)
```

### Adding New Routes
1. Create service in `src/services/`
2. Create route file in `src/routes/`
3. Import and register in `src/app.ts`

### Adding New Database Entities
1. Create entity file in `src/entities/`
2. Add to `AppDataSource.getRepository()` in service
3. TypeORM auto-creates/migrates schema on dev start

### Debugging
- Check logs: `docker-compose logs postgres`
- Test endpoints with Postman/curl
- Inspect DB: `docker exec -it nutshell_postgres psql ...`

---

## Troubleshooting

### PostgreSQL connection refused
```bash
docker-compose up -d postgres
# Wait 10 seconds for service health check
docker-compose ps  # Should show "healthy"
```

### OTP not being sent
- Check `.env`: `SMS_PROVIDER=mock` will log to console
- For real SMS: Configure Twilio credentials in `.env`

### Port 5432 already in use
```bash
# Change DATABASE_PORT in .env
docker-compose down  # Stop existing containers
docker-compose up -d  # Start fresh
```

### Clear database
```bash
docker-compose down -v  # Remove volumes
docker-compose up -d    # Fresh database
```

---

## Timeline

**Phase 1**: Complete (3-4 days)
- ✓ DB schema + TypeORM entities
- ✓ Authentication (OTP + JWT)
- ✓ Core API endpoints
- ✓ Docker setup

**Phase 2**: 2-3 days (next)
- 3D model validation + processing
- Cost calculation API

**Phase 3-7**: 11-14 days
- Frontend, engineer/manager dashboards, deployment

**Total MVP**: ~3-4 weeks with 1 developer + AI

---

## Support & Questions

See the comprehensive MVP plan at: `/memories/session/plan.md` (saved during analysis phase)

Key decisions documented in plan:
- Cost formula: `material_cost + machine_hours × rate + human_markup%`
- Supported formats: STEP, STP, IGES, IGS, STL, SAT (models); 7z, RAR (archives)
- Services (v1): 3D printing, milling, turning
- Multi-language: Russian + English (+ others configurable)