🎨 Status: MVP Complete & Running | 🚀 Version 1.0.0 | 📅 Last Updated: October 2025

A modern, full-stack image manipulation web application powered by AI models. Avatrix combines traditional image editing tools with cutting-edge AI capabilities for intelligent image manipulation, inpainting, and background removal.

✅ Completed Features (MVP)

• ✅ Full-stack application architecture
• ✅ FastAPI backend with async support
• ✅ React TypeScript frontend with Tailwind CSS
• ✅ Basic image editing operations (crop, resize, rotate, flip)
• ✅ Image filters and adjustments
• ✅ File upload system with validation
• ✅ Undo/Redo with 50-state history
• ✅ State management with Zustand
• ✅ HuggingFace API integration
• ✅ AI inpainting with Stable Diffusion
• ✅ Background removal capability
• ✅ Async job processing
• ✅ Docker containerization
• ✅ Comprehensive documentation

🔧 In Progress

• 🔄 Frontend-backend integration fixes
• 🔄 Image upload error handling improvements
• 🔄 Canvas-based editor implementation
• 🔄 Real-time preview enhancements

📊 Project Health

• Lines of Code: ~1,200+ (backend + frontend)
• Backend: 15+ API endpoints fully implemented
• Frontend: Core UI and state management complete
• Test Coverage: Pending
• Documentation: Comprehensive (README, QUICKSTART, PROJECT_SUMMARY)

• Crop & Resize - Intelligent cropping with aspect ratio preservation
• Rotate & Flip - Rotate images at any angle or flip horizontally/vertically
• Filters - Apply grayscale, sepia, blur, sharpen effects
• Adjustments - Fine-tune brightness, contrast, saturation, and hue

• AI Inpainting - Remove objects or fill missing areas using Stable Diffusion
• Background Removal - Automatically segment and remove backgrounds
• Smart Edits - Text-prompt guided image modifications

• Undo/Redo - Full history tracking with 50-state memory
• Real-time Preview - Instant visualization of edits
• File Support - JPEG, PNG, WebP formats (up to 10MB)
• Responsive Design - Works on desktop, tablet, and mobile

• FastAPI - Modern, high-performance Python web framework
• PyTorch & Diffusers - AI model inference
• Pillow & OpenCV - Image processing
• Redis - Caching and job queue
• Celery - Async task processing

• React 18 - UI library with TypeScript
• Vite - Fast build tool and dev server
• Tailwind CSS - Utility-first styling
• Zustand - Lightweight state management
• Axios - HTTP client

• stabilityai/stable-diffusion-2-inpainting - Image inpainting
• briaai/RMBG-1.4 - Background removal

avatrix/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   │   └── routes/
│   │   │       ├── images.py      # Image manipulation endpoints
│   │   │       └── ai.py          # AI processing endpoints
│   │   ├── core/
│   │   │   └── config.py          # Configuration management
│   │   ├── models/
│   │   │   └── schemas.py         # Pydantic models
│   │   ├── services/
│   │   │   └── ai_service.py      # HuggingFace integration
│   │   ├── utils/
│   │   │   ├── image_processor.py # Image processing utilities
│   │   │   └── file_handler.py    # File upload/storage
│   │   └── main.py                # FastAPI application
│   ├── requirements.txt
│   ├── Dockerfile
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── components/            # React components
│   │   ├── services/
│   │   │   └── api.ts             # API client
│   │   ├── store/
│   │   │   └── editorStore.ts     # Zustand state management
│   │   ├── types/
│   │   │   └── index.ts           # TypeScript types
│   │   ├── App.tsx                # Main application
│   │   └── main.tsx               # Entry point
│   ├── package.json
│   ├── vite.config.ts
│   ├── tailwind.config.js
│   └── Dockerfile
├── docker-compose.yml
├── uploads/                       # Uploaded images
├── temp/                          # Temporary files
└── README.md

• Python 3.11+
• Node.js 20+
• Redis (optional, for Docker setup)
• HuggingFace API key

1. Clone the repository

   git clone <repository-url>
   cd avatrix

2. Set up environment variables

   cp backend/.env.example backend/.env

3. Add your HuggingFace API key

   # Edit backend/.env
   HUGGINGFACE_API_KEY=your_token_here

4. Start all services

   docker-compose up -d

5. Access the application

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Docs: http://localhost:8000/docs

1. Navigate to backend directory

   cd backend

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Set up environment variables

   cp .env.example .env
   # Edit .env with your settings

5. Run the server

   python -m app.main
   # Or use uvicorn directly:
   uvicorn app.main:app --reload

1. Navigate to frontend directory

   cd frontend

2. Install dependencies

   npm install

3. Start development server

   npm run dev

4. Open browser

   http://localhost:3000
   

# Application
APP_NAME=Avatrix
DEBUG=true
ENVIRONMENT=development

