# wdufrin/headless-migration-tool architecture

> Architecture diagram of the GitHub repository wdufrin/headless-migration-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wdufrin/headless-migration-tool
- Repository: https://github.com/wdufrin/headless-migration-tool

## Overview

gemini-migrate is an administrator-operated platform for moving Gemini Enterprise data and permissions between Google Cloud environments. Its main workflow is to configure source/target environments and identity mappings, discover resources, audit parity and connector mappings for human review, then run a dry-run or migration and produce reports. The graph emphasizes those documented stages and the migration runner’s indexed module dependencies. Some route wiring and unsampled engines are represented only where the README or SOURCE INDEX supports them; edges do not imply unverified call order.

Main entry points: [`src/engines/migrationRunner.ts`](https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/migrationRunner.ts) (Migration Runner), [`src/services/gcpAuth.ts`](https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/gcpAuth.ts) (GCP Authentication), [`src/cli.ts`](https://github.com/wdufrin/headless-migration-tool/blob/main/src/cli.ts) (CLI), [`src/services/discoveryEngine.ts`](https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/discoveryEngine.ts) (Resource Discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Operator Entry"]
  node_cli["CLI<br/>[cli.ts]"]
  node_server["Web Server<br/>[server.ts]"]
end

subgraph group_control["Configuration and Control"]
  node_config["Config Schema<br/>[configSchema.ts]"]
  node_discovery_route["Discovery Routes<br/>[discovery.ts]"]
  node_wizard["Setup Wizard<br/>[wizard.ts]"]
  node_migration_route["Migration Routes<br/>[migration.ts]"]
end

subgraph group_migration["Migration Workflows"]
  node_runner["Migration Runner<br/>[migrationRunner.ts]"]
  node_agents["Agent Migrator<br/>[agentMigrator.ts]"]
  node_notebooks["Notebook Migrator"]
  node_skills["Skill Migrator<br/>[skillMigrator.ts]"]
  node_sessions["Session Migrator<br/>[sessionMigrator.ts]"]
  node_memories["Memory Migrator<br/>[memoryMigrator.ts]"]
  node_artifacts["Artifact Export"]
  node_checkpoint[("Migration Checkpoints")]
end

subgraph group_integrations["Cloud and Identity"]
  node_auth["GCP Authentication<br/>[gcpAuth.ts]"]
  node_discovery["Resource Discovery<br/>[discoveryEngine.ts]"]
  node_identity["Identity Mapping"]
  node_wif["WiF Preflight<br/>[wifPreflight.ts]"]
end

subgraph group_operations["Audit and Reporting"]
  node_audit_route["Audit Routes<br/>[configAudit.ts]"]
  node_audit_engine["Parity Audit"]
  node_connector["Connector Matching"]
  node_reports["User Reports"]
  node_report_service["Report Service<br/>[reporter.ts]"]
  node_permission["Permission Audit"]
end

node_admin(("Administrator"))
node_google["Google Cloud APIs"]

node_admin -->|"runs commands"| node_cli
node_admin -->|"operates console"| node_server
node_server -->|"routes requests"| node_migration_route
node_server -->|"routes requests"| node_discovery_route
node_server -->|"routes requests"| node_wizard
node_server -->|"routes requests"| node_audit_route
node_cli -->|"loads configuration"| node_config
node_cli -->|"starts migration"| node_runner
node_cli -->|"configures credentials"| node_auth
node_cli -->|"uses discovery"| node_discovery
node_cli -->|"runs audit"| node_audit_engine
node_cli -->|"generates report"| node_reports
node_config -.->|"configures credentials"| node_auth
node_wizard -->|"sets up identity"| node_auth
node_wizard -->|"checks permissions"| node_permission
node_wizard -->|"runs preflight"| node_wif
node_discovery_route -->|"queries resources"| node_discovery
node_audit_engine -->|"compares environments"| node_discovery
node_audit_engine -->|"builds mappings"| node_connector
node_audit_engine -->|"uses credentials"| node_auth
node_admin -->|"reviews parity"| node_audit_engine
node_admin -->|"confirms migration"| node_runner
node_migration_route -.->|"starts migration"| node_runner
node_runner -->|"dispatches migration"| node_agents
node_runner -->|"dispatches migration"| node_notebooks
node_runner -->|"dispatches migration"| node_skills
node_runner -->|"dispatches migration"| node_sessions
node_runner -->|"dispatches migration"| node_memories
node_runner -->|"dispatches export"| node_artifacts
node_runner -->|"uses credentials"| node_auth
node_runner -->|"uses API client"| node_discovery
node_runner -->|"maps identities"| node_identity
node_runner -->|"saves progress"| node_checkpoint
node_agents -->|"uses API client"| node_discovery
node_agents -->|"maps owners"| node_identity
node_skills -->|"maps owners"| node_identity
node_sessions -->|"obtains tokens"| node_auth
node_sessions -->|"maps identities"| node_identity
node_memories -->|"uses credentials"| node_auth
node_memories -->|"uses API client"| node_discovery
node_memories -->|"maps users"| node_identity
node_artifacts -->|"uses credentials"| node_auth
node_artifacts -->|"extracts session data"| node_sessions
node_auth -->|"requests tokens"| node_google
node_discovery -->|"calls Discovery APIs"| node_google
node_reports -->|"uses credentials"| node_auth
node_reports -->|"queries resources"| node_discovery
node_reports -.->|"formats reports"| node_report_service

click node_cli "https://github.com/wdufrin/headless-migration-tool/blob/main/src/cli.ts"
click node_server "https://github.com/wdufrin/headless-migration-tool/blob/main/src/server.ts"
click node_config "https://github.com/wdufrin/headless-migration-tool/blob/main/src/config/configSchema.ts"
click node_auth "https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/gcpAuth.ts"
click node_discovery_route "https://github.com/wdufrin/headless-migration-tool/blob/main/src/routes/discovery.ts"
click node_wizard "https://github.com/wdufrin/headless-migration-tool/blob/main/src/routes/wizard.ts"
click node_discovery "https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/discoveryEngine.ts"
click node_audit_route "https://github.com/wdufrin/headless-migration-tool/blob/main/src/routes/configAudit.ts"
click node_audit_engine "https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/configAuditEngine.ts"
click node_connector "https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/connectorMatcher.ts"
click node_migration_route "https://github.com/wdufrin/headless-migration-tool/blob/main/src/routes/migration.ts"
click node_runner "https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/migrationRunner.ts"
click node_agents "https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/agentMigrator.ts"
click node_notebooks "https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/notebookMigrator.ts"
click node_skills "https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/skillMigrator.ts"
click node_sessions "https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/sessionMigrator.ts"
click node_memories "https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/memoryMigrator.ts"
click node_artifacts "https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/artifactExtractor.ts"
click node_identity "https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/identityMappingService.ts"
click node_checkpoint "https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/checkpointManager.ts"
click node_reports "https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/userReportGenerator.ts"
click node_report_service "https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/reporter.ts"
click node_permission "https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/permissionAuditor.ts"
click node_wif "https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/wifPreflight.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_server toneBlue
class node_config,node_discovery_route,node_wizard,node_migration_route toneAmber
class node_runner,node_agents,node_notebooks,node_skills,node_sessions,node_memories,node_artifacts,node_checkpoint,node_google toneMint
class node_auth,node_discovery,node_identity,node_wif toneRose
class node_audit_route,node_audit_engine,node_connector,node_reports,node_report_service,node_permission,node_admin toneIndigo
```

## Components

### Operator Entry

- [CLI](https://github.com/wdufrin/headless-migration-tool/blob/main/src/cli.ts): `src/cli.ts`
- [Web Server](https://github.com/wdufrin/headless-migration-tool/blob/main/src/server.ts): `src/server.ts`

### Configuration and Control

- [Config Schema](https://github.com/wdufrin/headless-migration-tool/blob/main/src/config/configSchema.ts): `src/config/configSchema.ts`
- [Discovery Routes](https://github.com/wdufrin/headless-migration-tool/blob/main/src/routes/discovery.ts): `src/routes/discovery.ts`
- [Setup Wizard](https://github.com/wdufrin/headless-migration-tool/blob/main/src/routes/wizard.ts): `src/routes/wizard.ts`
- [Migration Routes](https://github.com/wdufrin/headless-migration-tool/blob/main/src/routes/migration.ts): `src/routes/migration.ts`

### Migration Workflows

- [Migration Runner](https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/migrationRunner.ts): `src/engines/migrationRunner.ts`
- [Agent Migrator](https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/agentMigrator.ts): `src/engines/agentMigrator.ts`
- [Notebook Migrator](https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/notebookMigrator.ts): `src/engines/notebookMigrator.ts`
- [Skill Migrator](https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/skillMigrator.ts): `src/engines/skillMigrator.ts`
- [Session Migrator](https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/sessionMigrator.ts): `src/engines/sessionMigrator.ts`
- [Memory Migrator](https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/memoryMigrator.ts): `src/engines/memoryMigrator.ts`
- [Artifact Export](https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/artifactExtractor.ts): `src/engines/artifactExtractor.ts`
- [Migration Checkpoints](https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/checkpointManager.ts): `src/services/checkpointManager.ts`

### Cloud and Identity

- [GCP Authentication](https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/gcpAuth.ts): `src/services/gcpAuth.ts`
- [Resource Discovery](https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/discoveryEngine.ts): `src/services/discoveryEngine.ts`
- [Identity Mapping](https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/identityMappingService.ts): `src/services/identityMappingService.ts`
- [WiF Preflight](https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/wifPreflight.ts): `src/services/wifPreflight.ts`

### Audit and Reporting

- [Audit Routes](https://github.com/wdufrin/headless-migration-tool/blob/main/src/routes/configAudit.ts): `src/routes/configAudit.ts`
- [Parity Audit](https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/configAuditEngine.ts): `src/engines/configAuditEngine.ts`
- [Connector Matching](https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/connectorMatcher.ts): `src/services/connectorMatcher.ts`
- [User Reports](https://github.com/wdufrin/headless-migration-tool/blob/main/src/engines/userReportGenerator.ts): `src/engines/userReportGenerator.ts`
- [Report Service](https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/reporter.ts): `src/services/reporter.ts`
- [Permission Audit](https://github.com/wdufrin/headless-migration-tool/blob/main/src/services/permissionAuditor.ts): `src/services/permissionAuditor.ts`

### Other components

- **Administrator**
- **Google Cloud APIs**

## Connections

- Administrator → CLI: runs commands (evidence: `README.md`)
- Administrator → Web Server: operates console (evidence: `README.md`)
- Web Server → Migration Routes: routes requests (evidence: `src/server.ts`)
- Web Server → Discovery Routes: routes requests (evidence: `src/server.ts`)
- Web Server → Setup Wizard: routes requests (evidence: `src/server.ts`)
- Web Server → Audit Routes: routes requests (evidence: `src/server.ts`)
- CLI → Config Schema: loads configuration (evidence: `src/cli.ts`)
- CLI → Migration Runner: starts migration (evidence: `src/cli.ts`)
- CLI → GCP Authentication: configures credentials (evidence: `src/cli.ts`)
- CLI → Resource Discovery: uses discovery (evidence: `src/cli.ts`)
- CLI → Parity Audit: runs audit (evidence: `src/cli.ts`)
- CLI → User Reports: generates report (evidence: `src/cli.ts`)
- Config Schema → GCP Authentication: configures credentials
- Setup Wizard → GCP Authentication: sets up identity (evidence: `src/routes/wizard.ts`)
- Setup Wizard → Permission Audit: checks permissions (evidence: `src/routes/wizard.ts`)
- Setup Wizard → WiF Preflight: runs preflight (evidence: `src/routes/wizard.ts`)
- Discovery Routes → Resource Discovery: queries resources (evidence: `src/routes/discovery.ts`)
- Parity Audit → Resource Discovery: compares environments (evidence: `src/engines/configAuditEngine.ts`)
- Parity Audit → Connector Matching: builds mappings (evidence: `src/engines/configAuditEngine.ts`)
- Parity Audit → GCP Authentication: uses credentials (evidence: `src/engines/configAuditEngine.ts`)
- Administrator → Parity Audit: reviews parity (evidence: `README.md`)
- Administrator → Migration Runner: confirms migration (evidence: `README.md`)
- Migration Routes → Migration Runner: starts migration
- Migration Runner → Agent Migrator: dispatches migration (evidence: `src/engines/migrationRunner.ts`)
- Migration Runner → Notebook Migrator: dispatches migration (evidence: `src/engines/migrationRunner.ts`)
- Migration Runner → Skill Migrator: dispatches migration (evidence: `src/engines/migrationRunner.ts`)
- Migration Runner → Session Migrator: dispatches migration (evidence: `src/engines/migrationRunner.ts`)
- Migration Runner → Memory Migrator: dispatches migration (evidence: `src/engines/migrationRunner.ts`)
- Migration Runner → Artifact Export: dispatches export (evidence: `src/engines/migrationRunner.ts`)
- Migration Runner → GCP Authentication: uses credentials (evidence: `src/engines/migrationRunner.ts`)
- Migration Runner → Resource Discovery: uses API client (evidence: `src/engines/migrationRunner.ts`)
- Migration Runner → Identity Mapping: maps identities (evidence: `src/engines/migrationRunner.ts`)
- Migration Runner → Migration Checkpoints: saves progress (evidence: `src/engines/migrationRunner.ts`)
- Agent Migrator → Resource Discovery: uses API client (evidence: `src/engines/agentMigrator.ts`)
- Agent Migrator → Identity Mapping: maps owners (evidence: `src/engines/agentMigrator.ts`)
- Skill Migrator → Identity Mapping: maps owners (evidence: `src/engines/skillMigrator.ts`)
- Session Migrator → GCP Authentication: obtains tokens (evidence: `src/engines/sessionMigrator.ts`)
- Session Migrator → Identity Mapping: maps identities (evidence: `src/engines/sessionMigrator.ts`)
- Memory Migrator → GCP Authentication: uses credentials (evidence: `src/engines/memoryMigrator.ts`)
- Memory Migrator → Resource Discovery: uses API client (evidence: `src/engines/memoryMigrator.ts`)
- Memory Migrator → Identity Mapping: maps users (evidence: `src/engines/memoryMigrator.ts`)
- Artifact Export → GCP Authentication: uses credentials (evidence: `src/engines/artifactExtractor.ts`)
- Artifact Export → Session Migrator: extracts session data (evidence: `src/engines/artifactExtractor.ts`)
- GCP Authentication → Google Cloud APIs: requests tokens (evidence: `src/services/gcpAuth.ts`)
- Resource Discovery → Google Cloud APIs: calls Discovery APIs (evidence: `README.md`)
- User Reports → GCP Authentication: uses credentials (evidence: `src/engines/userReportGenerator.ts`)
- User Reports → Resource Discovery: queries resources (evidence: `src/engines/userReportGenerator.ts`)
- User Reports → Report Service: formats reports
