pnger/INSTRUCTIONS.md

# PNGer Development Instructions

## Project Overview

PNGer is a single-container web application for PNG editing and resizing, designed for deployment on Unraid with Gitea version control.

## Development Roadmap

### Phase 1: MVP Foundation (Current)
- [x] Repository setup
- [ ] Project structure initialization
- [ ] Backend API scaffold
- [ ] Frontend scaffold
- [ ] Basic upload/download flow
- [ ] Dockerfile configuration

### Phase 2: Core Features
- [ ] Image resize functionality
- [ ] PNG compression
- [ ] Real-time preview
- [ ] Responsive UI design
- [ ] Error handling

### Phase 3: Polish & Deployment
- [ ] Docker Compose for Unraid
- [ ] Environment configuration
- [ ] Documentation
- [ ] Testing
- [ ] Production build optimization

## Technical Architecture

### Backend (Express + Sharp)

**Endpoints:**
- `POST /api/upload` - Accept PNG file
- `POST /api/process` - Resize/compress image
- `GET /api/health` - Health check

**Key Dependencies:**
- express: Web framework
- multer: File upload handling
- sharp: Image processing
- cors: Cross-origin support

### Frontend (Svelte + Vite)

**Components:**
- `App.svelte` - Main container
- `Uploader.svelte` - Drag & drop interface
- `Editor.svelte` - Resize controls
- `Preview.svelte` - Real-time image preview
- `Download.svelte` - Download button

**Key Dependencies:**
- svelte: Reactive framework
- vite: Build tool
- axios: HTTP client

### Docker Strategy

**Multi-stage Build:**
1. Stage 1: Build frontend (Vite build)
2. Stage 2: Copy frontend + setup backend
3. Final image: Alpine-based Node.js

**Image Size Target:** < 150MB

## Local Development Setup

### Prerequisites
- Node.js 20+
- npm or pnpm
- Docker (optional)

### Initial Setup

```bash
# Clone repository
git clone https://git.alwisp.com/jason/pnger.git
cd pnger

# Install root dependencies (if monorepo)
npm install

# Setup backend
cd backend
npm install
npm run dev

# Setup frontend (new terminal)
cd frontend
npm install
npm run dev
```

### Development Workflow

1. **Feature Branch**: Create from `main`
2. **Develop**: Make changes with hot-reload
3. **Test**: Manual testing + health checks
4. **Commit**: Descriptive commit messages
5. **Push**: Push to Gitea
6. **Review**: Self-review changes
7. **Merge**: Merge to `main`

### Environment Variables

**Backend (.env):**
```
PORT=3000
NODE_ENV=development
MAX_FILE_SIZE=10
CORS_ORIGIN=http://localhost:5173
```

**Frontend (.env):**
```
VITE_API_URL=http://localhost:3000/api
```

## Docker Build & Test

```bash
# Build image
docker build -t pnger:test .

# Run container
docker run -p 8080:3000 --name pnger-test pnger:test

# Test endpoints
curl http://localhost:8080/api/health

# View logs
docker logs pnger-test

# Stop and remove
docker stop pnger-test && docker rm pnger-test
```

## Unraid Deployment

### Setup Steps

1. **SSH into Unraid**
2. **Navigate to docker configs**: `/mnt/user/appdata/pnger`
3. **Clone repository**:
   ```bash
   git clone https://git.alwisp.com/jason/pnger.git
   cd pnger
   ```
4. **Build and run**:
   ```bash
   docker-compose up -d
   ```
5. **Access**: http://[unraid-ip]:8080

### Update Process

```bash
cd /mnt/user/appdata/pnger
git pull origin main
docker-compose down
docker-compose build
docker-compose up -d
```

## Code Standards

### JavaScript/Svelte
- Use ES6+ features
- Async/await for asynchronous operations
- Descriptive variable names
- Comments for complex logic only

### File Organization
- One component per file
- Group related utilities
- Keep components under 200 lines

### Commit Messages
- Format: `type: description`
- Types: feat, fix, docs, style, refactor, test
- Example: `feat: add drag and drop upload`

## Troubleshooting

### Common Issues

**Port already in use:**
```bash
lsof -ti:3000 | xargs kill -9
```

**Sharp installation issues:**
```bash
npm rebuild sharp
```

**Docker build fails:**
- Check Docker daemon is running
- Verify Dockerfile syntax
- Clear Docker cache: `docker builder prune`

## Performance Targets

- Upload handling: < 100ms (for 5MB file)
- Image processing: < 2s (for 10MP image)
- Download generation: < 500ms
- UI response time: < 100ms
- Docker image size: < 150MB

## Security Considerations

- File type validation (PNG only)
- File size limits (10MB default)
- No persistent storage of user files
- Memory cleanup after processing
- CORS configuration

## Next Steps

1. Create backend folder structure
2. Create frontend folder structure
3. Initialize package.json files
4. Create Dockerfile
5. Create docker-compose.yml
6. Begin MVP development