Oliver Metadata Tool v4.0

Universal metadata creation and management tool for all file types.

Create, import, and manage metadata from multiple sources with a modern React interface, FastAPI backend, persistent Redis sessions, and AI-powered metadata generation.

Developer: Vadym Samoilenko License: Corporate License - Oliver Marketing Version: 4.0 (FastAPI + React Edition)

---

🚀 Quick Start

Production Deployment (Ubuntu Server)

# 1. Clone repository
cd /opt
sudo git clone https://bitbucket.org/zlalani/solventum-image-metadata.git
cd solventum-image-metadata

# 2. Configure environment
sudo cp .env.production .env
sudo nano .env  # Add your secrets

# 3. Deploy
sudo ./deploy.sh

That's it! The script automatically:

• ✅ Builds Docker containers
• ✅ Initializes database
• ✅ Builds React frontend
• ✅ Deploys to /var/www/html/
• ✅ Runs health checks

See PRODUCTION-DEPLOY.md for detailed instructions.

---

📋 Features

Multiple Metadata Sources

• 📂 File Import: Import metadata from CSV, Excel, or JSON with smart column mapping
• 🤖 AI Generation: OpenAI GPT-powered intelligent metadata generation
• ✏️ Manual Entry: Direct editing with real-time validation
• 📋 Templates: Reusable metadata templates with variables

Enterprise Features

• 🔐 Authentication: JWT tokens + Microsoft SSO support
• 💾 Persistent Sessions: Redis-backed sessions (no data loss on restart)
• 👥 User Management: SQLite database for users and audit logs
• 📊 Audit Logging: Track all user actions and metadata changes
• 🔍 AI Usage Tracking: Monitor OpenAI token usage and costs

File Support

• 300+ File Formats via ExifTool integration
• PDF Files: Full metadata support (title, subject, keywords, author, copyright)
• Images: JPEG, PNG, GIF, HEIC, TIFF, RAW formats
• Office Documents: Word, Excel, PowerPoint
• Video Files: MP4, MOV, AVI, MKV
• Unicode Support: Full support for Chinese, Japanese, Korean characters

Advanced Capabilities

• Smart Field Mapping: Auto-detect columns with fuzzy matching
• Batch Processing: Process multiple files with selective updates
• Custom Metadata Fields: Add unlimited custom fields
• Template Variables: {filename}, {date}, {user}, custom variables

---

🏗️ Architecture

Modern full-stack application:

┌─────────────────┐
│  React Frontend │  (Vite + TypeScript + Tailwind)
└────────┬────────┘
         │ API calls
┌────────▼────────┐
│  FastAPI Backend│  (Python 3.11 + Async)
└────────┬────────┘
         │
    ┌────┴────┬─────────┐
    │         │         │
┌───▼───┐ ┌──▼───┐ ┌───▼────┐
│ Redis │ │SQLite│ │Processors│
│Sessions│ │ DB   │ │(ExifTool)│
└────────┘ └──────┘ └─────────┘

Key Components:

• Frontend: React 18 + React Router + Zustand (state management)
• Backend: FastAPI + SQLAlchemy async + Pydantic
• Sessions: Redis with TTL (7 days user sessions, 1 hour file sessions)
• Auth: JWT tokens (access: 30min, refresh: 7 days)
• Processors: 100% reusable from v3.1 - no changes needed

Why FastAPI + React?

• ✅ No session loss - Redis persistent storage
• ✅ Better performance - Async operations
• ✅ Modern UI - React with proper state management
• ✅ API-first - Easy to extend and integrate
• ✅ Auto docs - Swagger UI at /docs

---

📦 Requirements

System Dependencies

• Docker & Docker Compose (required for deployment)
• Node.js 18+ & npm (for frontend build)
• ExifTool 12.15+ (installed in Docker container)
• Tesseract OCR (optional - for image text extraction)
• Poppler (optional - for PDF content extraction)

Python Dependencies

See backend/requirements.txt:

• FastAPI 0.109+
• Redis 5.0+
• SQLAlchemy 2.0+ (async)
• OpenAI 1.0+
• PyExifTool, Pillow, pypdf, python-docx, etc.

Frontend Dependencies

