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

   cd backend
   npm install
   

2. Configure environment (copy template)

   cp backend/.env.example backend/.env
   # Edit backend/.env if needed (defaults work for dev)
   

3. Start services (PostgreSQL + File Storage)

   docker-compose up -d
   

4. Start API server

   cd backend
   npm run dev
   

   Server runs at http://localhost:3001

5. Test health endpoint

   curl http://localhost:3001/api/health
   

---

API Documentation

Authentication Flow

1. Request OTP

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

Response:

{
  "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

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

Response:

{
  "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

curl -X GET http://localhost:3001/api/orders \
  -H "Authorization: Bearer <token_from_verify_otp>"

---

Database Management

Docker Commands

# 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

-- 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:

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

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

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

# Change DATABASE_PORT in .env
docker-compose down  # Stop existing containers
docker-compose up -d  # Start fresh

Clear database

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)