diff --git a/Migration-Workflow.md b/Migration-Workflow.md
new file mode 100644
index 0000000..84a9917
--- /dev/null
+++ b/Migration-Workflow.md
@@ -0,0 +1,153 @@
+# Migration Service
+
+The Romexis Migration Service helps migrate an existing Romexis installation into the Docker-based Romexis Server stack.
+
+It provides:
+
+- Flask Web UI
+- REST API
+- temporary SFTP users
+- migration job state tracking
+- database backup upload
+- manifest creation
+- upload validation
+- restore orchestration
+- final completion/cancellation workflow
+
+---
+
+## Why a Migration Service?
+
+Romexis installations can contain:
+
+- large SQL Server backups
+- large image directories
+- ergo data directories
+- cache directories
+- many small files
+
+Browser uploads alone are not ideal for this. Therefore the migration service combines:
+
+```text
+Web UI / API
+  for orchestration and state
+
+SFTP
+  for large file and directory transfer
+```
+
+---
+
+## Migration Job State
+
+Migration jobs are stored as JSON state files.
+
+Typical workflow:
+
+```text
+created
+  -> database_uploaded
+  -> database_restored
+  -> upload_complete
+  -> validated
+  -> restored
+  -> completed
+```
+
+Final states:
+
+```text
+completed
+cancelled
+failed
+```
+
+---
+
+## SFTP User Lifecycle
+
+The service creates one temporary SFTP user per active migration.
+
+Important behavior:
+
+- active jobs recreate SFTP users on service startup
+- completed jobs should not recreate SFTP users
+- cancelled jobs should not recreate SFTP users
+- failed jobs should not recreate SFTP users unless intentionally reactivated
+- completing or cancelling a job removes or disables the temporary SFTP access
+
+---
+
+## Manual Browser Workflow
+
+1. Create migration job in the Web UI.
+2. Upload database backup through the browser.
+3. The service creates `manifest.json` automatically.
+4. Trigger database restore.
+5. Upload file directories through SFTP.
+6. Mark upload as complete.
+7. Validate upload.
+8. Run restore.
+9. Complete migration and remove SFTP access.
+
+---
+
+## SFTP Upload
+
+The Web UI shows the SFTP credentials and example commands.
+
+Typical rclone setup:
+
+```bash
+rclone config create romexis-migration sftp \
+  host <host> \
+  port <port> \
+  user <username> \
+  pass "$(rclone obscure '<password>')"
+```
+
+Upload images:
+
+```bash
+rclone sync "/PATH/TO/LOCAL/romexis_images" \
+  "romexis-migration:/romexis_images" \
+  --progress \
+  --transfers 4 \
+  --checkers 8
+```
+
+Upload ergo data:
+
+```bash
+rclone sync "/PATH/TO/LOCAL/romexis_ergodata" \
+  "romexis-migration:/romexis_ergodata" \
+  --progress \
+  --transfers 4 \
+  --checkers 8
+```
+
+Optional cache upload:
+
+```bash
+rclone sync "/PATH/TO/LOCAL/romexis_cache" \
+  "romexis-migration:/romexis_cache" \
+  --progress \
+  --transfers 4 \
+  --checkers 8
+```
+
+---
+
+## Restart Coordination
+
+The migration service and Romexis container coordinate restarts using a shared state file:
+
+```text
+/data/romexis_images/.romexis_restart_state
+```
+
+The migration service writes a pending restart request.
+
+The Romexis entrypoint/process observes the state, restarts the Romexis service and writes the result.
+
+The migration service reads the result and removes the state file.