# simulot/immich-go architecture

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

- Interactive diagram: https://gitdiagram.com/simulot/immich-go
- Repository: https://github.com/simulot/immich-go

## Overview

Immich-Go is a command-line photo migration and library-management tool. Its main workflow selects a source adapter, discovers and enriches photo assets, then uploads them to an Immich server with metadata and organization preserved. It also supports server-to-server migration, archiving, and stack management. The graph includes the shared file-processing and asset-tracking layer. Some adapter and archive connections are documented in the README rather than shown in full source excerpts; those relationships cite the README.

Main entry points: [`app/upload/run.go`](https://github.com/simulot/immich-go/blob/main/app/upload/run.go) (Upload workflow), [`app/root/rootCmd.go`](https://github.com/simulot/immich-go/blob/main/app/root/rootCmd.go) (Command router), [`adapters/fromimmich/command.go`](https://github.com/simulot/immich-go/blob/main/adapters/fromimmich/command.go) (Immich imports), [`app/archive/run.go`](https://github.com/simulot/immich-go/blob/main/app/archive/run.go) (Archive workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["Command workflows"]
  node_cli["CLI entry<br/>[main.go]"]
  node_root["Command router<br/>[rootCmd.go]"]
  node_upload["Upload workflow<br/>[run.go]"]
  node_archive["Archive workflow<br/>[run.go]"]
  node_stack["Stack command<br/>[stack.go]"]
end

subgraph group_sources["Import sources"]
  node_folder["Folder imports<br/>[run.go]"]
  node_google["Google Photos<br/>[googlephotos.go]"]
  node_fromimmich["Immich imports<br/>[command.go]"]
  node_archivefolder["Archive folder output<br/>[writeFolder.go]"]
end

subgraph group_processing["Asset processing"]
  node_asset["Asset processing<br/>[processor.go]"]
  node_tracker[("Asset tracker<br/>[tracker.go]")]
  node_groups["Grouping and stacks<br/>[groups.go]"]
end

subgraph group_server["Immich services"]
  node_connection["Server connection<br/>[client.go]"]
  node_api["Immich API client<br/>[client.go]"]
  node_immichfs["Immich file access<br/>[immich.go]"]
end

node_user(("User"))
node_server(("Immich server"))

node_user -->|"runs"| node_cli
node_cli -->|"starts"| node_root
node_root -->|"routes commands"| node_upload
node_root -->|"routes commands"| node_archive
node_root -->|"routes commands"| node_stack
node_folder -->|"provides assets"| node_upload
node_google -->|"provides assets"| node_upload
node_fromimmich -->|"provides assets"| node_upload
node_upload -->|"processes files"| node_asset
node_asset -->|"tracks assets"| node_tracker
node_upload -->|"creates stacks"| node_groups
node_stack -->|"groups assets"| node_groups
node_upload -.->|"uses connection"| node_connection
node_connection -->|"creates clients"| node_api
node_api -.->|"sends API requests"| node_server
node_fromimmich -->|"searches assets"| node_api
node_fromimmich -->|"reads asset files"| node_immichfs
node_archive -->|"selects sources"| node_folder
node_archive -->|"writes archive"| node_archivefolder

click node_cli "https://github.com/simulot/immich-go/blob/main/main.go"
click node_root "https://github.com/simulot/immich-go/blob/main/app/root/rootCmd.go"
click node_upload "https://github.com/simulot/immich-go/blob/main/app/upload/run.go"
click node_archive "https://github.com/simulot/immich-go/blob/main/app/archive/run.go"
click node_stack "https://github.com/simulot/immich-go/blob/main/app/stack/stack.go"
click node_folder "https://github.com/simulot/immich-go/blob/main/adapters/folder/run.go"
click node_google "https://github.com/simulot/immich-go/blob/main/adapters/googlePhotos/googlephotos.go"
click node_fromimmich "https://github.com/simulot/immich-go/blob/main/adapters/fromimmich/command.go"
click node_asset "https://github.com/simulot/immich-go/blob/main/internal/fileprocessor/processor.go"
click node_tracker "https://github.com/simulot/immich-go/blob/main/internal/assettracker/tracker.go"
click node_groups "https://github.com/simulot/immich-go/blob/main/internal/groups/groups.go"
click node_connection "https://github.com/simulot/immich-go/blob/main/app/client.go"
click node_api "https://github.com/simulot/immich-go/blob/main/immich/client.go"
click node_immichfs "https://github.com/simulot/immich-go/blob/main/internal/immichfs/immich.go"
click node_archivefolder "https://github.com/simulot/immich-go/blob/main/adapters/folder/writeFolder.go"

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_root,node_upload,node_archive,node_stack,node_user toneBlue
class node_folder,node_google,node_fromimmich,node_archivefolder toneAmber
class node_asset,node_tracker,node_groups,node_server toneMint
class node_connection,node_api,node_immichfs toneRose
```

## Components

### Command workflows

- [CLI entry](https://github.com/simulot/immich-go/blob/main/main.go): `main.go`
- [Command router](https://github.com/simulot/immich-go/blob/main/app/root/rootCmd.go): `app/root/rootCmd.go`
- [Upload workflow](https://github.com/simulot/immich-go/blob/main/app/upload/run.go): `app/upload/run.go`
- [Archive workflow](https://github.com/simulot/immich-go/blob/main/app/archive/run.go): `app/archive/run.go`
- [Stack command](https://github.com/simulot/immich-go/blob/main/app/stack/stack.go): `app/stack/stack.go`

### Import sources

- [Folder imports](https://github.com/simulot/immich-go/blob/main/adapters/folder/run.go): `adapters/folder/run.go`
- [Google Photos](https://github.com/simulot/immich-go/blob/main/adapters/googlePhotos/googlephotos.go): `adapters/googlePhotos/googlephotos.go`
- [Immich imports](https://github.com/simulot/immich-go/blob/main/adapters/fromimmich/command.go): `adapters/fromimmich/command.go`
- [Archive folder output](https://github.com/simulot/immich-go/blob/main/adapters/folder/writeFolder.go): `adapters/folder/writeFolder.go`

### Asset processing

- [Asset processing](https://github.com/simulot/immich-go/blob/main/internal/fileprocessor/processor.go): `internal/fileprocessor/processor.go`
- [Asset tracker](https://github.com/simulot/immich-go/blob/main/internal/assettracker/tracker.go): `internal/assettracker/tracker.go`
- [Grouping and stacks](https://github.com/simulot/immich-go/blob/main/internal/groups/groups.go): `internal/groups/groups.go`

### Immich services

- [Server connection](https://github.com/simulot/immich-go/blob/main/app/client.go): `app/client.go`
- [Immich API client](https://github.com/simulot/immich-go/blob/main/immich/client.go): `immich/client.go`
- [Immich file access](https://github.com/simulot/immich-go/blob/main/internal/immichfs/immich.go): `internal/immichfs/immich.go`

### Other components

- **User**
- **Immich server**

## Connections

- User → CLI entry: runs (evidence: `main.go`)
- CLI entry → Command router: starts (evidence: `main.go`)
- Command router → Upload workflow: routes commands (evidence: `app/root/rootCmd.go`)
- Command router → Archive workflow: routes commands (evidence: `app/root/rootCmd.go`)
- Command router → Stack command: routes commands (evidence: `app/root/rootCmd.go`)
- Folder imports → Upload workflow: provides assets
- Google Photos → Upload workflow: provides assets
- Immich imports → Upload workflow: provides assets
- Upload workflow → Asset processing: processes files (evidence: `app/upload/run.go`)
- Asset processing → Asset tracker: tracks assets (evidence: `internal/fileprocessor/processor.go`)
- Upload workflow → Grouping and stacks: creates stacks (evidence: `app/upload/run.go`)
- Stack command → Grouping and stacks: groups assets (evidence: `app/stack/stack.go`)
- Upload workflow → Server connection: uses connection
- Server connection → Immich API client: creates clients (evidence: `app/client.go`)
- Immich API client → Immich server: sends API requests
- Immich imports → Immich API client: searches assets (evidence: `adapters/fromimmich/command.go`)
- Immich imports → Immich file access: reads asset files (evidence: `adapters/fromimmich/command.go`)
- Archive workflow → Folder imports: selects sources
- Archive workflow → Archive folder output: writes archive
