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)

• 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

# 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

# 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:

   git clone https://git.alwisp.com/jason/pnger.git
   cd pnger
   

4. Build and run:

   docker-compose up -d
   

5. Access: http://[unraid-ip]:8080

Update Process

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:

lsof -ti:3000 | xargs kill -9

Sharp installation issues:

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