See frontend/package.json:

• React 18
• React Router 6
• Axios, Zustand, React Dropzone
• Tailwind CSS

---

🛠️ Installation

Option 1: Production Deployment (Recommended)

cd /opt
sudo git clone https://bitbucket.org/zlalani/solventum-image-metadata.git
cd solventum-image-metadata
sudo cp .env.production .env
sudo nano .env  # Configure secrets
sudo ./deploy.sh

See PRODUCTION-DEPLOY.md for complete guide.

Option 2: Local Development

# Backend
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

# Frontend (separate terminal)
cd frontend
npm install
npm run dev

# Redis (Docker)
docker run -d -p 6379:6379 redis:7-alpine

---

🔧 Configuration

Environment Variables

Required:

OPENAI_API_KEY=sk-proj-...                    # For AI metadata generation
AI_MODEL=gpt-5.2                              # AI model to use
SECRET_KEY=your-secret-key-here               # JWT signing key

Optional - Azure AD SSO:

AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
REDIRECT_URI=https://your-domain.com/callback

Optional - Advanced:

DATABASE_URL=sqlite+aiosqlite:///./data/oliver_metadata.db
REDIS_URL=redis://localhost:6379/0
BACKEND_PORT=5001
DEBUG=false

See .env.production for complete example.

---

📚 Documentation

• PRODUCTION-DEPLOY.md - Quick production deployment guide
• DEPLOYMENT.md - Detailed deployment documentation
• DEPLOYMENT-CHECKLIST.md - Pre-deployment checklist
• CLEANUP-COMMANDS.md - Server cleanup commands
• DOCKER.md - Docker configuration details
• CLAUDE.md - Developer guide for Claude Code

---

🚀 Usage

Web Interface

1. Access the application:

   • Production: https://your-domain.com/solventum-image-metadata/
   • Local: http://localhost:3000

2. Login:

   • Use local credentials or Microsoft SSO
   • Default test account: tester / oliveradmin (dev only)

3. Upload Files:

   • Drag & drop or click to upload
   • Supports multiple files at once

4. Choose Metadata Source:

   • AI Generation: GPT analyzes file content
   • Import from File: Upload CSV/Excel/JSON with metadata
   • Manual Entry: Fill in fields directly
   • Templates: Apply saved templates

5. Review & Edit:

   • Preview generated metadata
   • Edit any fields
   • Add custom fields

6. Download:

   • Download files with embedded metadata
   • Export metadata to CSV

API Endpoints

Interactive API docs: http://localhost:5001/docs

Authentication:

# Login
POST /auth/login
{"username": "user", "password": "pass"}
→ Returns: {access_token, refresh_token}

# Use token
Authorization: Bearer <access_token>

File Operations:

# Upload files
POST /files/upload
Content-Type: multipart/form-data

# Update metadata
POST /metadata/update
{"session_id": "...", "title": "...", "keywords": "..."}

# Download file
GET /files/download/{filename}

Templates:

# List templates
GET /templates/list

# Apply template
POST /templates/apply
{"template_name": "...", "files": [...]}

See /docs for complete API reference.

---

🔒 Security

• JWT Authentication: Secure token-based auth
• Password Hashing: bcrypt for password storage
• HTTPS Required: Use reverse proxy (Apache/Nginx) with SSL
• CORS Protection: Configured origins only
• Rate Limiting: Built-in API rate limiting
• Session Expiry: Automatic session cleanup
• Secrets Management: Environment variables only (never commit .env)

Best Practices:

1. ✅ Use strong SECRET_KEY (32+ characters)
2. ✅ Configure HTTPS in production
3. ✅ Set up firewall rules
4. ✅ Regular backups of database
5. ✅ Monitor logs for suspicious activity

---

🐳 Docker

Production: Uses docker-compose.fastapi.yml

# Start services
docker-compose -f docker-compose.fastapi.yml up -d

# View logs
docker-compose -f docker-compose.fastapi.yml logs -f

# Stop services
docker-compose -f docker-compose.fastapi.yml down

Services:

• backend: FastAPI application (port 5001 → 8000)
• redis: Session storage (internal only)

Volumes:

