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**
   ```bash
   git clone <repository-url>
   cd collaborative-pixel-art
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Start development servers (Easy Mode)**
   ```bash
   npm run dev
   ```
   
   **OR manually:**
   ```bash
   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

```bash
# 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)
```bash
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)
```bash
NEXT_PUBLIC_BACKEND_URL=http://localhost:3001
```

## 🧪 Testing

```bash
# 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
```bash
# Build all packages
npm run build

# Start production server
npm start
```

### Docker Production
```bash
# 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](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](MODERNIZATION_PLAN.md)
- [API Documentation](docs/api.md)
- [Development Guide](docs/development.md)
- [Deployment Guide](docs/deployment.md)

---

**GaPlace** - Where pixels meet collaboration 🎨✨