Image Project Manager

A full-stack web application for managing, classifying, and collaborating on visual content. Built for teams that need to organize image datasets, apply custom labels, and integrate machine learning analysis results.

Features

• Project Organization - Group images into projects with team-based access control
• Image Classification - Apply custom labels and categories to organize images
• Team Collaboration - Add comments and share insights with your team
• Metadata Management - Store custom key-value metadata for projects and images
• ML Analysis Integration - Visualize machine learning results with interactive overlays (bounding boxes, heatmaps)
• Safe Deletion - Two-stage deletion with 60-day recovery period
• API Access - RESTful API with comprehensive documentation and API key authentication

Requirements

• Node.js 22+
• Python 3.11+
• Docker (for PostgreSQL and MinIO)
• uv - Python package manager (pip install uv)

Quick Start

1. Start Infrastructure

# Start PostgreSQL and MinIO containers
docker compose up -d postgres minio

2. Setup Backend

# Install uv package manager
pip install uv

# Create virtual environment and install dependencies
uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt

# Run database migrations (REQUIRED)
cd backend
alembic upgrade head

# Start backend server
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Alternative: Use the backend helper script:

cd backend
./run.sh

3. Setup Frontend

In a separate terminal:

cd frontend
npm install
npm run dev

4. Access the Application

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs (Swagger UI)
• Alternative API Docs: http://localhost:8000/redoc (ReDoc)

Configuration

Environment Setup

1. Copy the example environment file:

   cp .env.example .env

2. Configure the following settings in .env:

Database:

DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5433/postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=postgres

S3/MinIO Storage:

S3_ENDPOINT=localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadminpassword
S3_BUCKET=data-storage
S3_USE_SSL=false

Authentication:

# Development (uses mock user)
[email protected]
MOCK_USER_GROUPS_JSON='["admin-group", "data-scientists"]'

# Production (reverse proxy authentication)
PROXY_SHARED_SECRET=your-secure-secret-here
AUTH_SERVER_URL=https://your-auth-server.com

ML Analysis (Optional):

ML_ANALYSIS_ENABLED=true
ML_CALLBACK_HMAC_SECRET=your-hmac-secret
ML_ALLOWED_MODELS=yolo_v8,resnet50_classifier

Database Migrations (Alembic)

Important: Migrations are NOT run automatically. This is intentional to prevent accidental schema changes in production.

Running Migrations

cd backend
source .venv/bin/activate
alembic upgrade head

Creating New Migrations

After modifying models in core/models.py:

cd backend
alembic revision --autogenerate -m "describe your changes"

Always review the generated migration file before applying!

Common Migration Commands

alembic upgrade head              # Apply all pending migrations
alembic downgrade -1              # Rollback last migration
alembic history --verbose         # View migration history
alembic current                   # Show current database version
alembic stamp head                # Mark DB as up-to-date (use cautiously)

Why Manual Migrations?

Manual migrations prevent:

• Accidental schema changes in production
• Race conditions with multiple application instances
• Unexpected downtime during deployments
• Loss of control over when schema changes occur

Troubleshooting

Issue	Solution
Autogenerate misses table	Verify model is imported in core/models.py
Dialect errors	Ensure using PostgreSQL URL, not SQLite
Schema drift	Run alembic upgrade head then regenerate migration

Development

Running Tests

Backend tests (pytest):

source .venv/bin/activate
cd backend
pytest                                          # Run all tests
pytest tests/test_specific.py                  # Run specific file
pytest tests/test_file.py::test_function       # Run specific test
pytest -v                                       # Verbose output
pytest -k "auth"                                # Run tests matching pattern
pytest --coverage                               # With coverage report

Frontend tests (Jest):

cd frontend
npm test                    # Interactive mode
npm test -- --coverage      # With coverage report

Building for Production

Frontend:

cd frontend
npm run build

Docker image:

docker build -t image-project-manager .
docker run -p 8000:8000 image-project-manager

Access at http://localhost:8000

ML Analysis Feature

This feature allows external ML pipelines to submit analysis results for visualization in the UI. Users cannot trigger analyses directly - they are initiated by external systems.

For End Users

1. Navigate to an image in the web interface
2. If ML analyses exist, view them in the "ML Analyses" sidebar panel
3. Toggle bounding box and heatmap overlays
4. Adjust visualization opacity or use side-by-side comparison
5. Export results as JSON or CSV

For ML Pipeline Developers

