EN | 中文 | ID

✨ PixelForge

The open-source image studio that blends AI cloud power with pro-grade browser editing

🚀 Why PixelForge

PixelForge started as a single-purpose AI upscaler and evolved into a full-stack image processing platform. It combines AI-powered cloud processing (upscale, background removal, restoration) with fast client-side editing tools (resize, compress, transform, metadata cleaning). The system is designed to handle real-world constraints such as rate limits, long-running AI jobs, and storage lifecycle management through an async queue-based architecture.

• ⚡ AI where it matters, instant client-side tools where it’s faster
• 🔐 Security-first pipeline (Turnstile, signed URLs, validation, anti-spoof proxy strategy)
• 🧠 Reliable architecture (async jobs, usage limits, janitor cleanup, session recovery)
• 🎨 Beautiful UX with before/after comparisons and staged progress feedback
• 🛠️ Open-source and extensible provider architecture

🎯 Features

A) Core Image Tools

1. 🔍 Upscale Image (AI) — Real-ESRGAN enhancement

🎥 Click to watch the preview

UPSCALE.mp4

2. 🧍 Remove Background (AI) — clean subject extraction

🎥 Click to watch the preview

REMBG.mp4

3. 🎨 Restore Color (AI) — revive grayscale & faded photos

🎥 Click to watch the preview

RESTORE.COLOR.mp4

4. 🎛️ Image Editor — brightness, contrast, saturation, blur, vignette

🎥 Click to watch the preview

EDIT.IMAGE.mp4

5. 📐 Resize Image — custom size, aspect lock, presets

🎥 Click to watch the preview

RESIZE.IMAGE.mp4

6. 🔄 Rotate & Flip — quick transform controls

🎥 Click to watch the preview

ROTATE.IMAGE.mp4

7. 🗜️ Compress Image — reduce size with quality control

🎥 Click to watch the preview

COMPRESS.IMAGE.mp4

8. 🔁 Convert Format — PNG / JPG / WEBP

🎥 Click to watch the preview

CONVERT.IMAGE.mp4

9. 🧹 Remove Metadata — clean EXIF data

🎥 Click to watch the preview

METADATA.mp4

10. 🎯 Color Palette Extractor — draggable sampling points

🎥 Click to watch the preview

COLOR.PALETTE.mp4

11. 🏷️ Add Watermark — text/image with live preview

🎥 Click to watch the preview

WATERMARK.mp4

12. ✂️ Crop Image — freeform or preset aspect ratios

🎥 Click to watch the preview

CROP.IMAGE.mp4

13. 🖼️ Thumbnail Maker (Coming Soon)

14. 🤖 Chatbot — Interactive FAQ assistant for quick answers and guided platform help

🎥 Click to watch the preview

CHATBOT.mp4

15. 📝 Feedback System — user input for improvements and bug reports

B) Platform & System Capabilities

16. 🛡️ Turnstile Verification — bot protection layer
17. 📊 Usage Limits — per-feature daily caps
18. 🚦 Rate Limiting — controlled API flow
19. ⚙️ Async Job Queue — safe background processing
20. 🔄 Status Polling — processing / ready / failed
21. 💾 Session Persistence — IndexedDB + localStorage
22. 🔁 Session Restore — recover after refresh
23. ⏳ Expiration Handling — results & drafts lifecycle
24. 🧽 Azure Cleanup — expired result janitor
25. 🧹 DB Cleanup — usage data maintenance
26. 🔑 Signed URLs — secure upload & access
27. 🔍 File Validation — type, size, spoof detection
28. 🏷️ Filename Sanitization — safe file handling
29. 🧩 Workspace System — reusable UI shell
30. 📢 Modal System — legal & alert handling
31. 🆚 Comparison Slider — before/after preview
32. 🎬 Progress UX — staged loading feedback

🧠 Architecture Highlights

PixelForge is designed to balance performance, cost, and reliability while working with external AI APIs that have strict rate and concurrency limits. Key architectural decisions include:

• Queue-based AI processing system to handle long-running jobs
• Decoupled upload → process → result pipeline
• Concurrency control to prevent overload and API abuse
• Stateless API with client-side job tracking
• Hybrid processing model (AI in cloud, instant tools in browser)
• Storage lifecycle management with automatic cleanup
• Pluggable AI provider layer for future model integrations

