diff --git a/extensions/saas/sources/api/src/main/java/tools/dynamia/modules/saas/api/AccountExportIgnore.java b/extensions/saas/sources/api/src/main/java/tools/dynamia/modules/saas/api/AccountExportIgnore.java
new file mode 100644
index 00000000..d2988a03
--- /dev/null
+++ b/extensions/saas/sources/api/src/main/java/tools/dynamia/modules/saas/api/AccountExportIgnore.java
@@ -0,0 +1,52 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package tools.dynamia.modules.saas.api;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a JPA {@code @Entity} class to be completely excluded from the Tenant Mobility
+ * export/import/clone pipeline.
+ *
+ *
Apply this annotation to entities that contain ephemeral, audit, cache or metric data
+ * that should never travel with a tenant:
+ *
+ *
Entities annotated with {@code @AccountExportIgnore} are silently skipped during
+ * discovery, so they will never appear in an export file and will never be processed
+ * on import.
+ *
+ * @author Mario Serrano Leones
+ * @see ExportIgnore
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface AccountExportIgnore {
+}
+
diff --git a/extensions/saas/sources/api/src/main/java/tools/dynamia/modules/saas/api/ExportIgnore.java b/extensions/saas/sources/api/src/main/java/tools/dynamia/modules/saas/api/ExportIgnore.java
new file mode 100644
index 00000000..a143dc1d
--- /dev/null
+++ b/extensions/saas/sources/api/src/main/java/tools/dynamia/modules/saas/api/ExportIgnore.java
@@ -0,0 +1,57 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package tools.dynamia.modules.saas.api;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a specific field in a JPA entity to be excluded from Tenant Mobility
+ * serialization during export.
+ *
+ *
Use this for fields that are computed, cached, or otherwise should not be
+ * persisted to a different environment:
+ *
+ *
Each method creates a {@link AccountMigrationJob} record, launches the operation
+ * as a background virtual thread via {@code SchedulerUtil.runWithResult()}, and returns
+ * the job DTO immediately (non-blocking).
+ *
+ *
+ *
+ * @author Mario Serrano Leones
+ */
+public interface AccountMigrationJobService {
+
+ /**
+ * Starts an async export job for the given account.
+ *
+ * @param accountId ID of the account to export
+ * @param options export configuration
+ * @return the newly created (PENDING) job
+ */
+ AccountMigrationJobDto createExportJob(Long accountId, AccountExportOptions options);
+
+ /**
+ * Starts an async import job from an uploaded file.
+ *
+ * @param file multipart upload containing the export JSON (or .json.gz)
+ * @param options import configuration (target account, identity strategy, etc.)
+ * @return the newly created (PENDING) job
+ */
+ AccountMigrationJobDto createImportJob(MultipartFile file, AccountImportOptions options);
+
+ /**
+ * Starts an async clone job (source tenant → target tenant, same system).
+ *
+ * @param options clone configuration
+ * @return the newly created (PENDING) job
+ */
+ AccountMigrationJobDto createCloneJob(AccountCloneOptions options);
+
+ /**
+ * Starts an async backup job (semantically equivalent to export with BACKUP type label).
+ *
+ * @param accountId ID of the account to back up
+ * @return the newly created (PENDING) job
+ */
+ AccountMigrationJobDto createBackupJob(Long accountId);
+
+ /**
+ * Starts an async restore job from an uploaded file
+ * (semantically equivalent to import with RESTORE type label).
+ *
+ * @param accountId target account to restore into
+ * @param file multipart upload
+ * @return the newly created (PENDING) job
+ */
+ AccountMigrationJobDto createRestoreJob(Long accountId, MultipartFile file);
+
+ /**
+ * Returns the current state of the job identified by {@code jobUuid}.
+ *
+ * @param jobUuid UUID of the job
+ * @return job DTO or {@code null} if not found
+ */
+ AccountMigrationJobDto getJob(String jobUuid);
+
+ /**
+ * Returns the raw {@link AccountMigrationJob} entity for internal use (e.g. file download).
+ *
+ * @param jobUuid UUID of the job
+ * @return entity or {@code null}
+ */
+ AccountMigrationJob getJobEntity(String jobUuid);
+
+ /**
+ * Lists all known jobs, optionally filtered by account.
+ *
+ * @param accountId filter by account; pass {@code null} to return all jobs
+ * @return list of jobs ordered by creation date descending
+ */
+ List listJobs(Long accountId);
+
+ /**
+ * Requests cooperative cancellation of a running job.
+ *
+ * The pipeline will stop at the next chunk boundary. If the job is already
+ * finished (COMPLETED/FAILED/CANCELLED), this is a no-op.
+ *
+ * @param jobUuid UUID of the job to cancel
+ */
+ void cancelJob(String jobUuid);
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/AccountMigrationService.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/AccountMigrationService.java
new file mode 100644
index 00000000..8384e1e9
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/AccountMigrationService.java
@@ -0,0 +1,75 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.api;
+
+import java.io.InputStream;
+import java.io.OutputStream;
+
+/**
+ * High-level service for executing tenant mobility operations synchronously.
+ *
+ *
This service is designed to be called from within a worker/job that is already
+ * running in a background virtual thread. For async job management see
+ * {@link AccountMigrationJobService}.
+ *
+ *
{@code
+ * // Direct usage (synchronous — blocks until complete):
+ * mobilityService.exportTenant(42L, outputStream, new TenantExportOptions(), listener, token);
+ *
+ * // Preferred usage (async via job service):
+ * jobService.createExportJob(42L, new TenantExportOptions());
+ * }
+ *
+ * @author Mario Serrano Leones
+ */
+public interface AccountMigrationService {
+
+ /**
+ * Exports all tenant data for {@code accountId} to the given {@code output} stream.
+ *
+ * @param accountId account whose data will be exported
+ * @param output destination stream (may be wrapped in GZIP by the pipeline if configured)
+ * @param options export configuration
+ * @param listener optional progress callback; may be {@code null}
+ * @param token optional cancellation token; may be {@code null}
+ */
+ void exportTenant(Long accountId,
+ OutputStream output,
+ AccountExportOptions options,
+ MigrationProgressListener listener,
+ CancellationToken token);
+
+ /**
+ * Imports tenant data from an exported {@code input} stream.
+ *
+ * @param input source stream (GZIP-encoded or plain JSON)
+ * @param options import configuration, including target account and identity strategy
+ * @param listener optional progress callback; may be {@code null}
+ * @param token optional cancellation token; may be {@code null}
+ */
+ void importTenant(InputStream input,
+ AccountImportOptions options,
+ MigrationProgressListener listener,
+ CancellationToken token);
+
+ /**
+ * Clones a tenant within the same system by exporting to an in-memory buffer
+ * and immediately importing to the target account.
+ *
+ * @param options clone configuration (source/target accounts, identity strategy, etc.)
+ * @param listener optional progress callback; may be {@code null}
+ * @param token optional cancellation token; may be {@code null}
+ */
+ void cloneTenant(AccountCloneOptions options,
+ MigrationProgressListener listener,
+ CancellationToken token);
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/CancellationToken.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/CancellationToken.java
new file mode 100644
index 00000000..9abfb04b
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/CancellationToken.java
@@ -0,0 +1,67 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.api;
+
+import java.util.concurrent.atomic.AtomicBoolean;
+
+/**
+ * Cooperative cancellation signal for long-running migration pipelines.
+ *
+ *
The pipeline checks {@link #isCancelled()} between processing chunks.
+ * When cancellation is requested, the pipeline exits cleanly at the next checkpoint.
+ *
+ *
{@code
+ * CancellationToken token = new CancellationToken();
+ * // Pass to pipeline; later, from another thread:
+ * token.cancel();
+ * }
+ *
+ * @author Mario Serrano Leones
+ */
+public class CancellationToken {
+
+ private final AtomicBoolean cancelled = new AtomicBoolean(false);
+ private volatile String reason;
+
+ /** Signals the pipeline to stop at the next checkpoint. */
+ public void cancel() {
+ cancel("Cancelled by user");
+ }
+
+ /**
+ * Signals cancellation with a reason message.
+ *
+ * @param reason human-readable reason for cancellation
+ */
+ public void cancel(String reason) {
+ this.reason = reason;
+ this.cancelled.set(true);
+ }
+
+ /**
+ * Returns {@code true} if cancellation has been requested.
+ * Pipelines should check this between chunks and exit gracefully.
+ */
+ public boolean isCancelled() {
+ return cancelled.get();
+ }
+
+ /** Returns the cancellation reason, or {@code null} if not cancelled. */
+ public String getReason() {
+ return reason;
+ }
+
+ /** Factory method for convenience. */
+ public static CancellationToken active() {
+ return new CancellationToken();
+ }
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/IdentityMapper.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/IdentityMapper.java
new file mode 100644
index 00000000..e0a4916c
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/IdentityMapper.java
@@ -0,0 +1,52 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.api;
+
+import java.util.Map;
+
+/**
+ * SPI for controlling how entity primary keys are handled during import.
+ *
+ *
The default implementation is {@link tools.dynamia.modules.saas.migration.identity.RegenerateIdsIdentityMapper}
+ * which assigns new JPA-generated IDs and resolves internal references via an
+ * {@code idMappings} table ({@code entityClass.name → {originalId → newId}}).
+ *
+ *
Implement and register this interface as a Spring bean to override the default behaviour.
+ *
+ * @author Mario Serrano Leones
+ */
+public interface IdentityMapper {
+
+ /**
+ * Determines the ID to use when persisting an imported entity.
+ *
+ * @param originalId the ID read from the export file; may be null
+ * @param entityClass the JPA entity class being imported
+ * @return the ID to assign before persisting, or {@code null} to let JPA auto-generate
+ */
+ Object mapId(Object originalId, Class entityClass);
+
+ /**
+ * Resolves a foreign-key reference ID from the export file to the correct ID
+ * in the target database, using the running ID mapping table.
+ *
+ * @param originalRefId the reference ID read from the export ({@code fieldName_ref_id})
+ * @param refClass the referenced entity class
+ * @param idMappings mutable map of {@code className → {originalId → newId}}; updated during import
+ * @return the actual ID to use when creating the JPA reference proxy
+ */
+ Object resolveReferenceId(Object originalRefId, Class refClass,
+ Map> idMappings);
+
+ /** Returns the strategy implemented by this mapper. */
+ IdentityStrategy getStrategy();
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/IdentityStrategy.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/IdentityStrategy.java
new file mode 100644
index 00000000..3f8f58c7
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/IdentityStrategy.java
@@ -0,0 +1,45 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.api;
+
+/**
+ * Controls how entity primary keys are handled during import.
+ *
+ * @author Mario Serrano Leones
+ */
+public enum IdentityStrategy {
+
+ /**
+ * Preserve original database IDs.
+ *
+ * The imported entities will have the same primary keys as the source system.
+ * This is safe when restoring to an empty target database.
+ * It may cause constraint violations if the target DB already contains data.
+ */
+ KEEP_IDS,
+
+ /**
+ * Auto-generate new IDs for all imported entities.
+ *
+ * JPA auto-generation is used for each entity. Foreign-key references are
+ * resolved via the internal ID mapping table ({@code originalId → newId}).
+ * This is the recommended strategy for cloning within the same database.
+ */
+ REGENERATE_IDS,
+
+ /**
+ * Assign UUIDv7 values as new IDs.
+ *
+ * Planned for v3.
+ */
+ UUID7
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/MigrationException.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/MigrationException.java
new file mode 100644
index 00000000..ab26c2de
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/MigrationException.java
@@ -0,0 +1,32 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.api;
+
+/**
+ * Unchecked exception thrown when a migration pipeline encounters an unrecoverable error.
+ *
+ * @author Mario Serrano Leones
+ */
+public class MigrationException extends RuntimeException {
+
+ public MigrationException(String message) {
+ super(message);
+ }
+
+ public MigrationException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ public MigrationException(Throwable cause) {
+ super(cause);
+ }
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/MigrationProgress.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/MigrationProgress.java
new file mode 100644
index 00000000..05a05ce3
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/MigrationProgress.java
@@ -0,0 +1,37 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.api;
+
+/**
+ * Carries progress information during a tenant migration operation.
+ *
+ * @param processedRecords Total records processed so far.
+ * @param totalRecords Total records expected (0 if unknown).
+ * @param message Human-readable description of the current step.
+ * @author Mario Serrano Leones
+ */
+public record MigrationProgress(long processedRecords, long totalRecords, String message) {
+
+ /** Returns the progress as a percentage (0–100), or -1 if total is unknown. */
+ public int percentage() {
+ if (totalRecords <= 0) return -1;
+ return (int) Math.min(100, (processedRecords * 100L) / totalRecords);
+ }
+
+ @Override
+ public String toString() {
+ if (totalRecords > 0) {
+ return "[%d%%] %s (%d / %d)".formatted(percentage(), message, processedRecords, totalRecords);
+ }
+ return "[?] %s (%d processed)".formatted(message, processedRecords);
+ }
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/MigrationProgressListener.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/MigrationProgressListener.java
new file mode 100644
index 00000000..a8b090ee
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/api/MigrationProgressListener.java
@@ -0,0 +1,31 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.api;
+
+/**
+ * SPI callback for receiving progress updates during a migration pipeline execution.
+ *
+ *
Implementations are typically provided by the job service to persist progress
+ * in the {@code TenantMobilityJob} entity.
+ *
+ * @author Mario Serrano Leones
+ */
+@FunctionalInterface
+public interface MigrationProgressListener {
+
+ /**
+ * Called by the pipeline whenever significant progress has been made.
+ *
+ * @param progress current progress snapshot
+ */
+ void onProgress(MigrationProgress progress);
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/config/AccountMigrationConfig.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/config/AccountMigrationConfig.java
new file mode 100644
index 00000000..ac6c39a5
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/config/AccountMigrationConfig.java
@@ -0,0 +1,89 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.config;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import tools.jackson.databind.DeserializationFeature;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.SerializationFeature;
+import tools.jackson.databind.json.JsonMapper;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+/**
+ * Spring Boot auto-configuration for the Tenant Mobility module.
+ *
+ *
Registers:
+ *
+ *
A migration-specific {@link ObjectMapper} (qualified name: {@code migrationObjectMapper}).
+ *
The default {@link tools.dynamia.modules.saas.migration.api.AccountMigrationService} implementation.
+ *
Ensures the output directory exists at startup.
+ *
+ *
+ * @author Mario Serrano Leones
+ */
+@Configuration
+@EnableConfigurationProperties(AccountMigrationProperties.class)
+public class AccountMigrationConfig {
+
+ private final AccountMigrationProperties properties;
+
+ public AccountMigrationConfig(AccountMigrationProperties properties) {
+ this.properties = properties;
+ initOutputDirectory();
+ }
+
+ /**
+ * Dedicated Jackson {@link ObjectMapper} for the migration pipelines.
+ *
+ *
Configured to:
+ *
+ *
Java time types supported natively (Jackson 3 built-in, no module needed).
+ *
Not fail on unknown properties during import.
+ *
Not fail on empty beans.
+ *
Exclude null values from output (smaller files).
+ *
+ *
+ *
This bean is named {@code migrationObjectMapper} so it does not conflict
+ * with any other {@code ObjectMapper} in the application context.
+ */
+ @Bean("migrationObjectMapper")
+ @ConditionalOnMissingBean(name = "migrationObjectMapper")
+ public ObjectMapper migrationObjectMapper() {
+ return JsonMapper.builder()
+ .disable(SerializationFeature.FAIL_ON_EMPTY_BEANS)
+ .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
+ .changeDefaultPropertyInclusion(
+ i -> i.withValueInclusion(JsonInclude.Include.NON_NULL))
+ .build();
+ }
+
+ private void initOutputDirectory() {
+ try {
+ Path dir = Path.of(properties.getOutputDirectory());
+ if (!Files.exists(dir)) {
+ Files.createDirectories(dir);
+ }
+ } catch (IOException e) {
+ throw new RuntimeException(
+ "Cannot create migration output directory: " + properties.getOutputDirectory(), e);
+ }
+ }
+}
+
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/config/AccountMigrationProperties.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/config/AccountMigrationProperties.java
new file mode 100644
index 00000000..43334185
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/config/AccountMigrationProperties.java
@@ -0,0 +1,102 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+/**
+ * Configuration properties for the Tenant Mobility module.
+ *
+ *
All properties are prefixed with {@code dynamia.saas.migration}.
+ *
+ *
+ *
+ * @author Mario Serrano Leones
+ */
+@ConfigurationProperties(prefix = "dynamia.saas.migration")
+public class AccountMigrationProperties {
+
+ /** Number of records read/written per pagination page. Default: 500. */
+ private int chunkSize = 500;
+
+ /**
+ * Directory where export/backup files are stored.
+ * Defaults to {@code ${java.io.tmpdir}/saas-migration}.
+ */
+ private String outputDirectory = System.getProperty("java.io.tmpdir") + "/saas-migration";
+
+ /** Whether to compress output files with GZIP by default. Default: {@code false}. */
+ private boolean compressionEnabled = false;
+
+ /**
+ * Maximum number of jobs that can be in RUNNING state simultaneously.
+ * Additional jobs remain in PENDING and are started as running jobs finish.
+ * Default: 5.
+ */
+ private int maxConcurrentJobs = 5;
+
+ /**
+ * If {@code true}, the import pipeline stops immediately when any entity
+ * fails to persist. If {@code false}, errors are logged and the import
+ * continues. Default: {@code false}.
+ */
+ private boolean failOnEntityError = false;
+
+ // ─── Accessors ─────────────────────────────────────────────────────────────
+
+ public int getChunkSize() {
+ return chunkSize;
+ }
+
+ public void setChunkSize(int chunkSize) {
+ this.chunkSize = chunkSize;
+ }
+
+ public String getOutputDirectory() {
+ return outputDirectory;
+ }
+
+ public void setOutputDirectory(String outputDirectory) {
+ this.outputDirectory = outputDirectory;
+ }
+
+ public boolean isCompressionEnabled() {
+ return compressionEnabled;
+ }
+
+ public void setCompressionEnabled(boolean compressionEnabled) {
+ this.compressionEnabled = compressionEnabled;
+ }
+
+ public int getMaxConcurrentJobs() {
+ return maxConcurrentJobs;
+ }
+
+ public void setMaxConcurrentJobs(int maxConcurrentJobs) {
+ this.maxConcurrentJobs = maxConcurrentJobs;
+ }
+
+ public boolean isFailOnEntityError() {
+ return failOnEntityError;
+ }
+
+ public void setFailOnEntityError(boolean failOnEntityError) {
+ this.failOnEntityError = failOnEntityError;
+ }
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/controllers/AccountMigrationRestController.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/controllers/AccountMigrationRestController.java
new file mode 100644
index 00000000..5c957164
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/controllers/AccountMigrationRestController.java
@@ -0,0 +1,250 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.controllers;
+
+import org.springframework.core.io.FileSystemResource;
+import org.springframework.core.io.Resource;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.multipart.MultipartFile;
+import tools.dynamia.modules.saas.migration.api.AccountCloneOptions;
+import tools.dynamia.modules.saas.migration.api.AccountExportOptions;
+import tools.dynamia.modules.saas.migration.api.AccountImportOptions;
+import tools.dynamia.modules.saas.migration.api.AccountMigrationJobDto;
+import tools.dynamia.modules.saas.migration.api.AccountMigrationJobService;
+import tools.dynamia.modules.saas.migration.domain.AccountMigrationJob;
+
+import java.io.File;
+import java.nio.file.Paths;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * REST API for the Tenant Mobility module.
+ *
+ *
Endpoints
+ *
+ * POST /api/saas/migration/jobs/export/{accountId} → start export job
+ * POST /api/saas/migration/jobs/import → start import job (multipart)
+ * POST /api/saas/migration/jobs/clone → start clone job
+ * POST /api/saas/migration/jobs/backup/{accountId} → start backup job
+ * POST /api/saas/migration/jobs/restore/{accountId} → start restore job (multipart)
+ * GET /api/saas/migration/jobs → list all jobs
+ * GET /api/saas/migration/jobs/{jobId} → get job status
+ * POST /api/saas/migration/jobs/{jobId}/cancel → cancel a running job
+ * GET /api/saas/migration/jobs/{jobId}/download → download result file
+ *
+ *
+ *
Note: Authorization is NOT enforced by this controller — the host
+ * application is responsible for securing these endpoints (e.g., via Spring Security,
+ * admin role checks, or API key filtering). These endpoints deal with raw tenant data
+ * and should be restricted to system administrators only.
+ *
+ * @author Mario Serrano Leones
+ */
+@RestController
+@RequestMapping(value = "/api/saas/migration", produces = MediaType.APPLICATION_JSON_VALUE)
+public class AccountMigrationRestController {
+
+ private final AccountMigrationJobService jobService;
+
+ public AccountMigrationRestController(AccountMigrationJobService jobService) {
+ this.jobService = jobService;
+ }
+
+ // ─────────────────────────────────────────────────────────────────────────
+ // Export
+ // ─────────────────────────────────────────────────────────────────────────
+
+ /**
+ * Start an export job for the specified account.
+ *
+ *
+ */
+ @PostMapping("/jobs/clone")
+ public ResponseEntity startClone(
+ @RequestBody AccountCloneOptions options) {
+
+ if (options.getSourceAccountId() == null || options.getTargetAccountId() == null) {
+ return ResponseEntity.badRequest().build();
+ }
+ AccountMigrationJobDto job = jobService.createCloneJob(options);
+ return ResponseEntity.status(HttpStatus.ACCEPTED).body(job);
+ }
+
+ // ─────────────────────────────────────────────────────────────────────────
+ // Backup / Restore
+ // ─────────────────────────────────────────────────────────────────────────
+
+ /** Start a backup job (export with BACKUP type label and compression). */
+ @PostMapping("/jobs/backup/{accountId}")
+ public ResponseEntity startBackup(@PathVariable Long accountId) {
+ AccountMigrationJobDto job = jobService.createBackupJob(accountId);
+ return ResponseEntity.status(HttpStatus.ACCEPTED).body(job);
+ }
+
+ /** Start a restore job from an uploaded export file. */
+ @PostMapping(value = "/jobs/restore/{accountId}", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+ public ResponseEntity startRestore(
+ @PathVariable Long accountId,
+ @RequestParam("file") MultipartFile file) {
+
+ AccountMigrationJobDto job = jobService.createRestoreJob(accountId, file);
+ return ResponseEntity.status(HttpStatus.ACCEPTED).body(job);
+ }
+
+ // ─────────────────────────────────────────────────────────────────────────
+ // Job management
+ // ─────────────────────────────────────────────────────────────────────────
+
+ /**
+ * List all jobs. Pass {@code ?accountId=X} to filter by account.
+ */
+ @GetMapping("/jobs")
+ public ResponseEntity> listJobs(
+ @RequestParam(required = false) Long accountId) {
+ return ResponseEntity.ok(jobService.listJobs(accountId));
+ }
+
+ /** Get the current status of a job by its UUID. */
+ @GetMapping("/jobs/{jobId}")
+ public ResponseEntity getJob(@PathVariable String jobId) {
+ AccountMigrationJobDto job = jobService.getJob(jobId);
+ if (job == null) return ResponseEntity.notFound().build();
+ return ResponseEntity.ok(job);
+ }
+
+ /** Request cancellation of a running job. Idempotent. */
+ @PostMapping("/jobs/{jobId}/cancel")
+ public ResponseEntity> cancelJob(@PathVariable String jobId) {
+ AccountMigrationJobDto job = jobService.getJob(jobId);
+ if (job == null) return ResponseEntity.notFound().build();
+ jobService.cancelJob(jobId);
+ return ResponseEntity.ok(Map.of("message", "Cancellation requested for job " + jobId));
+ }
+
+ // ─────────────────────────────────────────────────────────────────────────
+ // File download
+ // ─────────────────────────────────────────────────────────────────────────
+
+ /**
+ * Download the result file of a completed EXPORT or BACKUP job.
+ * Returns 404 if the job is not found, not completed, or has no result file.
+ */
+ @GetMapping("/jobs/{jobId}/download")
+ public ResponseEntity downloadResult(@PathVariable String jobId) {
+ AccountMigrationJob job = jobService.getJobEntity(jobId);
+ if (job == null || job.getResultPath() == null) {
+ return ResponseEntity.notFound().build();
+ }
+
+ File resultFile = Paths.get(job.getResultPath()).toFile();
+ if (!resultFile.exists()) {
+ return ResponseEntity.notFound().build();
+ }
+
+ String contentType = job.getResultPath().endsWith(".gz")
+ ? "application/gzip"
+ : "application/json";
+
+ String filename = resultFile.getName();
+
+ return ResponseEntity.ok()
+ .contentType(MediaType.parseMediaType(contentType))
+ .header(HttpHeaders.CONTENT_DISPOSITION,
+ "attachment; filename=\"" + filename + "\"")
+ .header(HttpHeaders.CONTENT_LENGTH, String.valueOf(resultFile.length()))
+ .body(new FileSystemResource(resultFile));
+ }
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/discovery/AccountEntityDiscovery.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/discovery/AccountEntityDiscovery.java
new file mode 100644
index 00000000..42a36af2
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/discovery/AccountEntityDiscovery.java
@@ -0,0 +1,91 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.discovery;
+
+import jakarta.persistence.EntityManagerFactory;
+import jakarta.persistence.metamodel.EntityType;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import tools.dynamia.integration.sterotypes.Service;
+import tools.dynamia.modules.saas.api.AccountAware;
+import tools.dynamia.modules.saas.api.AccountExportIgnore;
+import tools.dynamia.modules.saas.domain.Account;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * Discovers all JPA entity classes that participate in the Tenant Mobility export/import.
+ *
+ *
Discovery algorithm
+ *
+ *
Retrieves all managed entity types from {@link EntityManagerFactory#getMetamodel()}.
+ *
Filters to classes that implement {@link AccountAware}.
+ *
Excludes classes annotated with {@link AccountExportIgnore}.
+ *
Always includes {@link Account} (the tenant root), regardless of the above filters.
+ *
+ *
+ * @author Mario Serrano Leones
+ */
+@Service
+public class AccountEntityDiscovery {
+
+ private static final Logger log = LoggerFactory.getLogger(AccountEntityDiscovery.class);
+
+ private final EntityManagerFactory emf;
+
+ public AccountEntityDiscovery(EntityManagerFactory emf) {
+ this.emf = emf;
+ }
+
+ /**
+ * Returns the list of entity classes that should be included in the export.
+ * The list is not sorted; call
+ * {@link tools.dynamia.modules.saas.migration.graph.EntityDependencyGraph#topologicalSort(List)}
+ * to obtain the correct import order.
+ */
+ public List> discoverExportableEntities() {
+ Set> managedTypes = emf.getMetamodel().getEntities();
+ List> exportable = new ArrayList<>();
+
+ // Always include Account as the tenant root
+ exportable.add(Account.class);
+ log.debug("[Migration] Always including: {}", Account.class.getName());
+
+ for (EntityType entityType : managedTypes) {
+ Class javaType = entityType.getJavaType();
+
+ // Skip Account itself (already added above)
+ if (Account.class.equals(javaType)) {
+ continue;
+ }
+
+ // Skip entities not annotated as tenant-aware
+ if (!AccountAware.class.isAssignableFrom(javaType)) {
+ continue;
+ }
+
+ // Skip entities explicitly excluded from export
+ if (javaType.isAnnotationPresent(AccountExportIgnore.class)) {
+ log.debug("[Migration] Skipping @AccountExportIgnore entity: {}", javaType.getName());
+ continue;
+ }
+
+ exportable.add(javaType);
+ log.debug("[Migration] Discovered exportable entity: {}", javaType.getName());
+ }
+
+ log.info("[Migration] Discovered {} exportable entity types", exportable.size());
+ return exportable;
+ }
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/domain/AccountJobStatus.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/domain/AccountJobStatus.java
new file mode 100644
index 00000000..6688409d
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/domain/AccountJobStatus.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.domain;
+
+/**
+ * Lifecycle status of a {@link AccountMigrationJob}.
+ *
+ * @author Mario Serrano Leones
+ */
+public enum AccountJobStatus {
+
+ /** Job has been created but not started yet. */
+ PENDING,
+
+ /** Job is currently executing in a background virtual thread. */
+ RUNNING,
+
+ /** Job finished successfully. Result file is available for download. */
+ COMPLETED,
+
+ /** Job failed with an error. See {@link AccountMigrationJob#getErrorMessage()}. */
+ FAILED,
+
+ /** Job was cancelled by the user before it completed. */
+ CANCELLED
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/domain/AccountJobType.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/domain/AccountJobType.java
new file mode 100644
index 00000000..7cad29af
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/domain/AccountJobType.java
@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.domain;
+
+/**
+ * Type of a {@link AccountMigrationJob}.
+ *
+ * @author Mario Serrano Leones
+ */
+public enum AccountJobType {
+
+ /** Export all tenant data to a JSON/GZIP file. */
+ EXPORT,
+
+ /** Import tenant data from a previously exported file. */
+ IMPORT,
+
+ /** Clone a tenant within the same system (source → target accountId). */
+ CLONE,
+
+ /** Export tagged as a backup (semantically identical to EXPORT). */
+ BACKUP,
+
+ /** Import that replaces existing tenant data (semantically identical to IMPORT). */
+ RESTORE,
+
+ /**
+ * Cross-environment migration: export locally + push to a remote endpoint.
+ * Planned for v2.
+ */
+ MIGRATE
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/domain/AccountMigrationJob.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/domain/AccountMigrationJob.java
new file mode 100644
index 00000000..a4add282
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/domain/AccountMigrationJob.java
@@ -0,0 +1,244 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.Table;
+import tools.dynamia.commons.StringUtils;
+import tools.dynamia.domain.jpa.SimpleEntity;
+import tools.dynamia.modules.saas.migration.api.AccountExportOptions;
+import tools.dynamia.modules.saas.migration.api.AccountImportOptions;
+
+import java.time.LocalDateTime;
+
+/**
+ * Persisted record of a tenant mobility operation (export, import, clone, backup, restore).
+ *
+ *
Each row tracks the full lifecycle: PENDING → RUNNING → COMPLETED / FAILED / CANCELLED.
+ *
+ *
This entity is NOT {@code AccountAware} intentionally — it is a system-level record
+ * and must not be exported alongside tenant data.
+ *
+ * @author Mario Serrano Leones
+ */
+@Entity
+@Table(name = "saas_migration_jobs")
+public class AccountMigrationJob extends SimpleEntity {
+
+ // ─── Identity ──────────────────────────────────────────────────────────────
+
+ /** Stable external identifier (URL-safe, used in REST paths). */
+ @Column(nullable = false, unique = true, length = 64)
+ private String uuid = StringUtils.randomString();
+
+ // ─── Tenant references ─────────────────────────────────────────────────────
+
+ /** Source tenant account ID. */
+ private Long accountId;
+
+ /** Target tenant account ID (used for clone/restore operations). */
+ private Long targetAccountId;
+
+ // ─── Classification ────────────────────────────────────────────────────────
+
+ @Enumerated(EnumType.STRING)
+ @Column(length = 30)
+ private AccountJobType jobType;
+
+ @Enumerated(EnumType.STRING)
+ @Column(length = 30)
+ private AccountJobStatus status = AccountJobStatus.PENDING;
+
+ // ─── Progress ──────────────────────────────────────────────────────────────
+
+ /** Completion percentage 0–100. */
+ private int progress;
+
+ @Column(length = 2000)
+ private String progressMessage;
+
+ // ─── Timestamps ────────────────────────────────────────────────────────────
+
+ private LocalDateTime createdAt = LocalDateTime.now();
+ private LocalDateTime startedAt;
+ private LocalDateTime finishedAt;
+
+ // ─── Results & errors ──────────────────────────────────────────────────────
+
+ @Column(columnDefinition = "TEXT")
+ private String errorMessage;
+
+ /** Absolute path to the result file on disk (EXPORT / BACKUP jobs). */
+ @Column(length = 1000)
+ private String resultPath;
+
+ /** Serialized {@link AccountExportOptions}
+ * or {@link AccountImportOptions} as JSON. */
+ @Column(length = 4000)
+ private String optionsJson;
+
+ // ─── Helpers ───────────────────────────────────────────────────────────────
+
+ /** Mark the job as started. */
+ public void markRunning() {
+ this.status = AccountJobStatus.RUNNING;
+ this.startedAt = LocalDateTime.now();
+ }
+
+ /** Mark the job as successfully completed. */
+ public void markCompleted() {
+ this.status = AccountJobStatus.COMPLETED;
+ this.finishedAt = LocalDateTime.now();
+ this.progress = 100;
+ }
+
+ /** Mark the job as failed with an error message. */
+ public void markFailed(String errorMessage) {
+ this.status = AccountJobStatus.FAILED;
+ this.finishedAt = LocalDateTime.now();
+ this.errorMessage = errorMessage;
+ }
+
+ /** Mark the job as cancelled. */
+ public void markCancelled(String reason) {
+ this.status = AccountJobStatus.CANCELLED;
+ this.finishedAt = LocalDateTime.now();
+ this.progressMessage = reason;
+ }
+
+ /** Update running progress (0-100) and an optional human-readable message. */
+ public void updateProgress(int progress, String message) {
+ this.progress = Math.min(100, Math.max(0, progress));
+ this.progressMessage = message;
+ }
+
+ /** Returns {@code true} if the job is in a terminal state. */
+ public boolean isFinished() {
+ return status == AccountJobStatus.COMPLETED
+ || status == AccountJobStatus.FAILED
+ || status == AccountJobStatus.CANCELLED;
+ }
+
+ // ─── Accessors ─────────────────────────────────────────────────────────────
+
+ public String getUuid() {
+ return uuid;
+ }
+
+ public void setUuid(String uuid) {
+ this.uuid = uuid;
+ }
+
+ public Long getAccountId() {
+ return accountId;
+ }
+
+ public void setAccountId(Long accountId) {
+ this.accountId = accountId;
+ }
+
+ public Long getTargetAccountId() {
+ return targetAccountId;
+ }
+
+ public void setTargetAccountId(Long targetAccountId) {
+ this.targetAccountId = targetAccountId;
+ }
+
+ public AccountJobType getJobType() {
+ return jobType;
+ }
+
+ public void setJobType(AccountJobType jobType) {
+ this.jobType = jobType;
+ }
+
+ public AccountJobStatus getStatus() {
+ return status;
+ }
+
+ public void setStatus(AccountJobStatus status) {
+ this.status = status;
+ }
+
+ public int getProgress() {
+ return progress;
+ }
+
+ public void setProgress(int progress) {
+ this.progress = progress;
+ }
+
+ public String getProgressMessage() {
+ return progressMessage;
+ }
+
+ public void setProgressMessage(String progressMessage) {
+ this.progressMessage = progressMessage;
+ }
+
+ public LocalDateTime getCreatedAt() {
+ return createdAt;
+ }
+
+ public void setCreatedAt(LocalDateTime createdAt) {
+ this.createdAt = createdAt;
+ }
+
+ public LocalDateTime getStartedAt() {
+ return startedAt;
+ }
+
+ public void setStartedAt(LocalDateTime startedAt) {
+ this.startedAt = startedAt;
+ }
+
+ public LocalDateTime getFinishedAt() {
+ return finishedAt;
+ }
+
+ public void setFinishedAt(LocalDateTime finishedAt) {
+ this.finishedAt = finishedAt;
+ }
+
+ public String getErrorMessage() {
+ return errorMessage;
+ }
+
+ public void setErrorMessage(String errorMessage) {
+ this.errorMessage = errorMessage;
+ }
+
+ public String getResultPath() {
+ return resultPath;
+ }
+
+ public void setResultPath(String resultPath) {
+ this.resultPath = resultPath;
+ }
+
+ public String getOptionsJson() {
+ return optionsJson;
+ }
+
+ public void setOptionsJson(String optionsJson) {
+ this.optionsJson = optionsJson;
+ }
+
+ @Override
+ public String toString() {
+ return "TenantMobilityJob{uuid=" + uuid + ", type=" + jobType + ", status=" + status + "}";
+ }
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/graph/EntityDependencyGraph.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/graph/EntityDependencyGraph.java
new file mode 100644
index 00000000..c149cda9
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/graph/EntityDependencyGraph.java
@@ -0,0 +1,144 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.graph;
+
+import jakarta.persistence.EntityManagerFactory;
+import jakarta.persistence.metamodel.Attribute.PersistentAttributeType;
+import jakarta.persistence.metamodel.EntityType;
+import jakarta.persistence.metamodel.SingularAttribute;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import tools.dynamia.integration.sterotypes.Service;
+
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Queue;
+import java.util.Set;
+
+/**
+ * Builds a directed dependency graph of JPA entity classes and produces a
+ * topologically sorted import order (parents before children).
+ *
+ *
Graph construction
+ * For each entity {@code E} in the input set, every {@code @ManyToOne} /
+ * {@code @OneToOne} attribute that references another entity {@code P} in the
+ * same set creates a directed edge {@code P → E} (P must be imported before E).
+ *
+ *
Topological sort
+ * Kahn's BFS algorithm is used. If a cycle is detected (unlikely with
+ * well-formed JPA models), the remaining nodes are appended in their original
+ * discovery order so the pipeline can still proceed.
+ *
+ * @author Mario Serrano Leones
+ */
+@Service
+public class EntityDependencyGraph {
+
+ private static final Logger log = LoggerFactory.getLogger(EntityDependencyGraph.class);
+
+ private final EntityManagerFactory emf;
+
+ public EntityDependencyGraph(EntityManagerFactory emf) {
+ this.emf = emf;
+ }
+
+ /**
+ * Returns the input list sorted so that every entity appears after all
+ * entities it references (i.e., safe insert order).
+ *
+ * @param entityClasses the set of entity classes to sort
+ * @return a new list in topological order
+ */
+ public List> topologicalSort(List> entityClasses) {
+ if (entityClasses == null || entityClasses.isEmpty()) {
+ return Collections.emptyList();
+ }
+
+ Set> classSet = new HashSet<>(entityClasses);
+
+ // adjacency: node → set of nodes that depend on it (predecessors of edges)
+ Map, Set>> dependents = new HashMap<>();
+ // in-degree: how many entities this entity depends on (within our set)
+ Map, Integer> inDegree = new HashMap<>();
+
+ for (Class clazz : entityClasses) {
+ dependents.putIfAbsent(clazz, new HashSet<>());
+ inDegree.putIfAbsent(clazz, 0);
+ }
+
+ // Build graph from JPA metamodel
+ for (Class child : entityClasses) {
+ try {
+ EntityType entityType = emf.getMetamodel().entity(child);
+ for (SingularAttribute attr : entityType.getSingularAttributes()) {
+ PersistentAttributeType pt = attr.getPersistentAttributeType();
+ if (pt == PersistentAttributeType.MANY_TO_ONE
+ || pt == PersistentAttributeType.ONE_TO_ONE) {
+ Class parent = attr.getJavaType();
+ if (classSet.contains(parent) && !parent.equals(child)) {
+ // child depends on parent → edge: parent → child
+ dependents.get(parent).add(child);
+ inDegree.merge(child, 1, Integer::sum);
+ }
+ }
+ }
+ } catch (IllegalArgumentException e) {
+ // Entity not in metamodel; skip
+ log.warn("[Migration] Entity not found in JPA metamodel, skipping graph analysis: {}", child.getName());
+ }
+ }
+
+ // Kahn's BFS topological sort
+ Queue> queue = new ArrayDeque<>();
+ for (Class clazz : entityClasses) {
+ if (inDegree.get(clazz) == 0) {
+ queue.add(clazz);
+ }
+ }
+
+ List> sorted = new ArrayList<>(entityClasses.size());
+ Set> visited = new HashSet<>();
+
+ while (!queue.isEmpty()) {
+ Class current = queue.poll();
+ sorted.add(current);
+ visited.add(current);
+
+ for (Class dependent : dependents.get(current)) {
+ int newDegree = inDegree.merge(dependent, -1, Integer::sum);
+ if (newDegree == 0) {
+ queue.add(dependent);
+ }
+ }
+ }
+
+ // Cycle fallback: append remaining unvisited nodes
+ if (sorted.size() < entityClasses.size()) {
+ log.warn("[Migration] Dependency graph has cycles; appending {} unresolved entities in original order",
+ entityClasses.size() - sorted.size());
+ for (Class clazz : entityClasses) {
+ if (!visited.contains(clazz)) {
+ sorted.add(clazz);
+ }
+ }
+ }
+
+ log.debug("[Migration] Topological sort result: {}",
+ sorted.stream().map(Class::getSimpleName).toList());
+ return sorted;
+ }
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/identity/KeepIdsIdentityMapper.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/identity/KeepIdsIdentityMapper.java
new file mode 100644
index 00000000..5c7e7165
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/identity/KeepIdsIdentityMapper.java
@@ -0,0 +1,47 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.identity;
+
+import tools.dynamia.modules.saas.migration.api.IdentityMapper;
+import tools.dynamia.modules.saas.migration.api.IdentityStrategy;
+
+import java.util.Map;
+
+/**
+ * Identity mapper that preserves the original primary keys from the export file.
+ *
+ *
Suitable for restoring a backup to a completely empty target database where
+ * ID conflicts are not expected. If the target database already contains rows
+ * with the same IDs, constraint violations will occur.
+ *
+ * @author Mario Serrano Leones
+ */
+public class KeepIdsIdentityMapper implements IdentityMapper {
+
+ @Override
+ public Object mapId(Object originalId, Class entityClass) {
+ // Return the original ID — tell the pipeline to set it before persisting
+ return originalId;
+ }
+
+ @Override
+ public Object resolveReferenceId(Object originalRefId, Class refClass,
+ Map> idMappings) {
+ // IDs are unchanged, so the reference ID from the file is already correct
+ return originalRefId;
+ }
+
+ @Override
+ public IdentityStrategy getStrategy() {
+ return IdentityStrategy.KEEP_IDS;
+ }
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/identity/RegenerateIdsIdentityMapper.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/identity/RegenerateIdsIdentityMapper.java
new file mode 100644
index 00000000..1c55a25b
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/identity/RegenerateIdsIdentityMapper.java
@@ -0,0 +1,62 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.identity;
+
+import tools.dynamia.modules.saas.migration.api.IdentityMapper;
+import tools.dynamia.modules.saas.migration.api.IdentityStrategy;
+
+import java.util.Map;
+
+/**
+ * Identity mapper that discards original IDs and lets JPA auto-generate new ones.
+ *
+ *
During import, each entity is persisted without a pre-set ID so the JPA
+ * persistence provider assigns a fresh ID. After each {@code persist}, the mapping
+ * {@code originalId → newId} is recorded and used to resolve foreign-key references
+ * in subsequent entities.
+ *
+ *
This is the recommended strategy for cloning within the same database, where
+ * duplicate IDs would cause constraint violations.
+ *
+ * @author Mario Serrano Leones
+ */
+public class RegenerateIdsIdentityMapper implements IdentityMapper {
+
+ @Override
+ public Object mapId(Object originalId, Class entityClass) {
+ // Return null → pipeline will clear the ID field and let JPA generate a new one
+ return null;
+ }
+
+ @Override
+ public Object resolveReferenceId(Object originalRefId, Class refClass,
+ Map> idMappings) {
+ if (originalRefId == null) {
+ return null;
+ }
+ Map classMap = idMappings.get(refClass.getName());
+ if (classMap != null) {
+ Object mapped = classMap.get(originalRefId);
+ if (mapped != null) {
+ return mapped;
+ }
+ }
+ // Fallback: return original (may happen for references to entities not in the export,
+ // e.g., system-level entities shared across tenants)
+ return originalRefId;
+ }
+
+ @Override
+ public IdentityStrategy getStrategy() {
+ return IdentityStrategy.REGENERATE_IDS;
+ }
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/pipeline/ExportConstants.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/pipeline/ExportConstants.java
new file mode 100644
index 00000000..2b318d19
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/pipeline/ExportConstants.java
@@ -0,0 +1,52 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.pipeline;
+
+/**
+ * Constants shared between the export and import pipelines.
+ *
+ * @author Mario Serrano Leones
+ */
+public final class ExportConstants {
+
+ private ExportConstants() {
+ }
+
+ /** Current format version written to every export file. */
+ public static final String FORMAT_VERSION = "1";
+
+ /**
+ * Suffix appended to field names when serializing {@code @ManyToOne} /
+ * {@code @OneToOne} references. For example, a {@code category} field is
+ * exported as {@code category_ref_id} containing only the referenced entity's
+ * primary key value.
+ */
+ public static final String REF_ID_SUFFIX = "_ref_id";
+
+ /** Top-level JSON field containing the serialized AccountDTO. */
+ public static final String FIELD_ACCOUNT = "account";
+
+ /** Top-level JSON field containing the entity data map. */
+ public static final String FIELD_ENTITIES = "entities";
+
+ /** Top-level JSON field for the format version string. */
+ public static final String FIELD_VERSION = "version";
+
+ /** Top-level JSON field for the ISO-8601 export timestamp. */
+ public static final String FIELD_EXPORTED_AT = "exportedAt";
+
+ /** Top-level JSON field for the source account ID. */
+ public static final String FIELD_SOURCE_ACCOUNT_ID = "sourceAccountId";
+
+ /** Top-level JSON field for the identity strategy name. */
+ public static final String FIELD_IDENTITY_STRATEGY = "identityStrategy";
+}
+
diff --git a/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/pipeline/ExportPipeline.java b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/pipeline/ExportPipeline.java
new file mode 100644
index 00000000..46a7843b
--- /dev/null
+++ b/extensions/saas/sources/migration/src/main/java/tools/dynamia/modules/saas/migration/pipeline/ExportPipeline.java
@@ -0,0 +1,324 @@
+/*
+ * Copyright (C) 2023 Dynamia Soluciones IT S.A.S - NIT 900302344-1
+ * Colombia / South America
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+package tools.dynamia.modules.saas.migration.pipeline;
+
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.core.JsonGenerator;
+import jakarta.persistence.EntityManagerFactory;
+import jakarta.persistence.metamodel.Attribute.PersistentAttributeType;
+import jakarta.persistence.metamodel.EntityType;
+import jakarta.persistence.metamodel.SingularAttribute;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Qualifier;
+import tools.dynamia.domain.jpa.JpaUtils;
+import tools.dynamia.domain.query.DataPaginator;
+import tools.dynamia.domain.query.QueryParameters;
+import tools.dynamia.domain.services.CrudService;
+import tools.dynamia.integration.sterotypes.Service;
+import tools.dynamia.modules.saas.api.ExportIgnore;
+import tools.dynamia.modules.saas.domain.Account;
+import tools.dynamia.modules.saas.migration.api.CancellationToken;
+import tools.dynamia.modules.saas.migration.api.MigrationException;
+import tools.dynamia.modules.saas.migration.api.MigrationProgress;
+import tools.dynamia.modules.saas.migration.api.MigrationProgressListener;
+import tools.dynamia.modules.saas.migration.api.AccountExportOptions;
+import tools.dynamia.modules.saas.migration.config.AccountMigrationProperties;
+import tools.dynamia.modules.saas.migration.discovery.AccountEntityDiscovery;
+import tools.dynamia.modules.saas.migration.graph.EntityDependencyGraph;
+
+import java.io.IOException;
+import java.io.OutputStream;
+import java.io.Serializable;
+import java.lang.reflect.Field;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.zip.GZIPOutputStream;
+
+/**
+ * Streaming export pipeline.
+ *
+ *
Writes tenant data to an {@link OutputStream} using Jackson's
+ * {@link JsonGenerator}. Entities are processed in topological order, paginated
+ * by chunks so that RAM usage is bounded regardless of dataset size.
+ *
+ *
Serialization rules per attribute type
+ *
+ *
{@code BASIC} / {@code EMBEDDED} — value written directly.
+ *
{@code MANY_TO_ONE} / {@code ONE_TO_ONE} — written as
+ * {@code {fieldName}_ref_id: }.
+ *
{@code ONE_TO_MANY} / {@code MANY_TO_MANY} — skipped; child entities
+ * include their own references back to the parent.
+ *
+ *
+ *
Fields annotated with {@link ExportIgnore} are silently skipped.
+ *
+ * @author Mario Serrano Leones
+ */
+@Service
+public class ExportPipeline {
+
+ private static final Logger log = LoggerFactory.getLogger(ExportPipeline.class);
+
+ private final EntityManagerFactory emf;
+ private final CrudService crudService;
+ private final AccountEntityDiscovery discovery;
+ private final EntityDependencyGraph dependencyGraph;
+ private final AccountMigrationProperties properties;
+ private final ObjectMapper objectMapper;
+
+ public ExportPipeline(EntityManagerFactory emf,
+ CrudService crudService,
+ AccountEntityDiscovery discovery,
+ EntityDependencyGraph dependencyGraph,
+ AccountMigrationProperties properties,
+ @Qualifier("migrationObjectMapper") ObjectMapper objectMapper) {
+ this.emf = emf;
+ this.crudService = crudService;
+ this.discovery = discovery;
+ this.dependencyGraph = dependencyGraph;
+ this.properties = properties;
+ this.objectMapper = objectMapper;
+ }
+
+ /**
+ * Exports all tenant data for {@code accountId} to {@code output}.
+ *
+ * @param accountId ID of the account to export
+ * @param output destination stream; ownership is NOT transferred — the caller must close it
+ * @param options export configuration
+ * @param listener optional progress callback
+ * @param token optional cancellation token
+ */
+ public void export(Long accountId,
+ OutputStream output,
+ AccountExportOptions options,
+ MigrationProgressListener listener,
+ CancellationToken token) {
+
+ Account account = crudService.find(Account.class, accountId);
+ if (account == null) {
+ throw new MigrationException("Account not found: " + accountId);
+ }
+
+ List> candidates = discovery.discoverExportableEntities();
+ List> ordered = dependencyGraph.topologicalSort(candidates);
+
+ // Pre-calculate approximate total for progress reporting
+ long totalRecords = 0;
+ for (Class ec : ordered) {
+ if (!Account.class.equals(ec)) {
+ try {
+ totalRecords += crudService.count(ec, QueryParameters.with("accountId", accountId));
+ } catch (Exception e) {
+ log.debug("[Migration/Export] Could not count {}: {}", ec.getSimpleName(), e.getMessage());
+ }
+ }
+ }
+ totalRecords += 1; // +1 for the account itself
+
+ OutputStream target;
+ try {
+ target = options.isCompressionEnabled() ? new GZIPOutputStream(output) : output;
+ } catch (IOException e) {
+ throw new MigrationException("Failed to set up output stream", e);
+ }
+
+ try (JsonGenerator gen = objectMapper.createGenerator(target)) {
+
+ gen.writeStartObject();
+ gen.writeStringProperty(ExportConstants.FIELD_VERSION, ExportConstants.FORMAT_VERSION);
+ gen.writeStringProperty(ExportConstants.FIELD_EXPORTED_AT, LocalDateTime.now().toString());
+ gen.writeNumberProperty(ExportConstants.FIELD_SOURCE_ACCOUNT_ID, accountId);
+ gen.writeStringProperty(ExportConstants.FIELD_IDENTITY_STRATEGY,
+ options.getIdentityStrategy().name());
+
+ // Serialize AccountDTO as the tenant descriptor
+ gen.writeName(ExportConstants.FIELD_ACCOUNT);
+ objectMapper.writeValue(gen, account.toDTO());
+
+ // Entity section
+ gen.writeName(ExportConstants.FIELD_ENTITIES);
+ gen.writeStartObject();
+
+ long processed = 0;
+ for (Class entityClass : ordered) {
+ if (token != null && token.isCancelled()) {
+ log.info("[Migration/Export] Cancelled at entity: {}", entityClass.getSimpleName());
+ break;
+ }
+
+ long count = exportEntityType(gen, entityClass, accountId, options, token);
+ processed += count;
+
+ if (listener != null) {
+ listener.onProgress(new MigrationProgress(processed, totalRecords,
+ "Exported " + entityClass.getSimpleName() + " (" + count + " records)"));
+ }
+ }
+
+ gen.writeEndObject(); // entities
+ gen.writeEndObject(); // root
+
+ if (options.isCompressionEnabled()) {
+ // Flush the GZIP stream
+ ((GZIPOutputStream) target).finish();
+ }
+
+ } catch (IOException e) {
+ throw new MigrationException("Export failed while writing JSON stream", e);
+ }
+ }
+
+ // ─────────────────────────────────────────────────────────────────────────
+ // Internal helpers
+ // ─────────────────────────────────────────────────────────────────────────
+
+ private long exportEntityType(JsonGenerator gen, Class entityClass, Long accountId,
+ AccountExportOptions options, CancellationToken token)
+ throws IOException {
+
+ long processed = 0;
+ int chunkSize = resolveChunkSize(options);
+
+ gen.writeName(entityClass.getName());
+ gen.writeStartArray();
+
+ try {
+ EntityType entityType = emf.getMetamodel().entity(entityClass);
+
+ if (Account.class.equals(entityClass)) {
+ // Account is already serialized in the header; produce an empty array here
+ // to keep the format consistent (importers can find it if needed)
+ gen.writeEndArray();
+ return 0;
+ }
+
+ long totalCount = crudService.count(entityClass,
+ QueryParameters.with("accountId", accountId));
+ if (totalCount == 0) {
+ gen.writeEndArray();
+ return 0;
+ }
+
+ int totalPages = (int) Math.ceil((double) totalCount / chunkSize);
+
+ for (int page = 1; page <= totalPages; page++) {
+ if (token != null && token.isCancelled()) break;
+
+ DataPaginator paginator = new DataPaginator(totalCount, chunkSize, page);
+ QueryParameters qp = QueryParameters.with("accountId", accountId)
+ .paginate(paginator)
+ .orderBy("id", true);
+
+ @SuppressWarnings("unchecked")
+ List