# Server
HOST=0.0.0.0
PORT=8000

# CORS
ALLOWED_ORIGINS=http://localhost:3000

# File Upload
MAX_UPLOAD_SIZE=10485760  # 10MB
ALLOWED_EXTENSIONS=jpg,jpeg,png,webp
UPLOAD_DIR=../uploads
TEMP_DIR=../temp

# AI/ML
HUGGINGFACE_API_KEY=your_token_here
USE_LOCAL_MODELS=false  # Set to true for local model inference

# Redis (optional)
REDIS_HOST=localhost
REDIS_PORT=6379

# Image Processing
MAX_IMAGE_WIDTH=4096
MAX_IMAGE_HEIGHT=4096

Create a .env file in the frontend directory:

VITE_API_URL=http://localhost:8000/api

POST /api/images/upload
Content-Type: multipart/form-data

Response:
{
  "success": true,
  "image_id": "uuid",
  "image_url": "/api/images/uuid",
  "width": 1920,
  "height": 1080
}

POST /api/images/{image_id}/crop
Content-Type: application/json

{
  "x": 100,
  "y": 100,
  "width": 800,
  "height": 600
}

POST /api/ai/{image_id}/inpaint
Content-Type: application/json

{
  "mask_data": "base64_encoded_mask",
  "prompt": "beautiful landscape",
  "num_inference_steps": 50,
  "guidance_scale": 7.5
}

Response:
{
  "job_id": "uuid",
  "status": "pending",
  "progress": 0
}

GET /api/ai/jobs/{job_id}

Response:
{
  "job_id": "uuid",
  "status": "completed",
  "progress": 100,
  "result": {
    "image_id": "new_uuid",
    "image_url": "/api/images/new_uuid"
  }
}

Full API documentation available at: http://localhost:8000/docs

1. Upload an image - Drag and drop or click to select
2. Select a tool from the sidebar
3. Apply edits - Changes are instant
4. Use undo/redo to navigate history
5. Download your edited image

1. Upload an image
2. Click "AI Inpainting" tool
3. Paint over areas you want to modify
4. (Optional) Add a text prompt
5. Click "Generate"
6. Wait for AI processing
7. Review and download result

1. Upload an image
2. Click "Remove Background"
3. Adjust threshold if needed
4. Process image
5. Download transparent PNG

# Backend tests
cd backend
pytest

# Frontend tests
cd frontend
npm test

cd backend
docker build -t avatrix-backend .

cd frontend
npm run build

• Backend: Black formatter, PEP 8
• Frontend: ESLint, Prettier

# Format backend code
black backend/app

# Lint frontend code
cd frontend
npm run lint

• Images are automatically compressed
• JPEG quality: 95%
• PNG optimization enabled
• Maximum dimensions: 4096x4096px

• 10 requests per minute (default)
• 100 requests per hour
• Configurable in settings

• Redis caching for API responses
• Browser caching for static assets
• Service worker for offline support (optional)

Backend won't start

• Check Python version (3.11+)
• Verify all dependencies installed
• Check Redis connection
• Review environment variables

Frontend build errors

• Clear node_modules and reinstall
• Check Node.js version (20+)
• Verify API URL configuration

AI models not loading

• Verify HuggingFace API key
• Check internet connection
• Models may take 20-30s to load initially
• Check API rate limits

Upload fails

• Verify file size < 10MB
• Check file format (JPEG/PNG/WEBP)
• Ensure upload directory exists
• Check disk space

# Backend logs
docker-compose logs backend

# Frontend logs
docker-compose logs frontend

# Redis logs
docker-compose logs redis

1. Environment Variables

   • Set DEBUG=false
   • Use strong secrets
   • Configure production CORS origins

2. Database

   • Use persistent Redis storage
   • Regular backups
   • Monitor disk usage

3. Security

   • Enable HTTPS
   • Implement authentication
   • Rate limiting
   • Input validation
   • File type verification

4. Monitoring

   • Application logs
   • Error tracking (Sentry)
   • Performance monitoring
   • Uptime monitoring

5. Scaling

   • Load balancer
   • Multiple Celery workers
   • CDN for static assets
   • Image optimization service

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

This project is licensed under the MIT License.

• Stability AI - Stable Diffusion models
• HuggingFace - Model hosting and API
• FastAPI - Backend framework
• React - Frontend library
• Tailwind CSS - Styling framework

• GitHub Issues: Report bugs and request features
• Documentation: Full API docs at /docs
• Email: [email protected] (example)

• Advanced canvas editor with layers
• More AI models (style transfer, upscaling)
• Batch processing
• User accounts and saved projects
• Plugin system for custom tools
• Mobile apps (iOS/Android)
• Desktop app (Electron)

Built with ❤️ using FastAPI, React, and AI