# lukin/keywind architecture

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

- Interactive diagram: https://gitdiagram.com/lukin/keywind
- Repository: https://github.com/lukin/keywind

## Overview

##### Project type and purpose
- This is a Keycloak login **theme** project (“Keywind”), not a full-stack application. It provides a component-based UI layer for Keycloak’s authentication flows, built with Tailwind CSS and Alpine.js, packaged as a JAR for deployment to a Keycloak server.

##### File structure
- Top-level:
- package.json, pnpm-lock.yaml, tsconfig…: Node/TypeScript + pnpm build toolchain
- pom.xml: Maven config for JAR packaging
- scripts/build.ts: custom build script
- html/: static HTML samples of login pages
- src/: TypeScript sources for interactive behaviors (recoveryCodes, webAuthn…)
- META-INF/keycloak-themes.json: theme metadata for Keycloak

##### README for additional insights
- Emphasizes component-based (atoms, molecules) FreeMarker macros overridable by child themes.

##### Summary
- **all** essential elements—toolchain, templates, static assets, packaging, Keycloak runtime, user interactions.
- Use a layered view:
- Layer 1: Developer & Build Tools
- Layer 2: Theme Source & Asset Pipeline
- Layer 3: Deployment Artifact (JAR)
- Layer 4: Runtime (Keycloak + Browser + External IdPs)
- Don’t overcomplicate: show as many components as exist in the project structure, grouped logically by phase and function.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Phase
    subgraph "Build Phase"
        direction TB

        subgraph "Developer Tooling"
            direction TB
            pkg["package.json & pnpm-lock.yaml"]:::buildTime
            tscfg["tsconfig.json & tsconfig.node.json"]:::buildTime
            vitecfg["vite.config.ts"]:::buildTime
            tailcfg["tailwind.config.ts"]:::buildTime
            postcsscfg["postcss.config.js"]:::buildTime
            buildScript["scripts/build.ts"]:::buildTime
            maven["pom.xml"]:::buildTime
        end

        subgraph "Theme Source"
            direction TB
            htmlSamples["Static HTML Samples (html/login/*.html)"]:::buildTime
            tsModules["TypeScript Modules (src/)"]:::buildTime
            meta["Theme Metadata\n(META-INF/keycloak-themes.json)"]:::buildTime
            subgraph "FreeMarker Templates"
                direction TB
                atoms["Atoms (theme/keywind/login/components/atoms/*.ftl)"]:::buildTime
                molecules["Molecules (theme/keywind/login/components/molecules/*.ftl)"]:::buildTime
                features["Features/Labels (theme/keywind/login/features/labels/*.ftl)"]:::buildTime
                pages["Pages (theme/keywind/login/*.ftl)"]:::buildTime
                assetsTmpl["Assets (icons & providers)"]:::buildTime
            end
        end

        subgraph "Asset Pipeline"
            direction TB
            tsCompile["TypeScript Compiler"]:::buildTime
            viteBuild["Vite Bundler"]:::buildTime
            tailwind["Tailwind Processor"]:::buildTime
            postcss["PostCSS"]:::buildTime
        end

        subgraph "Build Outputs"
            direction TB
            cssBundle["index.css"]:::buildTime
            jsBundle["index.js & modules"]:::buildTime
            assetsOut["assets/*.js"]:::buildTime
            rcOut["recoveryCodes.js"]:::buildTime
            waAuthOut["webAuthnAuthenticate.js"]:::buildTime
            waRegOut["webAuthnRegister.js"]:::buildTime
        end

        subgraph "Packaging"
            direction TB
            jar["JAR Artifact (theme/keywind + META-INF)"]:::buildTime
        end

        %% Flow in Build Phase
        pkg & tscfg & vitecfg & tailcfg & postcsscfg & buildScript & maven --> htmlSamples & tsModules & meta & atoms & molecules & features & pages & assetsTmpl
        htmlSamples & tsModules & atoms & molecules & features & pages & assetsTmpl --> tsCompile
        tsCompile & viteBuild & tailwind & postcss --> cssBundle & jsBundle & assetsOut & rcOut & waAuthOut & waRegOut
        cssBundle & jsBundle & assetsOut & rcOut & waAuthOut & waRegOut --> jar
    end

    %% Runtime Phase
    subgraph "Runtime Phase"
        direction TB
        browser["Browser Client"]:::runtime
        kcServer["Keycloak Server\n(FreeMarker Engine)"]:::runtime
        kcDB["Keycloak User Database"]:::external
        idp["External Identity Providers"]:::external
    end

    %% Runtime Flows
    browser <-->|"HTTP Requests"| kcServer
    kcServer -->|"DB Queries"| kcDB
    kcServer <-->|"OAuth/OIDC"| idp

    %% Deployment arrow
    jar -->|"Deploy theme.jar to Keycloak themes"| kcServer

    %% Click Events
    click pkg "https://github.com/lukin/keywind/blob/master/package.json"
    click pkg "https://github.com/lukin/keywind/blob/master/pnpm-lock.yaml"
    click tscfg "https://github.com/lukin/keywind/blob/master/tsconfig.json"
    click tscfg "https://github.com/lukin/keywind/blob/master/tsconfig.node.json"
    click vitecfg "https://github.com/lukin/keywind/blob/master/vite.config.ts"
    click tailcfg "https://github.com/lukin/keywind/blob/master/tailwind.config.ts"
    click postcsscfg "https://github.com/lukin/keywind/blob/master/postcss.config.js"
    click buildScript "https://github.com/lukin/keywind/blob/master/scripts/build.ts"
    click maven "https://github.com/lukin/keywind/blob/master/pom.xml"
    click htmlSamples "https://github.com/lukin/keywind/tree/master/html/login/"
    click tsModules "https://github.com/lukin/keywind/blob/master/src/index.ts"
    click tsModules "https://github.com/lukin/keywind/blob/master/src/index.css"
    click tsModules "https://github.com/lukin/keywind/blob/master/src/data/recoveryCodes.ts"
    click tsModules "https://github.com/lukin/keywind/blob/master/src/data/webAuthnAuthenticate.ts"
    click tsModules "https://github.com/lukin/keywind/blob/master/src/data/webAuthnRegister.ts"
    click tsModules "https://github.com/lukin/keywind/blob/master/src/global.d.ts"
    click meta "https://github.com/lukin/keywind/blob/master/META-INF/keycloak-themes.json"
    click atoms "https://github.com/lukin/keywind/tree/master/theme/keywind/login/components/atoms/"
    click molecules "https://github.com/lukin/keywind/tree/master/theme/keywind/login/components/molecules/"
    click features "https://github.com/lukin/keywind/tree/master/theme/keywind/login/features/labels/"
    click pages "https://github.com/lukin/keywind/tree/master/theme/keywind/login/"
    click assetsTmpl "https://github.com/lukin/keywind/tree/master/theme/keywind/login/assets/icons/"
    click assetsTmpl "https://github.com/lukin/keywind/tree/master/theme/keywind/login/assets/providers/"
    click cssBundle "https://github.com/lukin/keywind/blob/master/theme/keywind/login/resources/dist/index.css"
    click jsBundle "https://github.com/lukin/keywind/blob/master/theme/keywind/login/resources/dist/index.js"
    click assetsOut "https://github.com/lukin/keywind/tree/master/theme/keywind/login/resources/dist/assets/"
    click rcOut "https://github.com/lukin/keywind/blob/master/theme/keywind/login/resources/dist/recoveryCodes.js"
    click waAuthOut "https://github.com/lukin/keywind/blob/master/theme/keywind/login/resources/dist/webAuthnAuthenticate.js"
    click waRegOut "https://github.com/lukin/keywind/blob/master/theme/keywind/login/resources/dist/webAuthnRegister.js"
    click jar "https://github.com/lukin/keywind/tree/master/theme/keywind/"
    click jar "https://github.com/lukin/keywind/tree/master/META-INF/"
    
    classDef buildTime fill:#cce5ff,stroke:#004085,color:#004085
    classDef runtime fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24
```