• backend/data: SQLite database
• backend/uploads: Uploaded files
• backend/output: Templates and reports

---

🔍 Troubleshooting

Common Issues

1. Backend health check fails

# Check logs
docker-compose -f docker-compose.fastapi.yml logs backend

# Common causes:
# - OPENAI_API_KEY not set
# - Redis not running
# - Port 5001 already in use

2. Frontend not loading

# Check files exist
ls -lh /var/www/html/solventum-image-metadata/

# Check permissions
sudo chown -R www-data:www-data /var/www/html/solventum-image-metadata/

3. Git pull fails during deployment

# First deployment: This is normal!
# The script will continue with existing code

# For updates: Set up git credentials
cd /opt/solventum-image-metadata
sudo git remote set-url origin https://username:token@bitbucket.org/...

4. Docker build fails

# Clean Docker and retry
sudo docker system prune -af
sudo ./deploy.sh

See CLEANUP-COMMANDS.md for more troubleshooting.

---

📝 Development

Project Structure

solventum-image-metadata/
├── backend/               # FastAPI backend
│   ├── app/
│   │   ├── api/          # API routes
│   │   ├── core/         # Auth, database, Redis
│   │   ├── models/       # SQLAlchemy models
│   │   └── processors/   # Metadata processors (reused from v3.1)
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/             # React frontend
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   └── store/       # Zustand state
│   ├── package.json
│   └── vite.config.ts
├── docker-compose.fastapi.yml
├── deploy.sh            # Production deployment script
└── README.md

Adding New Features

1. Backend API:

   • Add route in backend/app/api/
   • Use async/await for all operations
   • Add to backend/app/main.py router

2. Frontend Component:

   • Create in frontend/src/components/
   • Use Zustand for state
   • API calls via axios

3. New Processor:

   • Extend BaseExtractor or BaseUpdater
   • Add to backend/app/processors/
   • Register in main.py

---

📄 License

Corporate License - Oliver Marketing

This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.

© 2024-2026 Oliver Marketing. All rights reserved.

---

👨‍💻 Developer

Vadym Samoilenko Email: vadym.samoilenko@oliver.agency

---

🆘 Support

• Issues: Report at https://bitbucket.org/zlalani/solventum-image-metadata/issues
• Documentation: See /docs directory
• API Docs: http://localhost:5001/docs (when running)

---

🔄 Changelog

Version 4.0.1 (2026-02-12)

• 🐛 FIXED: Duplicate filename collisions when uploading the same file multiple times
• ⚡ IMPROVED: Per-session file isolation via subdirectories (no more cross-session overwrites)
• ⚡ IMPROVED: Within-session deduplication: re-uploading replaces the old entry without renaming
• ⚡ IMPROVED: Session ID generation now uses cryptographically secure tokens
• ⚡ IMPROVED: Auto-cleanup of ZIP archives after download
• ⚡ IMPROVED: Cleanup of old session directories and loose files

Version 4.0 (2026-02-09)

• ✨ NEW: FastAPI backend with async operations
• ✨ NEW: React frontend with modern UI
• ✨ NEW: Redis persistent sessions (no data loss)
• ✨ NEW: JWT authentication with refresh tokens
• ✨ NEW: Automatic deployment script
• ✨ NEW: Docker-based production deployment
• ⚡ IMPROVED: Better performance and scalability
• ⚡ IMPROVED: API-first architecture
• 🐛 FIXED: Session loss on restart
• 🐛 FIXED: Unicode filename handling

Version 3.1 (2026-01-26)

• Initial Flask-based version
• Multiple metadata sources
• AI generation support
• Microsoft SSO integration

---

🔮 Futures Log

Planned improvements and known areas for enhancement:

• Per-user upload isolation: Separate upload directories by user ID for multi-user deployments
• Automated tests: Add unit and integration test suite for upload, metadata lookup, and download flows
• WebSocket progress: Real-time upload and AI generation progress via WebSocket instead of polling
• Content-hash deduplication: Detect duplicate files across sessions by content hash
• Post-download session cleanup: Option to auto-delete session files after successful batch download
• Batch metadata editing: Apply the same metadata changes to multiple files at once from the UI

---

Made with ❤️ by Vadym Samoilenko