Immich: architecture lessons from a 100k-star Flutter photo stack

Immich is the rare Flutter app most self-hosters have heard of: Google-Photos-like backup, albums, ML search, and a mobile client that must survive flaky networks and huge libraries.

What the stack actually is

• Flutter mobile clients for iOS/Android (plus web/desktop surfaces elsewhere in the monorepo).
• NestJS server with a generated API client — OpenAPI keeps mobile and server honest.
• Python ML services for CLIP-style search and recognition.
• Docker as the blessed install path for self-hosters.

Patterns worth stealing

1. Generated API clients. Do not hand-write DTOs for a large domain.
2. Background-first upload. Treat sync as a product feature, not an afterthought.
3. Server-owned thumbnails. Mobile should not re-encode a 48MP original on a mid-range phone.

Flutter-specific notes

Large galleries punish naive GridViews. Immich-style apps need aggressive view recycling, placeholder strategy, and careful isolate use for decode. Study how upload queues persist across app restarts.

If you copy it naively

• Pulling the whole monorepo into a tiny app.
• Skipping authz on “local network” assumptions.
• Shipping ML search without a graceful empty/error path.

Steal the client/server contract and the sync queue design. Leave the Docker topology until you need it.