💡 Design Considerations

• AI jobs are handled asynchronously due to long execution times and external API limits
• Polling is used instead of WebSockets for simplicity and reliability
• Signed URLs reduce backend load and improve upload/download performance
• Rate limiting and usage caps prevent abuse and control costs

🔧 Processing Models

PixelForge uses a hybrid processing model to balance performance and cost: AI-intensive tasks are handled asynchronously on the backend, while lightweight operations are executed instantly in the browser.

🔄 AI Processing Flow (Asynchronous)

The system separates processing paths based on workload type to optimize performance and cost :

1. User uploads image → validated and sanitized
2. Backend generates signed upload URL (Azure Blob)
3. File uploaded directly to storage
4. Job created and queued for processing
5. AI provider executes task asynchronously
6. Client polls job status via API
7. Result stored with signed access URL
8. Frontend retrieves and displays result
9. Cleanup system removes expired data

⚡ Client-Side Processing Flow (Instant)

The frontend handles all lightweight transformations directly in the browser for instant feedback and zero backend load to provide a seamless user experience:

1. User uploads image
2. Image processed directly in browser (resize, compress, transform, etc.)
3. No backend interaction required
4. Result generated instantly
5. User downloads processed file

🏗️ Architecture & Stack

PixelForge uses a split architecture:

• Frontend (React + Vite + Tailwind)
  Handles tool UI, previews, client-side transforms, session persistence (IndexedDB/localStorage), and interaction flow.

• Backend (FastAPI + asyncpg + aiohttp)
  Handles secure AI orchestration, Turnstile verification, usage/rate limits, signed upload/result URLs, and polling endpoints.

• AI Inference (Replicate Python SDK)
  Model calls go through a provider abstraction (BaseAIProvider / ReplicateProvider) so the AI layer is modular and extensible.

• Storage + Data (Azure Blob + PostgreSQL)
  Azure Blob manages upload/result lifecycle; PostgreSQL stores usage buckets and retention-driven state.

⚙️ Environment Variables

Backend (root/backend env)

AZURE_CONNECTION_STRING=
REPLICATE_API_TOKEN=
ALLOWED_ORIGINS=
CLOUDFLARE_TURNSTILE_SITE_KEY=
CLOUDFLARE_TURNSTILE_SECRET_KEY=
DATABASE_URL=
CLOUDFLARE_SUBNETS=
ENVIRONMENT=
ALLOW_TURNSTILE_TEST_BYPASS=
TRUST_PROXY_HEADERS=
REQUIRE_CLOUDFLARE_PROXY=
STRICT_ENV_VALIDATION=

Frontend

VITE_API_BASE_URL=http://127.0.0.1:8000/api
VITE_TURNSTILE_SITE_KEY=0x4AAAAAACxEYGPTmGZUjctK

For local testing, keep API base URL at local backend.
For deployment, switch to your hosted API endpoint (example: https://your-domain/app/api).

🚀 Local Development

1) Clone

git clone https://github.com/Dendroculus/PixelForge.git
cd PixelForge

2) Run backend

cd backend
python -m venv .venv
source .venv/bin/activate      # macOS/Linux
# .venv\Scripts\activate       # Windows
pip install -r requirements.txt
uvicorn main:app --reload

3) Run frontend

cd frontend
npm install
npm run dev

🔒 Security Notes

• Turnstile check before AI init routes
• Proxy/IP trust strategy to reduce header spoofing risk
• Signed SAS URLs for controlled blob access
• Strict file validation + capped dimensions/size
• Automated cleanup for privacy and storage hygiene

🛠 Built With

• React + Vite (frontend)
• FastAPI (backend)
• Replicate (AI model inference)
• Azure Blob Storage (upload/result lifecycle)
• PostgreSQL (usage limits & retention windows)
• Cloudflare Turnstile (bot protection)

🤝 Contributing

PRs and improvements are welcome.
If you’re planning a bigger change, open an issue first to align on scope.

📜 License

Licensed under the MIT License. See LICENSE for details.

🙏 Acknowledgements

• Real-ESRGAN ecosystem
• Replicate platform
• FastAPI, React, and open-source contributors

👤 Contributors

Made with ❤️ by the PixelForge team:

Hans Lead Developer

Wellson Project Coordinator

Lawi UI/UX Designer

Jensen QA Lead & Stakeholder