# Project Overview

## About UF r/place

UF r/place is a simplified clone of Reddit's r/place collaborative pixel canvas. This project is built as a monorepo with AWS cloud infrastructure, designed with extensibility in mind to allow easy addition of new features and resources.

## Architecture

The project follows a modern serverless architecture using AWS services:

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Next.js Web   │────│  API Gateway    │────│  Lambda         │
│   Frontend      │    │  REST API       │    │  Functions      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                │
                         ┌─────────────────┐
                         │   Future AWS    │
                         │   Resources     │
                         │ (DynamoDB, S3,  │
                         │  WebSocket, etc)│
                         └─────────────────┘
```

## Technology Stack

### Frontend (web/)
- **Next.js 14.2.6** - React framework with App Router
- **React 18.3.1** - UI library
- **TypeScript 5.4.5** - Type safety
- **ESLint** - Code linting

### Backend Infrastructure (infra/)
- **AWS CDK 2.152.0** - Infrastructure as Code
- **AWS Lambda** - Serverless compute (Node.js 20.x runtime)
- **AWS API Gateway** - REST API management
- **TypeScript 5.4.5** - Type safety for infrastructure code
- **esbuild** - Fast bundling for Lambda functions

### Development & Deployment
- **npm workspaces** - Monorepo management
- **AWS CLI** - AWS operations
- **Node.js 18+** - Runtime environment

## Project Structure

```
UF_r-place/
├── package.json           # Root workspace configuration
├── README.md             # Basic setup instructions
├── infra/               # AWS CDK Infrastructure
│   ├── bin/
│   │   └── app.ts       # CDK app entry point
│   ├── lib/
│   │   ├── backend-stack.ts      # Main infrastructure stack
│   │   └── constructs/
│   │       └── api-construct.ts  # API Gateway + Lambda construct
│   ├── lambda/
│   │   └── hello.ts     # Lambda function handlers
│   ├── cdk.json         # CDK configuration
│   └── package.json     # Infrastructure dependencies
└── web/                 # Next.js Frontend
    ├── app/
    │   ├── layout.tsx   # Root layout component
    │   ├── page.tsx     # Home page component
    │   └── globals.css  # Global styles
    ├── next.config.mjs  # Next.js configuration
    └── package.json     # Frontend dependencies
```

## Current Features

### Implemented
- ✅ **Basic API Infrastructure** - Lambda function with API Gateway
- ✅ **Frontend-Backend Integration** - Next.js app calling AWS API
- ✅ **CORS Configuration** - Cross-origin requests enabled
- ✅ **TypeScript Support** - Full type safety across the stack
- ✅ **Automated Bundling** - Lambda functions bundled with esbuild
- ✅ **Environment Configuration** - Separate dev/prod environments

### API Endpoints
- `GET /hello` - Simple health check endpoint returning JSON message

## Design Principles

### Extensibility
The project is structured to make adding new features straightforward:
- **Modular Constructs** - Infrastructure components are separated into reusable constructs
- **Workspace Organization** - Clear separation between frontend and infrastructure
- **Type Safety** - TypeScript throughout ensures safe refactoring
- **Environment Management** - Easy configuration for different deployment stages

### Simplicity
- **Minimal Setup** - Few prerequisites and clear setup instructions
- **Monorepo Structure** - Everything in one place for easy development
- **Automated Deployment** - Single command deployment to AWS

### AWS Best Practices
- **Serverless First** - Using Lambda for compute to minimize costs
- **Regional Deployment** - API Gateway configured for regional endpoints
- **Proper Tagging** - Resources tagged with project information
- **Stack Outputs** - Important values exported for reference

## Resource Management

### Deployment Commands
```bash
# Initial setup (one-time per AWS account/region)
npm run cdk:bootstrap

# Deploy infrastructure
npm run cdk:deploy
npm run deploy        # Alternative

# Build and run locally
npm run build
npm run dev
```

### Cleanup Commands
```bash
# Remove project resources (recommended)
npm run destroy
npm run cdk:destroy   # Alternative

# Complete cleanup (including CDK bootstrap)
aws cloudformation delete-stack --stack-name CDKToolkit
```

### Cost Considerations
- **Development**: All resources designed to fit within AWS Free Tier
- **Lambda**: 1M free requests per month
- **API Gateway**: 1M API calls per month  
- **CloudWatch**: Basic logging included
- **Estimated monthly cost**: $0 for typical development usage

## Future Extensibility Points

The architecture is designed to easily accommodate:
- **Database Layer** - DynamoDB for storing canvas state
- **Real-time Updates** - WebSocket API for live pixel updates
- **Load Balancing** - Application Load Balancer for high traffic
- **CDN** - CloudFront for global content delivery
- **Authentication** - Cognito for user management
- **Monitoring** - CloudWatch for observability
- **Caching** - ElastiCache for performance optimization