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. 🎨 Object Remover (AI) — brush over unwanted objects and erase them cleanly

🎥 Click to watch the preview

OBJECT_RMOVE.mp4

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

🎥 Click to watch the preview

EDIT.IMAGE.mp4

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

🎥 Click to watch the preview

RESIZE.IMAGE.mp4

7. 🔄 Rotate & Flip — quick transform controls

🎥 Click to watch the preview

ROTATE.IMAGE.mp4

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

🎥 Click to watch the preview

COMPRESS.IMAGE.mp4

9. 🔁 Convert Format — PNG / JPG / WEBP

🎥 Click to watch the preview

CONVERT.IMAGE.mp4

10. 🧹 Remove Metadata — clean EXIF data

🎥 Click to watch the preview

METADATA.mp4

11. 🎯 Color Palette Extractor — draggable sampling points

🎥 Click to watch the preview

COLOR.PALETTE.mp4

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

🎥 Click to watch the preview

WATERMARK.mp4

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

🎥 Click to watch the preview

CROP.IMAGE.mp4

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, and resolution safety
28. 📉 Auto-Resize for Oversized Images — browser-side downscaling for images above the public pixel limit
29. 🏷️ Filename Sanitization — safe file handling
30. 🧩 Workspace System — reusable UI shell
31. 📢 Modal System — legal & alert handling
32. 🆚 Comparison Slider — before/after preview
33. 🎬 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 selects an image
2. Frontend validates type, size, and resolution
3. Oversized but safe images are resized in the browser before upload
4. Backend verifies Turnstile and checks usage quota
5. Backend generates signed upload URL metadata
6. File uploads directly to Azure Blob Storage
7. Backend reserves queue capacity and increments usage when processing starts
8. AI provider executes the task asynchronously
9. Client polls job status via API
10. Result is stored with a signed access URL
11. 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.

For more details, see docs/ARCHITECTURE.md.

⚙️ 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

Need help setting up external services? See SETUP.md for step-by-step instructions on configuring Azure Blob Storage, Replicate, Cloudflare Turnstile, PostgreSQL, Discord webhooks, and environment variables.

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
• Public AI uploads use a lower browser-side pixel limit for user experience
• Backend validation remains the security boundary with a higher hard pixel safety cap
• Oversized images may be resized before upload, while oversized files are still rejected by byte-size limits
• 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.

For contributing guidelines, see CONTRIBUTING.md.
Please follow our Code of Conduct.
For security issues, please see our Security Policy.

📜 License

Licensed under the MIT License. See LICENSE for details.

📝 Developer Docs

How to add a new AI feature to PixelForge:

• Adding a New AI Feature

Backend and AI test scripts:

• Testing PixelForge (ID, ZH)

Developer helper scripts:

• Total Line Counter — interactive Windows PowerShell script for counting project lines by folder, extension, and section.

Local PowerShell scripts and .bat helper files are intended for Windows development environments.

🙏 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