BeautyKit

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

★ 10 Open GitHub ↗

Full-stack beauty application with advanced ML-powered skin analysis, live avatar preview, hybrid face makeup simulation, celebrity-inspired looks, and comprehensive profile management.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ✦ BeauKit v2 — AI Skin Tone Beauty Intelligence

Full-stack beauty application with advanced ML-powered skin analysis, live avatar preview, hybrid face makeup simulation, celebrity-inspired looks, and comprehensive profile management.

![Version](https://img.shields.io/badge/version-2.0.0-c4a84a?style=for-the-badge)
![License](https://img.shields.io/badge/license-MIT-gold?style=for-the-badge)

---

## 🚀 Quick Setup (3 Steps)

### Step 1 — Install & Start Backend
```bash
cd backend
npm install
npm start
# ✅ Server runs on http://localhost:5000
```

### Step 2 — Install & Start Frontend (new terminal)
```bash
cd frontend
npm install
npm start
# ✅ App opens on http://localhost:3000
```

### Step 3 — Done! 
Open http://localhost:3000 in your browser

**Development Mode:**
```bash
# Backend (auto-restart with nodemon)
cd backend
npm run dev

# Frontend (hot reload)
cd frontend
npm start
```

---

## ✨ Key Features

### 🔐 Authentication System
- **JWT-based auth** with 7-day persistent sessions
- **Sign Up / Sign In** with bcrypt password hashing
- **Protected routes** with automatic token validation
- **Guest mode** for trying features without account

### 💾 Profile Management
- **Unlimited saved profiles** per account
- **Named profiles** (e.g., "Summer Look", "Wedding Day", "Mom")
- **Profile cards** with personalized avatar previews
- **Load & compare** different profiles instantly
- **Delete profiles** you no longer need

### 🎨 Advanced Skin Analysis
- **ML-powered pixel extraction** from uploaded/captured images
- **Undertone detection**: Warm, Cool, or Neutral
- **Depth classification**: Light to Deep (5 levels)
- **15 unique skin tone names** (e.g., "Golden Beige", "Porcelain Warm")
- **Real-time RGB to hex conversion**

### 💄 Comprehensive Beauty Recommendations
Seven personalized categories generated per analysis:

| Category | Details |
|----------|---------|
| **Jewelry** | 6 metals with ratings, 8+ styles, gemstone recommendations |
| **Clothing** | 16 colors per undertone, 8 styles, fabric & pattern guidance |
| **Lipstick** | 8 shades with finish type (Matte/Gloss/Velvet/Satin) |
| **Blush** | 6 shades with placement techniques |
| **Eyeshadow** | Custom 8-pan palette per undertone |
| **Hair Color** | 9 shades with styling & treatment suggestions |
| **Celebrity Looks** | Inspired matches from celebrity reference images |

### 🌟 Hybrid Avatar System
- **Real-time SVG avatar** that updates with every selection
- **Skin tone matching** from analysis results
- **Live makeup preview** on avatar face
- **Interactive color picking** - click any swatch to update avatar
- **Full customization**: hair, outfit, lipstick, blush, eyeshadow, jewelry

### 🎭 ML Face Makeup Simulation
- **Real-time face tracking** via webcam
- **Virtual makeup application** directly on user's live video feed
- **Multiple makeup styles** from natural to glam
- **Side-by-side comparison** with before/after views

### 📸 Image Capture Options
- **File upload** - drag-and-drop or click to upload any photo
- **Live camera capture** - real-time webcam with one-click photo
- **Celebrity reference** - analyze from celebrity inspiration photos
- **Pixel sampling algorithm** - extracts average skin tone from central 40% of image

### 🎨 Interactive Color Tools
- **Color Wheel** - explore full spectrum with precision picking
- **Color Picker** - fine-tune any shade with RGB/HEX controls
- **Celebrity Slider** - browse curated celebrity-inspired palettes
- **Skin Tone Panel** - visualize your exact undertone + depth match

---

## 📁 Project Structure

```
BeautyKit/
├── backend/
│   ├── index.js              # Express server + Auth + Analysis API
│   ├── package.json          # Backend dependencies
│   ├── vercel.json           # Vercel deployment config
│   └── README.md             # Detailed backend documentation
│
├── frontend/
│   ├── public/
│   │   └── index.html        # HTML shell + Google Fonts
│   ├── src/
│   │   ├── components/       # Reusable UI components
│   │   │   ├── Ambient.js    # Animated background orbs
│   │   │   ├── CelebritySlider.js    # Celebrity-inspired looks
│   │   │   ├── ColorPicker.js        # Fine-tune color selection
│   │   │   ├── ColorWheel.js         # Full spectrum color explorer
│   │   │   ├── HeroIllustration.js   # Landing page graphics
│   │   │   ├── HybridAvatar.js       # SVG avatar system
│   │   │   ├── MLFaceMakeup.js       # Real-time face makeup
│   │   │   ├── RealFaceMakeup.js     # Virtual makeup overlay
│   │   │   ├── SaveProfileModal.js   # Profile save dialog
│   │   │   └── SkinTonePanel.js      # Undertone visualization
│   │   ├── pages/            # Application screens
│   │   │   ├── LandingPage.js    # Marketing homepage
│   │   │   ├── AuthPage.js       # Sign in / Sign up
│   │   │   ├── DashboardPage.js  # Saved profiles grid
│   │   │   ├── ScanPage.js       # Image upload/capture
│   │   │   ├── AnalyzingPage.js  # Loading animation
│   │   │   └── ResultsPage.js    # Analysis results + avatar
│   │   ├── utils/            # Helper functions
│   │   │   ├── api.js            # API fetch wrapper + auth
│   │   │   ├── helpers.js        # Utility functions
│   │   │   └── imageProcessing.js# Pixel extraction algorithm
│   │   ├── data/
│   │   │   └── constants.js      # Shared constants
│   │   ├── App.js            # Main React component
│   │   ├── App.css           # Design system + styles
│   │   └── index.js          # React entry point
│   ├── package.json          # Frontend dependencies
│   └── README.md             # Frontend documentation
│
├── .gitignore
├── .gitmodules
├── LICENSE
└── README.md                 # You are here
```

---

## 🔬 Technology Stack

| Layer | Technology | Purpose |
|-------|-----------|----------|
| **Frontend Framework** | React 18.2 | Component-based UI |
| **Bundler** | Create React App (react-scripts 5.0.1) | Build tooling |
| **Language** | JavaScript ES2023+, JSX | Modern syntax |
| **Styling** | Vanilla CSS3 + Custom Properties | Design token system |
| **Fonts** | Cormorant Garamond + Outfit (Google Fonts) | Editorial typography |
| **Graphics** | Inline SVG (code-driven, no assets) | Avatar rendering |
| **Camera** | `navigator.mediaDevices.getUserMedia` | Live video capture |
| **Backend** | Node.js 18+ + Express 4.22 | REST API server |
| **Auth** | JWT (jsonwebtoken 9.0.2) + bcryptjs 2.4.3 | Secure authentication |
| **Database** | In-memory store (upgradeable to MongoDB/PostgreSQL) | Data persistence |
| **Analysis** | Canvas API + proprietary algorithm | Skin tone detection |
| **Utilities** | uuid 9.0.0, cors 2.8.5 | ID generation, CORS |
| **Dev Tools** | nodemon 3.0.1 | Auto-restart during development |

---

## 🛢 Database Upgrade Path

Replace the in-memory `db` object in `backend/index.js` with a real database:

### MongoDB (with Mongoose)
```bash
cd backend
npm install mongoose
```

```javascript
const mongoose = require('mongoose');
mongoose.connect('mongodb://localhost:27017/beaukit');

// Replace in-memory operations:
// db.users[email] = { ... }
await User.create({ id, name, email, passwordHash, profiles: [] });

// db.users[email]
const user = await User.findOne({ email });
```

### PostgreSQL (with Prisma)
```bash
cd backend
npm install prisma @prisma/client
npx prisma init
```

```javascript
const { PrismaClient } = require('@prisma/client');
const prisma = new PrismaClient();

// Replace in-memory operations:
await prisma.user.create({ data: { id, name, email, passwordHash } });
const user = await prisma.user.findUnique({ where: { email } });
```

---

## 📡 API Reference

### Base URL
```
http://localhost:5000
```

### Authentication Header
All protected routes require:
```
Authorization: Bearer <your_jwt_token>
```

---

### Public Endpoints (No Auth Required)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/health` | Health check - verify server running |
| `POST` | `/api/auth/signup` | Register new user account |
| `POST` | `/api/auth/signin` | Sign in and receive JWT token |
| `POST` | `/api/analyze-pixels` | Analyze skin RGB - get full recommendations |

---

### Protected Endpoints (Auth Required)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/auth/me` | Get current authenticated user info |
| `GET` | `/api/profiles` | List all saved beauty profiles |
| `POST` | `/api/profiles` | Save new beauty profile |
| `DELETE` | `/api/profiles/:id` | Delete a saved profile by UUID |

---

### Example Requests

**Health Check:**
```bash
curl http://localhost:5000/api/health
```

**Sign Up:**
```bash
curl -X POST http://localhost:5000/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","email":"jane@example.com","password":"secure123"}'
```

**Analyze Skin Tone:**
```bash
curl -X POST http://localhost:5000/api/analyze-pixels \
  -H "Content-Type: application/json" \
  -d '{"r":198,"g":158,"b":120}'
```

**Get Profiles (requires token):**
```bash
curl http://localhost:5000/api/profiles \
  -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE"
```

---

## 🌐 Environment Variables

### Backend
Create `backend/.env`:
```env
PORT=5000
JWT_SECRET=your-super-long-random-secret-here-at-least-256-bits
```

### Frontend
Create `frontend/.env`:
```env
REACT_APP_API_URL=http://localhost:5000
```

> ⚠️ **Important**: Never commit `.env` files to version control. Replace hardcoded secrets with environment variables in production.

---

BeautyKit

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README