# yoni13/immich architecture

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

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

## Overview

##### Main components
- Client Applications:
– Mobile app (with its own native project, tests, assets, and integration components)
– Web client (built in Svelte with its custom routing and UI components)
– CLI tool (for server-side operations and administration)
- Backend Application (“server”):
– A NestJS–based Node/TypeScript server organized as controllers, services, entities, DTOs, and migrations.
– It handles API endpoints for authentication, asset management, albums, facial recognition, search, sharing, and more.
- Machine Learning Module:
– Contains scripts, Dockerfiles, and C++/Python code (including ANN models, facial recognition, CLIP integrations, and export utilities) for image classification and face extraction.
- OpenAPI / SDK Layer:
– The “open-api” directory contains API definitions and a TypeScript SDK generator.
- Deployment and Infrastructure:
– Docker and deployment directories include Docker Compose files, container configuration (including the .devcontainer), cloud configurations, and deployment modules for various platforms.
- Ancillary Projects:
– Developer documentation (“docs”), E2E tests, and CI/CD configuration (.github workflows)

##### Relationships
- That Mobile and Web clients communicate via REST (or WebSocket where applicable) with the Backend API.
- That the CLI tool can invoke specific server commands (via HTTP endpoints or direct CLI scripts).
- Machine learning subsystem both as an independent service (or microservice) that integrates (e.g., via API endpoints or direct function calls via queues) for tasks like facial recognition and CLIP processing.
- Integration points for external services such as OAuth, storage backends, and possibly caching or notification services.

##### Architectural patterns and design principles
- Use a modular / microservices–oriented approach where the backend is decomposed into controllers, repositories, and services. This separation of concerns is very apparent in directory names such as “controllers”, “services”, “repositories”, and “entities.”
- The deployment pipelines are containerized using Docker, and the inclusion of CI/CD folders (.github/workflows, renovate, etc.) emphasizes a modern DevOps practice.
- The system uses a layered architecture: presentation layer (mobile/web), application layer (CLI / APIs), and data access layer (ORM entities, migrations, and direct SQL queries).

##### Relevant technologies, frameworks, and libraries
- Mobile: Flutter (as inferred by typical Dart/Flutter files such as “pubspec.yaml”, “.fvmrc”, and i18n assets) supporting offline backup and media management.
- Web: Svelte (with Vite and Tailwind) for frontend rendering.
- Server: Node.js/TypeScript along with NestJS framework (as suggested by the organization into controllers, providers, modules, DTOs, and service tests).
- Machine Learning: Likely a combination of Python, C++, and Dockerized workloads, with attention to ANN and CLIP models.
- OpenAPI: The “open-api” directory containing OpenAPI specification files and client generators.
- CI/CD: GitHub workflows, Docker Compose setups for different environments (development, production, and mobile).
- Testing: E2E tests (using Playwright and Vitest), unit test suites, and integration tests across services.

##### Detail and clarity
- Most essential architectural elements without oversimplification. Try to break down the backend into its core functionalities (authentication, asset management, albums, sharing, etc.)
- How deployments and containerization are managed (show Docker Compose, deployment modules, and CI/CD integration).
- Optionally, you could add a layer for internationalization and documentation tools given the project’s strong focus on multi-language support and developer docs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Applications"
        MA["Mobile App"]:::client
        WA["Web Client"]:::client
        CLI["CLI Tool"]:::client
    end

    subgraph "Backend System"
        API["Backend API (NestJS)"]:::backend
        DB["Database (PostgreSQL)"]:::database
        ML["Machine Learning Module"]:::ml
        subgraph "OpenAPI / SDK"
            OAPI_DEF["API Definitions"]:::backend
            OAPI_SDK["TypeScript SDK Generator"]:::backend
        end
    end

    subgraph "Deployment & Infrastructure"
        D1["Docker"]:::infra
        D2["Deployment Config"]:::infra
        D3["CI/CD Workflows"]:::infra
    end

    subgraph "Ancillary Projects"
        A1["Documentation"]:::ancillary
        A2["E2E Tests"]:::ancillary
        A3["CI/CD Configurations"]:::ancillary
    end

    %% Client to Backend connections
    MA -->|"calls_API"| API
    WA -->|"calls_API"| API
    CLI -->|"invokes"| API

    %% Backend internal connections
    API -->|"reads/writes"| DB
    API -->|"triggers"| ML
    API -->|"exposes"| OAPI_DEF
    OAPI_DEF -->|"generates"| OAPI_SDK

    %% Deployment & Infrastructure connections
    D2 -->|"deploys"| API
    D3 -->|"triggers"| D2
    A3 -->|"integrates"| D3

    %% Click Events for Client Applications
    click MA "https://github.com/yoni13/immich/tree/main/mobile"
    click WA "https://github.com/yoni13/immich/tree/main/web"
    click CLI "https://github.com/yoni13/immich/tree/main/cli"

    %% Click Events for Backend System
    click API "https://github.com/yoni13/immich/tree/main/server"
    click ML "https://github.com/yoni13/immich/tree/main/machine-learning"
    click OAPI_DEF "https://github.com/yoni13/immich/tree/main/open-api"
    click OAPI_SDK "https://github.com/yoni13/immich/tree/main/open-api/typescript-sdk"

    %% Click Events for Deployment & Infrastructure
    click D1 "https://github.com/yoni13/immich/tree/main/docker"
    click D2 "https://github.com/yoni13/immich/tree/main/deployment"
    click D3 "https://github.com/yoni13/immich/tree/main/.github/workflows"

    %% Click Events for Ancillary Projects
    click A1 "https://github.com/yoni13/immich/tree/main/docs"
    click A2 "https://github.com/yoni13/immich/tree/main/e2e"
    click A3 "https://github.com/yoni13/immich/blob/main/.github"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef ml fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef database fill:#FFE4B5,stroke:#000,stroke-width:1px;
    classDef infra fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef ancillary fill:#DDA0DD,stroke:#000,stroke-width:1px;
```
