---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-18
name: Developer_Manual
status: active
tags:
- client/solventum
- tech/azure-ad
- tech/docker
- tech/flask
- tech/python
- tech/sqlite
- type/reference
type: reference
---

# Solventum Image Metadata Tool v3.1 — Developer Manual

## Architecture Overview

The application is a Flask-based web service designed for both local development and Dockerized production deployment.

- **Web Framework**: Flask (with Jinja2 templating).
- **Backend Logic**: Modular services in `src/` directory.
- **Data Persistence**: SQLite via a custom `src/database.py` wrapper.
- **Authentication**: Microsoft Azure AD SSO (MSAL) and local session-based auth.
- **File Handling**: ExifTool integration for reading/writing metadata across 300+ formats.
- **AI Integration**: Optional OpenAI API integration for metadata generation.
- **Deployment**: Docker Compose for production; `uvicorn`/Flask dev server for local dev.

## Tech Stack

- **Language**: Python 3.14 (required for pandas compatibility, see `venv_local/lib/python3.14/site-packages/pandas/pyproject.toml`).
- **Web Server**: Flask (dev via `run.py`), Uvicorn (if ASGI needed, though currently Flask/Werkzeug).
- **Database**: SQLite (`oliver_metadata.db`, `oliver_sessions.db`).
- **External Tools**: ExifTool, Tesseract OCR (optional), Poppler (optional).
- **Dependencies**: pandas, numpy>=2.3.3 (for Python 3.14), MSAL, Pydantic-Settings, SlowAPI (rate limiting).

## Local Setup

### Prerequisites
1. Python 3.14+.
2. ExifTool installed on the system.
3. (Optional) Tesseract and Poppler for full OCR/PDF support.

### Steps
1. **Clone and Install**:
   ```bash
   git clone <repository_url>
   cd solventum-image-metadata
   python -m venv venv
   source venv/bin/activate # or venv\Scripts\activate on Windows
   pip install -r requirements.txt
   ```

2. **Environment Variables**:
   - Copy `.env.example` to `.env`.
   - Fill in `SECRET_KEY`, `AZURE_CLIENT_SECRET`, and other required fields.
   - Set `DOCKER_MODE=false` for local dev.

3. **Run**:
   ```bash
   python run.py
   ```
   The app will start at `http://127.0.0.1:5001`.

## Environment Variables

Key variables from `.env`:

- `SECRET_KEY`: Flask session secret. Generate with `secrets.token_hex(32)`.
- `DOCKER_MODE`: `true`/`false`. Determines path structures (e.g., `/app/uploads` vs local).
- `ROOT_PATH`: Subpath prefix for reverse proxy (e.g., `/solventum-image-metadata`).
- `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`: Azure AD SSO config.
- `REDIRECT_URI`: Must match Azure AD App Registration exactly. For local: `http://localhost:5001/auth/callback`.
- `SUPERADMIN_EMAIL`: Auto-created admin email.
- `OPENAI_API_KEY`: For AI metadata generation.
- `ENABLE_TEST_USER`: `true` to enable local test user login.
- `HTTPS_ONLY`: `true` in production to enforce HTTPS.

## Key Services & Entry Points

- `app/main.py`: Entry point for the Flask app. Initializes blueprints and middleware.
- `app/config.py`: `Settings` class using Pydantic-Settings for config management.
- `src/auth.py`: Handles authentication logic (MSAL flow, session creation, login_required decorator).
- `src/file_detector.py`: Detects file type and routes to appropriate extractor.
- `src/extractors/`: Contains `PDFExtractor`, `ImageExtractor`, `OfficeExtractor`, `VideoExtractor`.
- `src/updaters/`: Contains `PDFUpdater`, `ImageUpdater`, etc., for writing metadata.
- `src/metadata_importer.py`: Handles CSV/Excel import and column mapping.
- `web_app.py`: Contains Flask routes and controllers (if used as direct entry). Note: `run.py` imports `app.main:app`.

## API Reference

The tool provides a web UI. However, some internal JSON APIs are exposed for the frontend:

- `POST /auth/callback`: Azure AD SSO callback.
- `POST /api/import`: Process Excel/CSV import.
- `POST /api/ai/generate`: Trigger AI metadata generation.
- `GET /api/files`: List files.
- `GET /api/files/<id>`: Get file details.
- `PUT /api/files/<id>/metadata`: Update metadata.

*Note: Refer to `web_app.py` for exact route definitions and request/response schemas.*

## Deployment

### Docker
1. Ensure Docker and Docker Compose are installed.
2. Configure `.env` with production values.
3. Run:
   ```bash
   docker-compose up -d
   ```
4. The app will be available at `http://127.0.0.1:5001` (if exposed locally) or via the reverse proxy at `ROOT_PATH`.

### Volumes
- `uploads`: Persistent file uploads.
- `database`: Persistent SQLite databases.
- `output`: Persistent output/backups.

### Reverse Proxy
- Configure Apache/Nginx to proxy `/solventum-image-metadata` to the container port 5001.
- Ensure `ROOT_PATH` in `.env` matches the proxy subpath.

## Known Gotchas

1. **Python 3.14 Requirement**: The pandas dependency in `venv_local/lib/python3.14/site-packages/pandas/pyproject.toml` explicitly requires `numpy>=2.3.3` for Python 3.14. Ensure you are using Python 3.14+ to avoid compatibility issues.
2. **ExifTool Path**: ExifTool must be in the system PATH. In Docker, ensure the ExifTool binary is installed in the container or mounted.
3. **Azure Redirect URI**: Must match exactly, including `/auth/callback`. Case sensitivity applies.
4. **File Locking**: On Windows, ensure files are not locked by other processes before updating metadata.
5. **Database Path**: In Docker mode, DB paths are hardcoded to `/app/data/`. Ensure volume mounts align.
6. **Rate Limiting**: SlowAPI is used. Ensure `app/security.py` is properly integrated in `app/main.py` to avoid bypassing rate limits.
7. **Unicode Filenames**: The `safe_filename` function in `web_app.py` normalizes Unicode. Ensure ExifTool supports UTF-8 input (usually does with modern versions).

## Related
- [[01 Projects/olivas/DEVELOPER_MANUAL.md]]