# keycloakify/keycloakify architecture

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

- Interactive diagram: https://gitdiagram.com/keycloakify/keycloakify
- Repository: https://github.com/keycloakify/keycloakify

## Overview

##### Project Type and Purpose
- This project is a build tool and theme generator tailored to create customized themes for Keycloak. It provides both account and login UI theming, along with an ecosystem of scripts, utilities, and build tools to integrate, generate, and preview themes.
- The README and file structure indicate that Keycloakify is not a traditional full-stack application but rather a specialized compiler/toolchain for theming, complete with Storybook integration for component previews and a rich library of scripts to support various customization workflows.

##### Main Components
a. Theme Source Components:
- Account Theming Module – under src/account: This includes context providers, templates, pages, and library functions dedicated to the Keycloak account console.
- Login Theming Module – under src/login: Contains the login context, templates, various login pages (like Login, LogoutConfirm, Register, etc.), and internationalization (i18n) support.

b. Build & Compiler Infrastructure:
- Bin and Scripts – under src/bin and scripts: These directories hold the build scripts, theme initialization utilities (like initialize-account-theme, initialize-admin-theme, initialize-email-theme), and tooling to package and customize themes.
- Keycloakify-Specific Compiler Tools – subdirectories under src/bin/keycloakify (with buildJars, generateFtl, generateResources, replacers, and others). They manage the transformation of theme source code into assets and deployable formats.

c. Utility and Shared Libraries:
- Core Utilities – under src/lib and src/tools: Utility functions such as class name management (kcClsx), sanitizers for HTML content (kcSanitize), and additional helper functions.
- Shared Components and Contexts for both modules (account and login) such as the KcContext implementations and mocks.

d. Preview, Documentation, and Storybook:
- Storybook Configuration – under .storybook and stories directories: This provides a live preview environment for UI components and theme templates.
- Test and Documentation – directories like test and README provide insights into expected behaviors and include documentation and testing code (vitest, type-level tests, etc.).

e. Configuration and Dependency Management:
- Package files (package.json, tsconfig.json, etc.) and CI/CD workflows (under .github/workflows) which hint at the external dependencies and automated processes in the build and deploy cycle.

##### Relationships & Interactions
- The Compiler/Build Tools (scripts, bin) transform the source theme components (in account, login, lib) into deployable assets that can be used by a Keycloak server.
- The generated themes integrate with Keycloak (compatible with various versions as stated in the README), so the output of these tools is configured for consumption by Keycloak.
- Storybook and the stories directory provide a feedback and preview loop for developers to view theme changes live.
- Utility libraries support both theme modules by providing common functionality such as context sanitation, dynamic class management, and i18n support.
- External integrations include CI/CD pipelines (GitHub Actions), dependency management (npm, renovate.json), and documentation portals (Hosted Storybook, Documentation linked in README).

##### Architectural Patterns and Design Principles
- Modular Structure: Separation between account and login themes, with discrete directories for each helps maintain separation of concerns.
- Build Tool Pipeline: A complex pipeline where source code is processed through multiple scripts (e.g., generating FreeMarker template files, managing imports in CSS/JS through replacers) indicative of a compiler-like design.
- Extensibility: The design is extensible through a modular structure and dedicated extension points (e.g., sync-extensions scripts) to support different Keycloak versions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Theme Modules
    subgraph "Theme Modules"
        A["Account Module"]:::module
        B["Login Module"]:::module
    end

    %% Shared Utilities
    subgraph "Shared Utilities"
        U1["Lib Utilities (lib)"]:::utility
        U2["Tools Utilities (tools)"]:::utility
    end

    %% Build & Compilation
    subgraph "Build & Compilation"
        C["General Build Scripts"]:::build
        D["Keycloakify Compiler Tools"]:::build
    end

    %% Preview / Feedback
    subgraph "Preview / Feedback"
        P1["Storybook Config"]:::preview
        P2["Stories"]:::preview
    end

    %% Configuration & Dependencies
    subgraph "Configuration & Dependencies"
        CF1["package.json"]:::config
        CF2["tsconfig.json"]:::config
        CF3["CI/CD Workflows"]:::config
    end

    %% Deployable Theme and External Integration
    E["Deployable Theme"]:::output
    K["Keycloak Server Integration"]:::external

    %% Relationships from Theme Modules to Build Process
    A -->|"uses"| C
    B -->|"uses"| C
    A -->|"depends"| U1
    A -->|"depends"| U2
    B -->|"depends"| U1
    B -->|"depends"| U2

    %% Configuration influences the Build Process
    CF1 -->|"configures"| C
    CF2 -->|"configures"| C
    CF3 -->|"configures"| C

    %% Build Process Flow
    C -->|"triggers"| D
    D -->|"generates"| E

    %% Build Process also provides Preview Assets
    D -->|"feeds"| P1
    D -->|"feeds"| P2

    %% Deployable Theme integrates with External Keycloak Server
    E -->|"integrates"| K

    %% Class Definitions
    classDef module fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef build fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef utility fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef preview fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef config fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef output fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef external fill:#f5c6cb,stroke:#721c24,stroke-width:2px;

    %% Click Events
    click A "https://github.com/keycloakify/keycloakify/tree/main/src/account"
    click B "https://github.com/keycloakify/keycloakify/tree/main/src/login"
    click C "https://github.com/keycloakify/keycloakify/tree/main/src/bin & scripts"
    click D "https://github.com/keycloakify/keycloakify/tree/main/src/bin/keycloakify"
    click U1 "https://github.com/keycloakify/keycloakify/tree/main/src/lib"
    click U2 "https://github.com/keycloakify/keycloakify/tree/main/src/tools"
    click P1 "https://github.com/keycloakify/keycloakify/blob/main/.storybook"
    click P2 "https://github.com/keycloakify/keycloakify/tree/main/stories"
    click CF1 "https://github.com/keycloakify/keycloakify/blob/main/package.json"
    click CF2 "https://github.com/keycloakify/keycloakify/blob/main/src/tsconfig.json"
    click CF3 "https://github.com/keycloakify/keycloakify/tree/main/.github/workflows"
```
