# File Manager Base Image Flow

This document explains upload + create flow specifically for base images.

## Purpose

This flow uploads base images and persists file metadata into a forced folder hierarchy:

- `__system_root_files__ > bases > <base-type> > <base-name>`

Main differences compared to regular file flow:

- dedicated upload endpoint: `POST /api/v1/file-manager/files/upload-base-image`
- dedicated create endpoint: `POST /api/v1/file-manager/files/create-base-image`
- `content_type` must be `image/*`
- `base_uuid` is required in the create request per item
- create step performs hard replace of existing files in target folder before creating new file

## Step 1 - Request Upload Intent (Base)

Endpoint:

- `POST /api/v1/file-manager/files/upload-base-image`

Validation highlights:

- `type` must be `file_manager_file_upload_intent`
- `name` required
- `content_type` required and must start with `image/`
- `size_bytes >= 0`

## Step 2 - Upload Binary to Object Storage

For each successful intent, frontend uploads binary with `PUT` to `upload_url`.

## Step 3 - Create File Record (Base)

Endpoint:

- `POST /api/v1/file-manager/files/create-base-image`

Validation highlights:

- `type` must be `file_manager_file_create` or `file_manager_file`
- `upload_intent_uuid` required and valid UUID
- `base_uuid` required and valid UUID
- `name` required

Backend behavior:

1. load base from `base_uuid`
2. resolve `base-type` from base category (e.g. `hems` or `regular`)
3. resolve/create folder path `__system_root_files__ > bases > <base-type> > <base-name>`
4. hard replace: delete + purge all existing files in that target folder
5. create file node from upload intent

Hard replace cleanup target:

- file row in DB
- original object in S3
- thumbnail object in S3 (if exists)
- related attachment metadata