Configuration

ML_ANALYSIS_ENABLED=true
ML_CALLBACK_HMAC_SECRET=your-secure-secret
ML_ALLOWED_MODELS=yolo_v8,resnet50_classifier,custom_model

API Integration Workflow

1. Create analysis - POST /api/images/{image_id}/analyses
2. Update to processing - PATCH /api/analyses/{analysis_id}/status
3. Request presigned URL - POST /api/analyses/{analysis_id}/artifacts/presign
4. Upload artifacts to S3 - PUT <presigned_url>
5. Submit annotations - POST /api/analyses/{analysis_id}/annotations:bulk
6. Finalize - POST /api/analyses/{analysis_id}/finalize

Security: Pipeline endpoints require HMAC authentication:

• Header: X-ML-Signature (HMAC-SHA256 of request body)
• Header: X-ML-Timestamp (Unix timestamp for replay protection)

Testing the Pipeline

export ML_CALLBACK_HMAC_SECRET='your_secret_here'
python scripts/test_ml_pipeline.py --image-id <uuid>

For detailed integration guide, see API documentation at http://localhost:8000/docs

Production Deployment

Reverse Proxy Setup

Production deployments require a reverse proxy for authentication. See comprehensive documentation:

• Setup Guide: docs/production/proxy-setup.md
• Nginx Example: docs/production/nginx-example.conf

The application uses header-based authentication where the reverse proxy authenticates users and forwards their identity to the backend via HTTP headers.

Docker Deployment

docker build -t image-project-manager .
docker run -p 8000:8000 image-project-manager

Access at http://localhost:8000

Kubernetes Deployment

Test deployment using minikube:

# Start minikube
minikube start

# Build and load image
docker build -t image-project-manager:latest .
minikube image load image-project-manager:latest

# Deploy
kubectl apply -f deployment-test/

# Access application
minikube service image-project-manager --url

See deployment-test/ directory for Kubernetes manifests.

Note: The dev container includes minikube, kubectl, and helm pre-installed.

Architecture

Technology Stack

• Backend: FastAPI (Python 3.11+) with async SQLAlchemy
• Frontend: React 18 with React Router
• Database: PostgreSQL 15
• Storage: MinIO/S3 compatible object storage
• Migrations: Alembic
• Caching: aiocache + diskcache

Project Structure

backend/
├── main.py              # Application entry point
├── core/                # Core components (models, schemas, config)
├── routers/             # API endpoint definitions
├── middleware/          # Authentication, CORS, security headers
├── utils/               # Shared utilities (CRUD, caching, S3)
├── alembic/             # Database migrations
└── tests/               # Backend tests

frontend/
├── src/
│   ├── App.js           # Main application component
│   ├── Project.js       # Project view
│   ├── ImageView.js     # Image detail view
│   └── components/      # Reusable React components

Authentication

• Development: Mock user from environment variables
• Production: Header-based authentication via reverse proxy
• Group-based access control: Projects belong to groups
• API keys: Programmatic access via API key authentication

Documentation

Comprehensive guides for different user roles:

For Users

• User Guide - Complete guide for end users
  • Getting started
  • Managing projects and images
  • Classification and collaboration
  • ML analysis visualization

For Administrators

• Administrator Guide - Deployment and maintenance
  • Installation & Deployment - Docker, Kubernetes, manual setup
  • Configuration - Environment variables and settings
  • Authentication & Security - Reverse proxy setup and security
  • Database Management - PostgreSQL, migrations, backups
  • Storage Configuration - S3/MinIO setup and management
  • Monitoring & Maintenance - Logging, metrics, updates
  • Troubleshooting - Common issues and solutions

For Developers

• Developer Guide - Development and contribution guide
  • Development environment setup
  • Architecture overview
  • Backend and frontend development
  • API development
  • Testing and code style

For ML Integration

• ML Analysis API Guide - Machine learning integration
  • Authentication and workflow
  • API endpoints and data formats
  • Example implementations
  • Testing and best practices

Additional Resources

• Production Proxy Setup - Detailed reverse proxy configuration
• API Documentation: http://localhost:8000/docs (Swagger UI)
• Alternative API Docs: http://localhost:8000/redoc (ReDoc)
• pgAdmin (Database UI): http://localhost:8080 (user: [email protected], pass: admin)
• MinIO Console: http://localhost:9001 (user: minioadmin, pass: minioadminpassword)

License

MIT