Unparty Logo

COLORS

the api for colors

theunpartycolors

Location: /Users/UNPARTYLLC/theunpartycolors/
Status: Active Development
Primary Purpose: Color palette management API and backend infrastructure for UNPARTY color generation platform

Overview

theunpartycolors is a RESTful API server that provides color palette management, user authentication, and administrative controls for the UNPARTY color generation ecosystem. It serves as the backend infrastructure for color-based creative tools, enabling users to create, store, and manage color palettes while finding similar and complementary colors through vector-based similarity search.

This repository represents the foundational API layer originally designed for the "Uncolor" app concept - a color generator that allows users to extract colors from photos, create custom palettes, and discover color relationships using machine learning.

Tech Stack

  • Framework: Express.js 4.21.0
  • Language: JavaScript (Node.js)
  • Database: MongoDB via Mongoose ODM
  • Authentication: Clerk (clerk-sdk-node 5.0.43)
  • Integration Services: Slack API (@slack/web-api, @slack/events-api)
  • Deployment: Vercel
  • Testing: Jest 29.7.0
  • Additional Tools:
    • express-basic-auth for API protection
    • CORS for cross-origin resource sharing
    • Joi for request validation
    • dotenv for environment configuration

Key Features

Core Functionality

  • Color Palette Management: Create, read, update, and delete color palettes with rich metadata
  • Color Schema Support: Full color representation including HEX, RGB, HSL, and LAB color spaces
  • User Management: Complete user lifecycle with Clerk integration
  • Project Organization: Users can organize colors into projects with clustering support
  • Color Associations: Track color relationships, usage frequency, and associations

Authentication & Authorization

  • Multi-layer Security: Basic authentication + Clerk JWT validation
  • Space Code System: Admin access control via time-limited space codes
  • CORS Protection: Allowlist-based origin control for web app integration

Integration Features

  • Slack Integration: Event handling and slash commands for team collaboration
  • Admin Panel Support: Space code generation and management routes
  • User Preferences: Theme settings and priority project tracking

Architecture

Code

API Server (Express.js)
├── Authentication Layer
│   ├── Basic Auth (All Routes)
│   ├── Clerk Auth (Protected User Routes)
│   └── Space Auth (Admin Routes)
├── Routes
│   ├── /api/basic (Public API)
│   ├── /api/auth (Login/Registration)
│   ├── /api/users (Protected User Operations)
│   ├── /admin (Space Code Management)
│   └── /api/slack (Slack Events & Commands)
├── Services
│   └── UserService (Business Logic)
├── Controllers
│   └── UserControllers (Request Handling)
├── Models (Mongoose Schemas)
│   ├── User (username, email, spaceName, projects, preferences)
│   ├── Color (hex, rgb, hsl, lab, associations, usageFrequency)
│   ├── ColorCluster (grouped colors by project)
│   ├── Project (name, description, colors)
│   └── SpaceCode (admin access codes)
└── Middleware
    ├── Basic Auth Middleware
    └── Space Auth Middleware

Data Models

User Schema

javascript

{
  username: String (3-30 chars, unique),
  email: String (unique, validated),
  spaceName: String (required),
  projects: [ObjectId] (ref: Project),
  preferences: {
    priorityProject: ObjectId (ref: Project),
    theme: String (enum: ['light', 'dark'])
  },
  timestamps: true
}

Color Schema

javascript

