Collaborative-pixel-art/README.md

🎨 GaPlace - Modern Collaborative Pixel Art Platform

GaPlace is a high-performance, real-time collaborative pixel art platform built with modern web technologies. Create pixel art together with thousands of users on an infinite canvas with advanced features like real-time cursors, chunked loading, and optimized rendering.

✨ Features

🚀 Performance

• Virtual Canvas: Only renders visible pixels for massive performance gains
• Chunked Loading: Loads canvas data in 64x64 pixel chunks on-demand
• WebGL Acceleration: Hardware-accelerated rendering for smooth interactions
• Infinite Canvas: Support for canvases up to 10,000 x 10,000 pixels
• 60 FPS: Smooth animations and interactions

🤝 Real-time Collaboration

• Live Cursors: See other users' cursors in real-time
• User Presence: Know who's online and active
• Instant Updates: See pixel changes as they happen
• Rate Limiting: Smart rate limiting to prevent spam

🎨 Advanced Drawing Tools

• Pixel Tool: Classic pixel-by-pixel drawing
• Fill Tool: Flood fill for large areas
• Eyedropper: Pick colors from existing pixels
• Color Palette: 21 predefined colors + custom color picker
• Zoom & Pan: Smooth navigation with mouse and keyboard

🌙 Modern UI/UX

• Dark Mode: System preference detection + manual toggle
• Responsive Design: Works on desktop, tablet, and mobile
• Accessibility: Screen reader support and keyboard navigation
• Smooth Animations: Framer Motion powered interactions

🔒 Enterprise Ready

• TypeScript: Full type safety across the stack
• Redis: High-performance data storage and caching
• PostgreSQL: Reliable user and canvas metadata storage
• Docker: Containerized deployment
• Health Checks: Comprehensive monitoring and alerting

🏗️ Architecture

Backend Stack

• Node.js 18+ with TypeScript
• Express.js for HTTP API
• Socket.IO for real-time WebSocket communication
• Redis for pixel data and caching
• PostgreSQL for user data and canvas metadata
• JWT authentication

Frontend Stack

• Next.js 15.5 with App Router
• React 19 with Concurrent Features
• TypeScript for type safety
• Tailwind CSS for styling
• Framer Motion for animations
• Zustand for state management
• React Query for server state

Key Performance Optimizations

• Binary WebSocket Protocol: 90% reduction in network traffic
• Canvas Virtualization: Only render visible viewport
• Spatial Indexing: Redis-based chunk organization
• Connection Pooling: Optimized database connections
• Compression: Gzip compression for all responses

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Docker and Docker Compose
• Git

Development Setup

1. Clone the repository

   git clone <repository-url>
   cd collaborative-pixel-art
   

2. Install dependencies

   npm install
   

3. Start development servers (Easy Mode)

   npm run dev
   

   OR manually:

   node start-dev.js
   

4. Open the application

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:3001
   • Health Check: http://localhost:3001/health

Note: The application runs in development mode with mock databases by default (no Docker required). To use real Redis/PostgreSQL, see the Docker setup section below.

Full Docker Setup

# Start all services with Docker
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

📁 Project Structure

gaplace/
├── backend/                 # Node.js + TypeScript backend
│   ├── src/
│   │   ├── services/       # Business logic services
│   │   ├── config/         # Database and environment config
│   │   ├── middleware/     # Express middleware
│   │   └── server.ts       # Main server file
│   ├── Dockerfile
│   └── package.json
│
├── frontend/               # Next.js + React frontend
│   ├── src/
│   │   ├── app/           # Next.js app router
│   │   ├── components/    # React components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── store/         # Zustand state management
│   │   └── styles/        # Global styles
│   ├── Dockerfile
│   └── package.json
│
├── shared/                 # Shared TypeScript types and utilities
│   ├── src/
│   │   ├── types/         # Shared type definitions
│   │   ├── constants/     # Shared constants
│   │   └── utils/         # Shared utility functions
│   └── package.json
│
├── docs/                   # Documentation
├── docker-compose.yml      # Docker services
└── MODERNIZATION_PLAN.md   # Detailed technical plan

🎯 Performance Targets

• Canvas Size: 10,000+ x 10,000+ pixels supported
• Concurrent Users: 1000+ simultaneous users
• Load Time: <2 seconds for any viewport
• Memory Usage: <100MB for largest canvases
• Network Traffic: <1KB per pixel operation
• Frame Rate: 60 FPS during interactions

🔧 Configuration

Environment Variables

Backend (.env)

PORT=3001
NODE_ENV=development
JWT_SECRET=your-super-secret-key
CORS_ORIGIN=http://localhost:3000

# Database
REDIS_URL=redis://localhost:6379
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=gaplace
POSTGRES_USER=gaplace
POSTGRES_PASSWORD=password

# Rate Limiting
RATE_LIMIT_PIXELS_PER_MINUTE=60
RATE_LIMIT_PIXELS_PER_HOUR=1000

Frontend (.env.local)

NEXT_PUBLIC_BACKEND_URL=http://localhost:3001

🧪 Testing

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run specific workspace tests
npm run test --workspace=backend
npm run test --workspace=frontend

📦 Deployment

Production Build

# Build all packages
npm run build

# Start production server
npm start

Docker Production

# Build production images
docker-compose -f docker-compose.prod.yml build

# Deploy to production
docker-compose -f docker-compose.prod.yml up -d

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (npm run test)
5. Run linting (npm run lint)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by r/place and other collaborative art platforms
• Built with modern web technologies and best practices
• Optimized for performance and scalability

📚 Documentation

• Technical Architecture
• API Documentation
• Development Guide
• Deployment Guide

---

GaPlace - Where pixels meet collaboration 🎨✨