{"id":31658220,"url":"https://github.com/nickcrisci/palpalette-2","last_synced_at":"2026-04-11T10:37:02.120Z","repository":{"id":310648389,"uuid":"1034263167","full_name":"nickcrisci/PalPalette-2","owner":"nickcrisci","description":"🎨 Share ambient colors in real-time across IoT LED devices. Connect spaces and people through synchronized lighting experiences with mobile control and smart device integration.","archived":false,"fork":false,"pushed_at":"2025-08-26T11:56:49.000Z","size":1163,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-26T15:33:47.710Z","etag":null,"topics":["ambient-lighting","color-sharing","docker","embedded-systems","esp32","ionic","iot","nestjs","smart-lighting","typescript","websockets"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nickcrisci.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-08T05:42:46.000Z","updated_at":"2025-08-26T11:56:51.000Z","dependencies_parsed_at":"2025-08-19T12:41:23.742Z","dependency_job_id":"75e39829-0aca-49d3-86f3-5267772a868b","html_url":"https://github.com/nickcrisci/PalPalette-2","commit_stats":null,"previous_names":["nickcrisci/palpalette-2"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nickcrisci/PalPalette-2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickcrisci%2FPalPalette-2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickcrisci%2FPalPalette-2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickcrisci%2FPalPalette-2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickcrisci%2FPalPalette-2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nickcrisci","download_url":"https://codeload.github.com/nickcrisci/PalPalette-2/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickcrisci%2FPalPalette-2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278795659,"owners_count":26047253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ambient-lighting","color-sharing","docker","embedded-systems","esp32","ionic","iot","nestjs","smart-lighting","typescript","websockets"],"created_at":"2025-10-07T15:15:33.806Z","updated_at":"2025-10-07T15:15:35.040Z","avatar_url":"https://github.com/nickcrisci.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PalPalette - IoT Color Sharing Platform\n\nThe original idea of this was to create a system that lets remote friends easily share moments with each other. The first version of this was created in the context of a university module. As there were deadlines to fullfill, our techstack was not optimal and the structure lacked... structure.\n\nThis second version seen here is the attempt to bring more structure and a better techstack to this project. But again, there were deadlines to fullfill (this time for a study using this system) and the second version had to be created rather quickly. Because of this it was decided to try to create the new system using AI support.\n\nAs many of you probably know, this can be rather chaotic at times. While some parts of this system are already working well, others are still chaotic and do not work as intended. In the near future human devs should take control back from the AI in this project, hopefully fixing what the AI could'nt.\n\nAs I'm neither an expert in C++, nor in NestJS, the AI created the code only with my supervision. I plan on learning these techs in the near future, to be able to further develop this on my own.\n\nIn the meantime, I invite everyone who has a better understanding of these technologies to refactor and expand this project :).\n\n_The following readme was also created by the AI_\n\n\u003e **A revolutionary IoT ecosystem that bridges the digital and physical worlds through color**\n\nPalPalette transforms how we share and experience colors by connecting mobile devices, cloud services, and physical LED displays. Extract colors from your world, share them with friends, and watch them come alive on beautiful LED installations in real-time.\n\n## 🎯 Project Vision\n\nIn an increasingly digital world, PalPalette creates tangible connections through the universal language of color. Whether you want to share the sunset from your vacation, the cozy ambiance of your coffee shop, or simply brighten a friend's day with their favorite colors, PalPalette makes it possible with just a photo and a tap.\n\n## ✨ What Makes PalPalette Special\n\n- **🌈 Instant Color Magic**: Point, capture, extract, and share color palettes in seconds\n- **🤝 Social Color Sharing**: Send colors to friends like sending messages\n- **💡 Physical Manifestation**: Watch digital colors transform into beautiful LED displays\n- **🔧 Zero-Configuration Setup**: ESP32 devices that set themselves up automatically\n- **🌐 Real-Time Synchronization**: WebSocket-powered instant color delivery\n- **📱 Cross-Platform Mobile**: Works on iOS and Android with native performance\n\n## 🏗️ System Architecture\n\n### High-Level Overview\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   Mobile App    │◄──►│   Backend API    │◄──►│  ESP32 Device   │\n│ (Ionic/React)   │    │ (NestJS + WS)    │    │   (Arduino)     │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n       │                        │                        │\n       │                        │                        │\n   ┌───▼────┐              ┌────▼────┐              ┌────▼────┐\n   │ Camera │              │Database │              │ WS2812B │\n   │ Color  │              │(Postgres│              │   LED   │\n   │Extract │              │ + JWT)  │              │ Display │\n   └────────┘              └─────────┘              └─────────┘\n```\n\n### Detailed Component Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                        PalPalette System                        │\n├─────────────────────────────────────────────────────────────────┤\n│                          Frontend Layer                         │\n│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │\n│  │   iOS App       │  │   Android App   │  │   Web Portal    │ │\n│  │ (Ionic/Capacitor│  │ (Ionic/Capacitor│  │   (React)       │ │\n│  │  + TypeScript)  │  │  + TypeScript)  │  │                 │ │\n│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │\n├─────────────────────────────────────────────────────────────────┤\n│                        API Gateway Layer                        │\n│  ┌─────────────────────────────────────────────────────────────┐ │\n│  │              NestJS Backend API Server                     │ │\n│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐         │ │\n│  │  │  Auth   │ │ Devices │ │Messages │ │  Users  │         │ │\n│  │  │ Module  │ │ Module  │ │ Module  │ │ Module  │         │ │\n│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘         │ │\n│  └─────────────────────────────────────────────────────────────┘ │\n├─────────────────────────────────────────────────────────────────┤\n│                       Communication Layer                       │\n│  ┌─────────────────┐              ┌─────────────────┐           │\n│  │   REST APIs     │              │   WebSocket     │           │\n│  │ (HTTP/HTTPS)    │              │   (Real-time)   │           │\n│  │                 │              │                 │           │\n│  │ • Authentication│              │ • Device Comms  │           │\n│  │ • User Management│              │ • Color Sharing │           │\n│  │ • Device Setup  │              │ • Live Updates  │           │\n│  └─────────────────┘              └─────────────────┘           │\n├─────────────────────────────────────────────────────────────────┤\n│                         Data Layer                              │\n│  ┌─────────────────────────────────────────────────────────────┐ │\n│  │                PostgreSQL Database                          │ │\n│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │ │\n│  │  │  Users  │ │ Devices │ │Messages │ │Palettes │           │ │\n│  │  │  Table  │ │  Table  │ │  Table  │ │  Table  │           │ │\n│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │ │\n│  └─────────────────────────────────────────────────────────────┘ │\n├─────────────────────────────────────────────────────────────────┤\n│                         IoT Layer                               │\n│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │\n│  │   ESP32 MCU     │  │   ESP32 MCU     │  │   ESP32 MCU     │ │\n│  │                 │  │                 │  │                 │ │\n│  │ ┌─────────────┐ │  │ ┌─────────────┐ │  │ ┌─────────────┐ │ │\n│  │ │WiFi Manager │ │  │ │WiFi Manager │ │  │ │WiFi Manager │ │ │\n│  │ │Device Setup │ │  │ │Device Setup │ │  │ │Device Setup │ │ │\n│  │ │WS Client    │ │  │ │WS Client    │ │  │ │WS Client    │ │ │\n│  │ │LED Control  │ │  │ │LED Control  │ │  │ │LED Control  │ │ │\n│  │ └─────────────┘ │  │ └─────────────┘ │  │ └─────────────┘ │ │\n│  │                 │  │                 │  │                 │ │\n│  │ ┌─────────────┐ │  │ ┌─────────────┐ │  │ ┌─────────────┐ │ │\n│  │ │  WS2812B    │ │  │ │  WS2812B    │ │  │ │  WS2812B    │ │ │\n│  │ │ LED Strip   │ │  │ │ LED Strip   │ │  │ │ LED Strip   │ │ │\n│  │ └─────────────┘ │  │ └─────────────┘ │  │ └─────────────┘ │ │\n│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n## 🚀 Quick Deployment\n\n## 🚀 Quick Deployment\n\nGet PalPalette running in production with these simple steps:\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/PalPalette-2.git\ncd PalPalette-2\n\n# Configure environment\ncp .env.production.example .env.production\nnano .env.production  # Set your DB_PASSWORD and JWT_SECRET\n\n# Deploy with Docker\nsudo docker-compose -f docker-compose.production.yml --env-file .env.production up -d --build\n```\n\n🔗 **Complete deployment guide**: [DEPLOYMENT.md](DEPLOYMENT.md)\n\n## 🎯 Core Features\n\n### 📱 **Mobile Experience**\n\n- **🎨 Smart Color Extraction**: Advanced algorithms extract dominant colors from any photo\n- **👥 Social Color Networks**: Build friendships through shared color experiences\n- **🔧 Guided Device Setup**: Intuitive wizard walks users through ESP32 pairing\n- **💬 Real-Time Color Chat**: Send colors like messages with instant delivery\n- **📊 Color History**: Track and replay favorite color combinations\n- **🎭 Palette Collections**: Organize colors into themed collections\n\n### 🔌 **ESP32 IoT Devices**\n\n- **🌐 Auto-Configuration**: Zero-touch setup with captive WiFi portal\n- **🔐 Secure Self-Registration**: Automatic device authentication with pairing codes\n- **⚡ Real-Time WebSocket**: Ultra-low latency color synchronization\n- **💾 Persistent Memory**: Device state preserved across power cycles\n- **🎨 Advanced LED Control**: Support for WS2812B strips with smooth transitions\n- **📡 Robust Connectivity**: Automatic reconnection and error recovery\n\n### 🖥️ **Backend Infrastructure**\n\n- **🔒 Enterprise Security**: JWT-based authentication with refresh tokens\n- **📊 Scalable Architecture**: Microservice-ready NestJS modules\n- **🔌 Dual Communication**: REST APIs + WebSocket for optimal performance\n- **👫 Social Features**: Friend networks, requests, and color sharing permissions\n- **📂 Complete API**: RESTful endpoints for all system operations\n- **🗄️ Robust Database**: PostgreSQL with comprehensive migrations\n\n## 🎭 User Journey Examples\n\n### **The Sunset Sharer**\n\n_\"I captured the most beautiful sunset on my hike. Now my friend Emma can enjoy those exact colors on her bedroom LED strip while she relaxes after work.\"_\n\n1. 📸 Capture sunset photo with mobile app\n2. 🎨 App extracts warm orange, pink, and purple tones\n3. 👫 Select Emma from friends list\n4. 💡 Choose Emma's bedroom LED device\n5. ⚡ Colors instantly appear on Emma's LED strip\n6. 💬 Emma receives notification with original photo\n\n### **The Cozy Coffee Experience**\n\n_\"The lighting in this café is perfect for reading. I'll share this ambiance with my study group's shared workspace.\"_\n\n1. 📱 Extract warm amber and soft white tones from café photo\n2. 🎯 Send to \"Study Room\" device owned by study group\n3. 🏠 Entire room transforms to match café ambiance\n4. 📚 Group enjoys enhanced focus atmosphere\n\n### **The Long-Distance Love**\n\n_\"Even though we're in different cities, we can share the same colors and feel connected.\"_\n\n1. 💕 Daily color sharing ritual between partners\n2. 🌅 Morning person shares sunrise colors\n3. 🌙 Evening person shares twilight hues\n4. 💞 Both experience shared color moments simultaneously\n\n## 🏗️ Technical Architecture Deep Dive\n\n### **Data Flow Architecture**\n\n```mermaid\ngraph TD\n    A[Mobile App] --\u003e|HTTP REST| B[NestJS API Gateway]\n    A --\u003e|Photo Capture| C[Color Extraction Engine]\n    C --\u003e|Hex Colors| A\n\n    B --\u003e|Query/Store| D[PostgreSQL Database]\n    B \u003c--\u003e|WebSocket| E[ESP32 Device Pool]\n\n    E --\u003e|WiFi Setup| F[Captive Portal]\n    E --\u003e|LED Control| G[WS2812B LEDs]\n    E --\u003e|Status Updates| B\n\n    D --\u003e|User Auth| H[JWT Service]\n    D --\u003e|Device Registry| I[Device Manager]\n    D --\u003e|Social Graph| J[Friends System]\n```\n\n### **Security Architecture**\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                     Security Layers                         │\n├─────────────────────────────────────────────────────────────┤\n│ Application Layer                                           │\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │\n│  │   JWT Auth  │  │  Input Val  │  │  Rate Limit │        │\n│  │  \u0026 Refresh  │  │ \u0026 Sanitiz.  │  │ \u0026 Throttle  │        │\n│  └─────────────┘  └─────────────┘  └─────────────┘        │\n├─────────────────────────────────────────────────────────────┤\n│ Transport Layer                                             │\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │\n│  │   HTTPS/    │  │   Secure    │  │   Device    │        │\n│  │   WSS TLS   │  │  WebSocket  │  │ Pairing Codes│        │\n│  └─────────────┘  └─────────────┘  └─────────────┘        │\n├─────────────────────────────────────────────────────────────┤\n│ Infrastructure Layer                                        │\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │\n│  │  Database   │  │   Docker    │  │   Network   │        │\n│  │ Encryption  │  │  Container  │  │  Isolation  │        │\n│  │ \u0026 Hashing   │  │  Security   │  │ \u0026 Firewall  │        │\n│  └─────────────┘  └─────────────┘  └─────────────┘        │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## 📁 Project Structure\n\n```\nPalPalette-2/\n├── 📱 palpalette-app/              # Cross-Platform Mobile Application\n│   ├── src/\n│   │   ├── components/             # Reusable UI components\n│   │   │   ├── ColorExtractor/     # Camera \u0026 color analysis\n│   │   │   ├── DeviceSetup/        # ESP32 pairing wizard\n│   │   │   ├── SocialFeatures/     # Friends \u0026 sharing\n│   │   │   └── LEDControls/        # Device management\n│   │   ├── contexts/               # React contexts\n│   │   │   ├── AuthContext.tsx     # User authentication\n│   │   │   ├── DeviceContext.tsx   # ESP32 device management\n│   │   │   └── WebSocketContext.tsx# Real-time communication\n│   │   ├── pages/                  # Main application screens\n│   │   │   ├── Dashboard/          # Color palette overview\n│   │   │   ├── Camera/             # Photo capture \u0026 extraction\n│   │   │   ├── Friends/            # Social network management\n│   │   │   └── Devices/            # ESP32 device management\n│   │   ├── services/               # API \u0026 WebSocket services\n│   │   │   ├── api.service.ts      # REST API client\n│   │   │   ├── websocket.service.ts# Real-time communication\n│   │   │   └── color.service.ts    # Color analysis algorithms\n│   │   ├── hooks/                  # Custom React hooks\n│   │   └── config/                 # Configuration \u0026 constants\n│   ├── android/                    # Android platform files\n│   ├── ios/                        # iOS platform files (future)\n│   └── docs/                       # Mobile development guides\n│\n├── 🖥️  backend/                    # Enterprise NestJS API Server\n│   ├── src/\n│   │   ├── modules/                # Domain-driven feature modules\n│   │   │   ├── auth/               # JWT authentication system\n│   │   │   │   ├── guards/         # Route protection\n│   │   │   │   ├── strategies/     # Passport strategies\n│   │   │   │   └── decorators/     # Custom auth decorators\n│   │   │   ├── devices/            # ESP32 device lifecycle\n│   │   │   │   ├── dto/            # Data transfer objects\n│   │   │   │   ├── entities/       # Database entities\n│   │   │   │   └── services/       # Business logic\n│   │   │   ├── messages/           # Color sharing \u0026 WebSocket\n│   │   │   │   ├── gateways/       # WebSocket gateways\n│   │   │   │   ├── handlers/       # Message processors\n│   │   │   │   └── queues/         # Message queuing\n│   │   │   └── users/              # User management \u0026 social\n│   │   │       ├── friends/        # Friendship system\n│   │   │       ├── palettes/       # Color palette storage\n│   │   │       └── profiles/       # User profile management\n│   │   ├── migrations/             # Database schema evolution\n│   │   ├── common/                 # Shared utilities \u0026 decorators\n│   │   └── config/                 # Environment configuration\n│   ├── test/                       # Comprehensive test suites\n│   └── docs/                       # API documentation \u0026 guides\n│\n├── 🔧 controller/                  # ESP32 Arduino Firmware\n│   ├── src/                        # Modular firmware architecture\n│   │   ├── main.ino               # Main application loop\n│   │   ├── config.h               # Hardware \u0026 network configuration\n│   │   ├── core/                  # Core system modules\n│   │   │   ├── DeviceManager.cpp  # Device lifecycle \u0026 registration\n│   │   │   ├── WiFiManager.cpp    # Network connectivity \u0026 portal\n│   │   │   ├── WebSocketClient.cpp# Real-time communication\n│   │   │   └── SystemUtils.cpp    # Utilities \u0026 diagnostics\n│   │   ├── lighting/              # LED control subsystem\n│   │   │   ├── LEDController.cpp  # WS2812B strip management\n│   │   │   ├── ColorAnimations.cpp# Smooth color transitions\n│   │   │   └── EffectEngine.cpp   # Advanced visual effects\n│   │   └── network/               # Network protocols\n│   │       ├── CaptivePortal.cpp  # WiFi setup web interface\n│   │       ├── HTTPClient.cpp     # REST API communication\n│   │       └── OTAUpdater.cpp     # Over-the-air firmware updates\n│   ├── platformio.ini             # PlatformIO configuration\n│   ├── examples/                  # Usage examples \u0026 tutorials\n│   └── docs/                      # Firmware development guides\n│\n├── 🐳 deployment/                  # Production deployment\n│   ├── docker-compose.production.yml # Production container orchestration\n│   ├── nginx/                     # Reverse proxy configuration\n│   ├── ssl/                       # SSL certificate management\n│   └── monitoring/                # System monitoring \u0026 logging\n│\n└── 📚 docs/                       # Comprehensive documentation\n    ├── ARCHITECTURE.md            # System design \u0026 patterns\n    ├── DEPLOYMENT.md              # Production deployment guide\n    ├── API.md                     # Complete API reference\n    ├── DEVELOPMENT.md             # Local development setup\n    ├── HARDWARE.md                # ESP32 \u0026 LED setup guide\n    └── TROUBLESHOOTING.md         # Common issues \u0026 solutions\n```\n\n## 🔧 Development Setup\n\n### Prerequisites\n\n- **Node.js 18+** - JavaScript runtime\n- **Docker \u0026 Docker Compose** - Containerization\n- **Arduino IDE or PlatformIO** - ESP32 development\n- **ESP32 Development Board** - Target hardware\n- **WS2812B LED Strip** - Light display (optional)\n\n### 1. Backend Development\n\n```bash\n# Start backend services\ncd backend\nnpm install\ndocker-compose up -d          # PostgreSQL database\nnpm run migration:run         # Database schema\nnpm run seed:run             # Sample data\nnpm run start:dev            # Development server with hot reload\n\n# Access points:\n# API: http://localhost:3000\n# WebSocket: ws://localhost:3001\n# Database: localhost:5432\n```\n\n### 2. Mobile App Development\n\n```bash\n# Start mobile development\ncd palpalette-app\nnpm install\nnpx ionic serve              # Web browser development\n\n# Platform-specific builds:\nnpx ionic cap run android    # Android device/emulator\nnpx ionic cap run ios        # iOS device/simulator (macOS only)\n\n# Access: http://localhost:8100\n```\n\n### 3. ESP32 Firmware Development\n\n```bash\n# Prepare ESP32 development environment\ncd controller\n\n# Using Arduino IDE:\n# 1. Install ESP32 board package\n# 2. Install libraries: ArduinoJson, WiFi, WebSockets, Preferences\n# 3. Open src/main.ino and upload\n\n# Using PlatformIO:\npio run                      # Build firmware\npio upload                   # Flash to ESP32\npio device monitor           # Serial monitor for debugging\n```\n\n## 🌟 Key System Workflows\n\n### **🔧 Device Setup \u0026 Pairing Flow**\n\n```\n1. 📦 ESP32 powers on → Creates \"PalPalette-Setup\" WiFi hotspot\n2. 📱 User connects phone → Opens captive portal at 192.168.4.1\n3. 🌐 User enters home WiFi credentials → ESP32 connects to internet\n4. 🔐 ESP32 auto-registers with backend → Generates unique pairing code\n5. 📱 User opens mobile app → Enters pairing code to claim device\n6. ✅ ESP32 receives claim notification → Device becomes operational\n7. 🎨 Device ready to receive and display colors\n```\n\n### **🎨 Color Capture \u0026 Sharing Flow**\n\n```\n1. 📸 User captures photo with mobile app camera\n2. 🧠 Advanced color extraction algorithm analyzes image\n3. 🎭 App presents dominant color palette (3-8 colors)\n4. 👥 User selects friends and target ESP32 devices\n5. ⚡ Backend delivers colors via WebSocket to ESP32s\n6. 💡 ESP32 displays colors on LED strip with smooth transitions\n7. 📱 Recipients receive notification with original photo\n8. 🔄 Colors can be replayed, modified, or acknowledged\n```\n\n### **👫 Social Network \u0026 Friends Flow**\n\n```\n1. 🔍 User searches for friends by username or email\n2. 📤 Sends friend request through mobile app\n3. 📬 Recipient receives in-app notification\n4. ✅ Recipient accepts/declines friend request\n5. 🤝 Friends can now share colors and see each other's devices\n6. 🎨 Color sharing permissions managed per friendship\n7. 📊 Shared color history tracked and accessible\n```\n\n## 📖 Documentation \u0026 Resources\n\n### 📋 **System Documentation**\n\n- [🏗️ **System Architecture**](docs/ARCHITECTURE.md) - Detailed technical architecture\n- [🚀 **Deployment Guide**](docs/DEPLOYMENT.md) - Production deployment instructions\n- [📡 **API Documentation**](docs/API.md) - Complete REST API reference\n- [💻 **Development Setup**](docs/DEVELOPMENT.md) - Local development environment\n- [🔧 **Hardware Guide**](docs/HARDWARE.md) - ESP32 setup and LED configuration\n- [🐛 **Troubleshooting**](docs/TROUBLESHOOTING.md) - Common issues and solutions\n\n### 🧩 **Component Documentation**\n\n- [📱 **Mobile App Guide**](palpalette-app/docs/README.md) - Ionic development \u0026 deployment\n- [🖥️ **Backend API Guide**](backend/docs/README.md) - NestJS architecture \u0026 patterns\n- [🔧 **ESP32 Firmware Guide**](controller/docs/README.md) - Arduino firmware development\n\n## 🛠️ Technology Stack\n\n### **Frontend Technologies**\n\n- **🚀 Ionic Framework** - Cross-platform mobile development\n- **⚛️ React** - Component-based UI framework\n- **📱 Capacitor** - Native mobile platform integration\n- **🎨 TypeScript** - Type-safe JavaScript development\n- **📷 Camera API** - Native camera access for color capture\n- **🎭 Color Analysis** - Advanced color extraction algorithms\n\n### **Backend Technologies**\n\n- **🏗️ NestJS** - Enterprise Node.js framework with dependency injection\n- **🔌 WebSockets** - Real-time bidirectional communication\n- **🗄️ PostgreSQL** - Relational database with JSON support\n- **🔐 JWT Authentication** - Stateless security tokens\n- **📊 TypeORM** - Object-relational mapping with migrations\n- **🐳 Docker** - Containerized deployment and development\n\n### **IoT \u0026 Hardware**\n\n- **🔧 ESP32** - WiFi-enabled microcontroller with dual-core processing\n- **💡 WS2812B LEDs** - Individually addressable RGB LED strips\n- **⚡ Arduino Framework** - Embedded C++ development environment\n- **🌐 Captive Portal** - Auto-setup WiFi configuration interface\n- **💾 EEPROM Storage** - Persistent device configuration storage\n\n### **DevOps \u0026 Infrastructure**\n\n- **🐳 Docker Compose** - Multi-container application orchestration\n- **🔒 Environment Management** - Secure configuration with .env files\n- **📦 Git Version Control** - Source code management and collaboration\n- **🌐 RESTful APIs** - Stateless HTTP service architecture\n- **⚡ WebSocket Protocol** - Low-latency real-time communication\n\n## 🚀 Getting Started\n\n### **For Users**\n\n1. **📱 Download the mobile app** (coming to app stores)\n2. **🛒 Get an ESP32 device** and LED strip\n3. **⚡ Flash the firmware** to your ESP32\n4. **🔧 Follow the setup wizard** in the mobile app\n5. **🎨 Start sharing colors** with friends!\n\n### **For Developers**\n\n1. **📥 Clone this repository**\n2. **📚 Read the development documentation**\n3. **🔧 Set up the development environment**\n4. **🧪 Run the test suites**\n5. **💡 Start building amazing features!**\n\n### **For Makers \u0026 Hardware Enthusiasts**\n\n1. **📋 Check the hardware requirements**\n2. **🔌 Wire up your ESP32 and LED strip**\n3. **⚡ Flash the firmware**\n4. **🎨 Create beautiful LED installations**\n5. **🤝 Share your builds with the community!**\n\n## 🤝 Contributing\n\nWe welcome contributions from developers, designers, makers, and color enthusiasts! Here's how you can help:\n\n### **🐛 Bug Reports \u0026 Feature Requests**\n\n- Use GitHub Issues for bug reports\n- Provide detailed reproduction steps\n- Include hardware/software versions\n- Suggest new features and improvements\n\n### **💻 Code Contributions**\n\n1. **🍴 Fork the repository**\n2. **🌿 Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **✅ Write tests** for your changes\n4. **📝 Update documentation** if needed\n5. **🚀 Submit a Pull Request** with detailed description\n\n### **📖 Documentation**\n\n- Improve existing documentation\n- Add tutorials and examples\n- Translate documentation\n- Create video guides\n\n### **🔧 Hardware \u0026 Firmware**\n\n- Test on different ESP32 variants\n- Add support for new LED types\n- Optimize power consumption\n- Create new visual effects\n\n## 🎯 Future Roadmap\n\n### **🔜 Coming Soon**\n\n- **🍎 iOS App** - Native iOS application\n- **🌐 Web Dashboard** - Browser-based device management\n- **🎵 Music Sync** - Color visualization synchronized with audio\n- **🤖 AI Color Suggestions** - Intelligent palette recommendations\n- **📱 Widget Support** - Home screen color widgets\n\n### **🔮 Future Vision**\n\n- **🏠 Smart Home Integration** - Philips Hue, LIFX compatibility\n- **🎮 Gaming Integration** - Color effects for gaming events\n- **📺 Screen Mirroring** - Display computer/TV colors on LEDs\n- **🌍 Global Color Events** - Worldwide synchronized color displays\n- **🎨 AR/VR Integration** - Virtual color palette interactions\n\n## ⚠️ Development Disclaimer\n\n**This project was built with AI assistance** using GitHub Copilot and other AI tools, building upon an original human-created foundation. While the core concepts, architecture decisions, and user experience design reflect human creativity and expertise, significant portions of the implementation were enhanced and accelerated through AI collaboration.\n\n### **🤖 AI-Assisted Development**\n\n- **Code Generation**: Many code components were generated or enhanced by AI\n- **Documentation**: Large portions of documentation were created with AI assistance\n- **Architecture Refinement**: AI helped optimize and expand the original architecture\n- **Testing \u0026 Debugging**: AI assisted in creating comprehensive test suites\n\n### **👨‍💻 Human Foundation**\n\n- **Original Concept**: The core idea and user experience were human-designed\n- **System Architecture**: Base architecture and technology choices were human-driven\n- **Creative Vision**: The product vision and user stories are human-created\n- **Final Validation**: All AI-generated code was reviewed and validated by humans\n\nThis hybrid approach demonstrates the powerful collaboration possible between human creativity and AI capabilities, resulting in a more robust and feature-complete system than either could achieve alone.\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n### **� Open Source Philosophy**\n\n- ✅ **Free to use** for personal and commercial projects\n- ✅ **Modify and distribute** with attribution\n- ✅ **Learn and experiment** with the codebase\n- ✅ **Build upon** for your own projects\n\n## �🙏 Acknowledgments \u0026 Credits\n\n### **🛠️ Technology \u0026 Framework Credits**\n\n- **⚛️ React \u0026 Ionic Teams** - For exceptional cross-platform mobile frameworks\n- **🏗️ NestJS Community** - For the robust, enterprise-ready backend framework\n- **🔧 Espressif Systems** - For the powerful and affordable ESP32 platform\n- **💡 FastLED Community** - For advanced LED control libraries and effects\n\n### **🤝 Development \u0026 Community**\n\n- **🤖 OpenAI \u0026 GitHub Copilot** - For AI development assistance and code generation\n- **👥 Open Source Community** - For countless libraries and tools that made this possible\n- **🎨 Color Theory Researchers** - For algorithms and insights into color perception\n- **💻 Stack Overflow Contributors** - For solutions to countless development challenges\n\n### **🎨 Design \u0026 Inspiration**\n\n- **🌈 Color Enthusiasts** - For inspiring the core concept of color sharing\n- **🏠 Smart Home Community** - For pioneering IoT integration patterns\n- **📱 UX/UI Designers** - For mobile app design patterns and best practices\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**🌈 Made with ❤️ for the IoT and Color Community 🌈**\n\n_Bringing digital colors to life, one LED at a time_\n\n[![⭐ Star this repo](https://img.shields.io/github/stars/nickcrisci/PalPalette-2?style=social)](https://github.com/nickcrisci/PalPalette-2/stargazers)\n[![🍴 Fork this repo](https://img.shields.io/github/forks/nickcrisci/PalPalette-2?style=social)](https://github.com/nickcrisci/PalPalette-2/network/members)\n[![📢 Share on Twitter](https://img.shields.io/twitter/url?style=social\u0026url=https%3A%2F%2Fgithub.com%nickcrisci%2FPalPalette-2)](https://twitter.com/intent/tweet?text=Check%20out%20PalPalette%20-%20IoT%20Color%20Sharing%20Platform!\u0026url=https://github.com/nickcrisci/PalPalette-2)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickcrisci%2Fpalpalette-2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnickcrisci%2Fpalpalette-2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickcrisci%2Fpalpalette-2/lists"}