{
  hex: String (format: #RRGGBB),
  rgb: { r: Number (0-255), g: Number, b: Number },
  hsl: { h: Number (0-360), s: Number (0-100), l: Number (0-100) },
  lab: { l: Number, a: Number, b: Number },
  name: String (optional),
  associations: [String],
  usageFrequency: Number (default: 0),
  createdBy: ObjectId (ref: User)
}

Project Schema

javascript

{
  name: String (required),
  description: String (optional),
  colorCluster: ObjectId (ref: ColorCluster),
  colors: [ObjectId] (ref: Color),
  createdBy: ObjectId (ref: User),
  createdAt: Date,
  updatedAt: Date
}

ColorCluster Schema

javascript

{
  name: String (required),
  colors: [ObjectId] (ref: Color),
  project: ObjectId (ref: Project)
}

SpaceCode Schema

javascript

{
  code: String (unique admin access code),
  expiresAt: Date (optional expiration)
}

API Endpoints

Public Routes

  • GET / - API health check and welcome message
  • GET /api/basic - Basic public API routes

Authentication Routes

  • POST /api/auth/login - User login
  • POST /api/auth/register - User registration

Protected User Routes (Requires Basic Auth + Clerk)

  • GET /api/users - List users
  • POST /api/users - Create user
  • GET /api/users/:id - Get user details
  • PUT /api/users/:id - Update user
  • DELETE /api/users/:id - Delete user

Admin Routes (Requires Space Auth)

  • POST /admin/create-initial-space-code - Create first admin code
  • POST /admin/create-space-code - Generate new space code (protected)
  • GET /admin/test - Admin route health check

Slack Integration Routes

  • POST /api/slack/events - Slack event webhook
  • POST /api/slack/command - Slack slash command handler

Integration Points

External Services

  • Clerk Authentication: User identity and session management
  • MongoDB: Primary data storage for users, colors, projects
  • Slack API: Team collaboration and event notifications
  • Vercel: Deployment and hosting platform

Planned Integrations (from design docs)

  • Pinecone: Vector database for color similarity search (UP-PINE)
  • Redis: Caching layer for performance optimization (UP-CACHE)
  • Next.js Frontend: Web application interface (UP-FE-WEB)
  • iOS App: SwiftUI native application (UP-FE-IOS)

CORS Configuration

Allowed origins:

  • http://localhost:3000 (Development)
  • https://unparty.app (Production)
  • https://www.unparty.app (Production WWW)
  • https://founders.unparty.app (Founders Portal)

Development Setup

Prerequisites

  • Node.js 14+ (with npm or yarn)
  • MongoDB instance (local or cloud)
  • Clerk account and API keys
  • Slack workspace and bot tokens (for Slack features)

Environment Variables

Create a .env file in the root directory:

bash

# Server Configuration
PORT=3300

# Database
MONGO_URI=mongodb://localhost:27017/uncolor

# Authentication
CLERK_SECRET_KEY=your_clerk_secret_key

# Slack Integration
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your_signing_secret

Installation

bash

# Install dependencies
npm install

# Start development server with auto-reload
npm run dev

# Start production server
npm start

Testing

bash

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests only
npm run test:integration

# Run user-specific tests
npm run test:user

# Watch mode for development
npm run test:watch

Project Structure

Code

theunpartycolors/
├── authentication/           # Auth utilities and helpers
├── config/                   # Configuration files
├── controllers/              # Request handlers
│   └── user_controllers.js
├── documentation/            # Project documentation
│   └── uncolor_docs/
│       ├── uncolor_guide.mdx
│       ├── uncolor_product_brief.mdx
│       ├── uncolor_up_mongo_schema
│       ├── uncolor_user_model.mdx
│       └── uncolor_user_service.mdx
├── middleware/               # Express middleware
│   ├── basic_middleware.js   # Basic auth
│   └── space_middleware.js   # Admin space auth
├── models/                   # Mongoose schemas
│   ├── schema.js             # Color, Project, ColorCluster schemas
│   ├── space_code.js         # SpaceCode schema
│   └── user_model.js         # User schema
├── routes/                   # API route definitions
│   ├── admin_routes.js       # Admin operations
│   ├── auth_routes.js        # Authentication
│   ├── basic_routes.js       # Public routes
│   ├── slack_routes.js       # Slack integration
│   └── user_routes.js        # User operations
├── services/                 # Business logic layer
│   └── user_service.js
├── tests/                    # Test suites
│   ├── user/
│   │   ├── integration/
│   │   └── unit/
│   └── test.js
├── utils/                    # Utility functions
│   ├── generate/             # Code generators
│   └── validation/           # Input validation
├── index.js                  # Application entry point
├── package.json              # Dependencies and scripts
├── vercel.json              # Vercel deployment config
└── README.md                # This file

Business Value

ABOUT (Understanding & Discovery)

theunpartycolors helps users understand color relationships and discover new color combinations by:

  • Color Space Support: Multiple color representations (HEX, RGB, HSL, LAB) for comprehensive color understanding
  • Usage Tracking: Frequency and association data to understand color preferences
  • Project Organization: Clear structure to see how colors relate within projects
  • Search Foundation: Schema design supports future similarity search via Pinecone integration

BUILD (Creation & Tools)

Enables creators to build visual identities and color systems through:

  • Palette Creation: Store and organize color palettes for consistent branding
  • Project Management: Group colors by project for organized workflow
  • Color Extraction: Planned feature to extract colors from uploaded images (via UP-FE)
  • Complementary Suggestions: Foundation for ML-powered color recommendations
  • API-First Design: Flexible backend enables multiple frontend implementations (web, iOS, desktop)

CONNECT (Sharing & Collaboration)

Facilitates collaboration and community through:

  • Multi-platform Access: CORS configuration supports web and native apps
  • Slack Integration: Team notifications and commands for collaborative workflows
  • User Spaces: SpaceName system for organizing users and teams
  • Shared Projects: Project reference system supports future collaboration features
  • Export-Ready: Data models designed for easy sharing and export of color palettes

Relationship to UNPARTY Ecosystem

Direct Integration

  • theunpartyapp (Web Platform): Planned frontend consumer of this API
  • theunpartyunppp (Native App): Potential iOS client for color management
  • theunpartyrunway (Dev Tools): Cost tracking and development metrics for this service

Ecosystem Position

theunpartycolors serves as the color infrastructure layer of the UNPARTY ecosystem:

  • Provides color data management for other UNPARTY applications
  • Demonstrates the UNPARTY pattern of API-first, multi-platform design
  • Shares authentication infrastructure (Clerk) with other UNPARTY apps
  • Follows UNPARTY naming conventions (UP- prefixes in documentation)

Data Flow

Original Concept: UNCOLOR

From the product brief, theunpartycolors was originally designed as "UNCOLOR" - a color generator app with the following vision:

Problem Statement: Allowing users to explore colors and find complementary colors in real-time to build branding iteratively without feeling stuck.

Competitive Position:

  • Competitors: coolors.co ($5/mo), adobe.com (free), canva.com (free), huemint.com (free)
  • Unique Value: ML-powered color extraction, vector-based similarity search, project-based organization

Technical Innovation:

  • RAG (Retrieval Augmented Generation) approach to color similarity
  • MongoDB for metadata storage + Pinecone for vector relationships
  • Pre-seeded color complement database for intelligent suggestions

Future Pipeline: Font pairing recommendations based on color selection

Development Roadmap

Based on product documentation, the development follows this path:

Phase 1: Backend Foundation ✅ (Current)

  • MongoDB schemas and indexes (UP-MONGO)
  • Express.js API server (UP-API)
  • User authentication via Clerk (UP-AUTH)
  • Basic CRUD operations (UP-APP)
  • Admin space code system

Phase 2: Advanced Backend (Planned)

  • Pinecone vector indexing (UP-PINE)
  • Redis caching layer (UP-CACHE)
  • Color extraction algorithms
  • Similarity search implementation
  • Complementary color suggestions

Phase 3: Web Frontend (Planned)

  • Next.js application (UP-FE-WEB)
  • Color picker UI components
  • Image upload and color extraction
  • Palette management interface
  • User dashboard

Phase 4: Native iOS App (Planned)

  • SwiftUI application (UP-FE-IOS)
  • Apple Sign In integration
  • Core Image color extraction
  • Local storage with Core Data
  • Push notifications

Phase 5: Advanced Features (Future)

  • Font pairing recommendations
  • Team collaboration features
  • Export to design tools (Figma, Sketch)
  • Color trend analysis
  • Community palette sharing

Security & Privacy Considerations

Current Implementation

  • Multi-layer Authentication: Basic auth prevents unauthorized API access
  • Clerk Integration: Industry-standard user identity management
  • Space Code System: Time-limited admin access codes
  • CORS Protection: Origin allowlist prevents unauthorized domains
  • Input Validation: Joi schemas validate all user inputs
  • Mongoose Schema Validation: Database-level data integrity

Privacy

  • User email addresses stored with lowercase normalization
  • Passwords managed by Clerk (not stored in this database)
  • User preferences stored locally (theme, priority project)
  • No analytics or tracking implemented in current version

Cost Sensitivity

  • Vercel Deployment: Serverless functions minimize idle costs
  • MongoDB: Pay-per-use database reduces infrastructure overhead
  • Clerk Free Tier: 5,000 MAU included
  • Future Optimization: Planned Redis caching will reduce database costs

Testing Strategy

Current Test Coverage

  • Unit Tests: User service validation, user validation logic
  • Integration Tests: User model database operations
  • Test Framework: Jest with jest-mock-extended for mocking

Known Test Issues

Some tests are currently failing due to:

  • Missing validation module (user_validation.js)
  • User model constructor issues in test environment
  • These are pre-existing and unrelated to documentation changes

Testing Best Practices

bash

# Run tests before making changes
npm test

# Focus on changed areas
npm run test:user

# Use watch mode during development
npm run test:watch

Performance Considerations

Current Optimizations

  • Mongoose indexes on frequently queried fields (username, email)
  • Connection pooling via Mongoose
  • Express.json() body parsing limits

Planned Optimizations (from docs)

  • Redis Caching: Frequently accessed colors and palettes
  • CDN Integration: Static assets via Vercel Edge Network
  • Database Indexing: Compound indexes for color similarity queries
  • Pagination: Limit result sets for list operations
  • Batch Operations: Bulk color insertions

Deployment

Vercel Configuration

The vercel.json configuration file specifies:

  • Serverless function routing
  • Environment variable configuration
  • Build settings

Deployment Process

bash

# Automatic deployment via Vercel
git push origin main

# Manual deployment
vercel --prod

Environment Setup

Ensure all environment variables are configured in Vercel dashboard:

  • MONGO_URI
  • CLERK_SECRET_KEY
  • SLACK_BOT_TOKEN
  • SLACK_SIGNING_SECRET

Monitoring & Maintenance

Logging

  • Console.log for server startup and errors
  • MongoDB connection status monitoring
  • Request/response logging via Express middleware

Health Checks

  • GET / - Basic server health check
  • GET /admin/test - Admin routes health check
  • MongoDB connection status in startup logs

Maintenance Tasks

  • Monitor MongoDB connection pool
  • Review Clerk authentication logs
  • Update dependencies regularly
  • Review and rotate space codes
  • Monitor API usage and rate limits

Contributing

Code Style

  • JavaScript ES6+ features
  • Async/await for asynchronous operations
  • Clear variable and function naming
  • JSDoc comments for complex functions

Naming Conventions

Following UNPARTY ecosystem standards:

  • Routes: kebab-case (/api/user-colors)
  • Services: PascalCase + Service (ColorService)
  • Models: PascalCase (ColorModel)
  • Collections: camelCase plural (colorPalettes)
  • Variables: camelCase (userProfile)
  • Constants: UPPER_SNAKE_CASE (MAX_COLORS)

Git Workflow

  • Branches: feature/, bugfix/, hotfix/ prefixes
  • Commits: Imperative mood, lowercase (e.g., "add space code validation")
  • Pull Requests: Reference related issues and provide context

Documentation

Additional Resources

  • Product Brief: /documentation/uncolor_docs/uncolor_product_brief.mdx
  • User Model Guide: /documentation/uncolor_docs/uncolor_user_model.mdx
  • User Service Guide: /documentation/uncolor_docs/uncolor_user_service.mdx
  • Development Guide: /documentation/uncolor_docs/uncolor_guide.mdx
  • MongoDB Schema: /documentation/uncolor_docs/uncolor_up_mongo_schema

API Documentation

Currently using inline documentation. Future plans include:

  • OpenAPI/Swagger specification
  • Postman collection
  • Interactive API explorer

Known Issues & Limitations

Current Limitations

  • No pagination on list endpoints (can return large datasets)
  • Basic error messages (not user-friendly)
  • No rate limiting implemented
  • Slack integration requires additional setup
  • Color extraction not yet implemented (requires ML service)
  • Pinecone integration not yet implemented
  • No admin UI (space code management is API-only)

Future Improvements

  • Add comprehensive error handling
  • Implement request validation middleware
  • Add API rate limiting
  • Create admin dashboard
  • Implement color similarity search
  • Add bulk operations for colors
  • Create API documentation portal
  • Add performance monitoring

Support & Contact

License

[License information to be added]

Quick Start

bash

# Clone the repository
git clone https://github.com/unparty-app/theunpartycolors.git
cd theunpartycolors

# Install dependencies
npm install

# Configure environment
# Create .env file with your credentials (see Environment Variables section above)

# Start development server
npm run dev

# Server runs on http://localhost:3300

Status: 🚧 Active Development
Version: 1.0.0
Last Updated: 2024-10-30
Maintained By: UNPARTY Development Team

Focus: Building color infrastructure for creators - enabling exploration, creation, and sharing of color palettes while protecting user privacy and maintaining cost efficiency.