# immich-app/ui architecture

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

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

## Overview

##### Project type and purpose
- This is a monorepo hosting an open-source front-end component library (`@immich/ui`) and a companion Svelte Markdown preprocessor (`svelte-markdown-preprocess`).
- It includes a SvelteKit-based documentation/demo site (under `packages/ui`) and Terraform/Terragrunt modules for deploying the docs as Cloudflare Pages.

##### File structure
- Top-level “packages” directory contains two workspace packages:
- `svelte-markdown-preprocess` – a utility library with source, tests, and config.
- `ui` – the SvelteKit application and component library with `src/lib` (components & services), `src/routes` (docs/examples), and build configs (Vite, Tailwind, Svelte).
- A `deployment` directory holds Terraform modules and Terragrunt configs that target Cloudflare Pages (static-pages and pages-project).
- CI/CD is handled by GitHub Actions workflows (`.github/workflows`), covering build, test, publish (npm), and destroy (infra teardown).

##### README for additional insights
- Usage: npm installation, import components.
- Documentation: run a local dev server for the docs site.
- Contributing: uses `pnpm` and custom tool `mise`.

a. Main components
1. Developer workstation (local)
2. Monorepo codebase
- Package A: Markdown preprocessor
- Package B: UI component library + SvelteKit docs site
3. CI/CD platform (GitHub Actions)
4. Artifact repositories
- npm registry (for published packages)
- Terraform remote state (e.g., in Cloudflare R2 or S3)
5. Cloudflare Pages hosting (static site)

b. Relationships and data flows
- Developer → GitHub: push code & PRs
- GitHub Actions → run lint/tests/build on both packages
- On release tag: publish packages to npm; apply Terragrunt to deploy docs
- Terraform modules use remote state; deploy static assets to Cloudflare Pages
- End users → browse docs site on Cloudflare Pages; install `@immich/ui` from npm

c. Architectural patterns & design principles
- Monorepo with pnpm workspace for multi-package coordination
- Package separation: reusability of core logic (`markdown-preprocess`) and UI components
- SvelteKit SSR/SSG for documentation site, serving static pages
- Infrastructure as Code: Terraform modules, Terragrunt for DRY config
- CI/CD automation for build/test/publish/deploy

d. Relevant technologies & frameworks
- Frontend: Svelte, SvelteKit, Tailwind CSS, Vite
- Package management: pnpm, npm registry
- Testing: Vitest, snapshots
- Infra: Terraform, Terragrunt, Cloudflare provider
- CI: GitHub Actions
- Code quality: ESLint, Prettier

## Diagram (Mermaid)

```mermaid
flowchart TD
    Developer["Developer Workstation"]:::external
    Github["GitHub Repository (Monorepo)"]:::codeRepo

    subgraph "Monorepo Codebase"
        direction TB
        MonorepoWorkspace["pnpm-workspace.yaml"]:::codeRepo
        RootPackage["package.json"]:::codeRepo
        MarkdownPreprocessor["svelte-markdown-preprocess"]:::codeRepo
        UI["@immich/ui (SvelteKit Docs & UI Lib)"]:::codeRepo
        ViteConfig["vite.config.ts"]:::codeRepo
        SvelteConfig["svelte.config.js"]:::codeRepo
        TailwindConfig["tailwind.config.ts"]:::codeRepo
    end

    Developer -->|push code/PR| Github
    Github -->|invokes| CI_Build["Build Workflow"]:::ci
    Github -->|invokes| CI_Test["Test Workflow"]:::ci
    CI_Build -->|reports| Github
    CI_Test -->|reports| Github

    subgraph "Release & Deploy Pipeline"
        direction TB
        CI_Release["Release-Please Workflow"]:::ci
        CI_Publish["Publish Workflow"]:::ci
        CI_Destroy["Destroy Workflow"]:::ci
        CI_DeployInfra["Terraform Apply"]:::ci
        EnvVar["Environment Variables (.env)"]:::codeRepo
        RemoteState["Terraform Remote State"]:::external
        ModulesPagesProject["pages-project Module"]:::deploy
        ModulesStaticPages["static-pages Module"]:::deploy
        Pages["Cloudflare Pages Hosting"]:::deploy

        CI_Release --> CI_Publish
        CI_Release --> CI_Destroy
        CI_Release --> CI_DeployInfra
        CI_Publish -->|publish packages| NPM["npm Registry"]:::external
        CI_DeployInfra --> EnvVar
        CI_DeployInfra --> RemoteState
        CI_DeployInfra --> ModulesPagesProject
        CI_DeployInfra --> ModulesStaticPages
        ModulesPagesProject --> Pages
        ModulesStaticPages --> Pages
    end

    Pages -->|http| Users["End Users"]:::external

    click MarkdownPreprocessor "https://github.com/immich-app/ui/tree/main/packages/svelte-markdown-preprocess"
    click UI "https://github.com/immich-app/ui/tree/main/packages/ui"
    click MonorepoWorkspace "https://github.com/immich-app/ui/blob/main/pnpm-workspace.yaml"
    click RootPackage "https://github.com/immich-app/ui/blob/main/package.json"
    click ViteConfig "https://github.com/immich-app/ui/blob/main/packages/ui/vite.config.ts"
    click SvelteConfig "https://github.com/immich-app/ui/blob/main/packages/ui/svelte.config.js"
    click TailwindConfig "https://github.com/immich-app/ui/blob/main/packages/ui/tailwind.config.ts"
    click CI_Build "https://github.com/immich-app/ui/blob/main/.github/workflows/build.yml"
    click CI_Test "https://github.com/immich-app/ui/blob/main/.github/workflows/test.yml"
    click CI_Publish "https://github.com/immich-app/ui/blob/main/.github/workflows/publish.yml"
    click CI_Destroy "https://github.com/immich-app/ui/blob/main/.github/workflows/destroy.yml"
    click CI_Release "https://github.com/immich-app/ui/blob/main/.github/workflows/release-please.yml"
    click RemoteState "https://github.com/immich-app/ui/blob/main/deployment/state.hcl"
    click ModulesPagesProject "https://github.com/immich-app/ui/tree/main/deployment/modules/cloudflare/pages-project"
    click ModulesStaticPages "https://github.com/immich-app/ui/tree/main/deployment/modules/cloudflare/static-pages"
    click EnvVar "https://github.com/immich-app/ui/blob/main/deployment/.env"

    classDef codeRepo fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef ci fill:#FFA500,stroke:#333,stroke-width:1px
    classDef deploy fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
