Add INSTRUCTIONS.md with development roadmap and setup guide

2026-03-07 22:40:22 -06:00
parent 70bcae1c6a
commit b48c7a7561
1 changed files with 228 additions and 0 deletions
--- a/INSTRUCTIONS.md
+++ b/INSTRUCTIONS.md
@@ -0,0 +1,228 @@
+# 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