# varabyte/kobweb architecture

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

- Interactive diagram: https://gitdiagram.com/varabyte/kobweb
- Repository: https://github.com/varabyte/kobweb

## Overview

##### Major Components
- Frontend Modules:
– These compose the UI library layer on top of Compose HTML and provide the component libraries, theming (Silk), routing, and page rendering.
- Backend Modules:
– Under “backend” you have several modules such as “kobweb-api”, “server-plugin”, and “server”.
– “kobweb-api” includes the API definitions, data structures, HTTP layer (request/response handling), interceptors, logging and event management.
– “server-plugin” is meant for extending or customizing server functionality.
– “server” includes the actual server application (e.g. Application.kt, ServerGlobals.kt) built on top of Ktor or a similar web server framework.
- Common and Shared Code:
– The “common” directory includes shared code used by both client and server. For example, “common/client-server-internal”, “common/kobweb-common”, “common/kobweb-serialization”, and “common/kobwebx-serialization-kotlinx”.
– Such modules encapsulate utilities (like navigation, serialization, data collection, API stream abstractions, package mapping, etc.) that are used throughout the stack.
- Build and Tooling Infrastructure:
– The project makes extensive use of Gradle with a multi-module setup.
– Tools such as “tools/gradle-plugins”, “tools/ksp”, and other custom Gradle scripts handle code generation, plugin behavior, snapshot and publishing support.
– These parts, although not “runtime” components, are essential to understand the build and deployment pipeline.
- Playground/Examples:
– There is a “playground” section where sample applications, sites, and even site libraries (“sitelib”) are contained. This represents the demo and experimentation surface for the framework.

##### Component Relationships and Interactions
- Frontend components produce the website’s UI by leveraging Compose HTML (via modules such as kobweb-core, kobweb-compose, and Silk components) and route handling annotated with @Page.
- The backend API layer (kobweb-api) defines endpoints that the frontend interacts with to perform server-side functionality.
- Shared libraries in “common” are used by both the frontend and backend modules to handle data, serialization, and state management (for example, API streams and package mapping).
- The Gradle build and tooling modules orchestrate the entire build process, code generation (e.g., site generation based on annotated pages), and even live reloading support on the development side.
– Represent this as an external “Build/CI Pipeline” block that feeds into all modules (frontend, backend, and common).

##### Architectural Patterns and Technologies
- Layered/MVC Pattern:
– The project neatly separates presentation (Frontend UI, page components), business logic (Kobweb server/API processing), and data/infrastructure (common libraries and API streams).
- Client-Server Interaction:
– The framework provides APIs for routing, live reload, static site exports, and even web worker support.
- Use of Kotlin Multiplatform:
– The shared “common” modules highlight the multiplatform approach, letting designers know that code is reused between the browser (JS) and server (JVM).
- Gradle & Code Generation:
– The build logic makes use of custom Gradle plugins (see directories under “tools/gradle-plugins” and “tools/ksp”), reflecting compile-time code generation and metadata extraction.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Build and Tooling Infrastructure
    subgraph "Build/CI Pipeline"
        Build_gradle_build_logic["Gradle Build Logic"]:::build
        Build_gradle_plugins["Gradle Plugins"]:::build
        Build_ksp["KSP CodeGen"]:::build
        Build_build_script["Project Build Script"]:::build
    end

    %% Frontend (UI Libraries & Routing)
    subgraph "Frontend (UI Libraries & Routing)"
        FE_browser_ext["Browser Ext"]:::frontend
        FE_compose_html_ext["Compose HTML Ext"]:::frontend
        FE_kobweb_compose["Kobweb Compose"]:::frontend
        FE_kobweb_core["Kobweb Core (UI)"]:::frontend
        FE_kobweb_silk["Kobweb Silk"]:::frontend
        FE_kobweb_worker_interface["Kobweb Worker Interface"]:::frontend
        FE_kobweb_worker["Kobweb Worker"]:::frontend
        FE_kobwebx_markdown["Kobwebx Markdown"]:::frontend
        FE_silk_foundation["Silk Foundation"]:::frontend
        FE_silk_icons_fa["Silk Icons FA"]:::frontend
        FE_silk_icons_mdi["Silk Icons MDI"]:::frontend
        FE_silk_widgets_kobweb["Silk Widgets Kobweb"]:::frontend
    end

    %% Common (Shared Code)
    subgraph "Common (Shared Code)"
        Common_client_server_internal["Client-Server Internal"]:::common
        Common_kobweb_common["Kobweb Common"]:::common
        Common_kobweb_serialization["Kobweb Serialization"]:::common
        Common_kobwebx_serialization_kotlinx["Kotlinx Serialization"]:::common
    end

    %% Backend (API & Server)
    subgraph "Backend (API & Server)"
        BE_kobweb_api["Kobweb API"]:::backend
        BE_server_plugin["Server Plugin"]:::backend
        BE_server["Server App"]:::backend
    end

    %% Playground / Examples
    subgraph "Playground and Examples"
        Playground["Playground Demos"]:::playground
        Playground_sitelib["Playground SiteLib"]:::playground
    end

    %% Build Pipeline feeding into modules (dashed arrows)
    Build_gradle_build_logic -.-> FE_kobweb_core
    Build_gradle_build_logic -.-> Common_kobweb_common
    Build_gradle_build_logic -.-> BE_kobweb_api

    Build_gradle_plugins -.-> FE_kobweb_core
    Build_gradle_plugins -.-> BE_kobweb_api
    Build_gradle_plugins -.-> Common_client_server_internal

    Build_ksp -.-> FE_kobweb_core
    Build_build_script -.-> BE_server

    %% Frontend interactions with Common and Backend
    FE_kobweb_core -->|"navigate"| Common_client_server_internal
    FE_kobweb_core -->|"API_call"| BE_kobweb_api
    FE_kobweb_core <-->|"shared"| Common_kobweb_common

    %% Shared usage between Backend and Common
    BE_kobweb_api <-->|"data"| Common_kobweb_serialization

    %% Playground interactions with Frontend and Backend
    Playground -->|"demo"| FE_kobweb_core
    Playground -->|"demo"| BE_server
    Playground_sitelib -->|"extends"| Playground

    %% Click Events for Frontend Modules
    click FE_browser_ext "https://github.com/varabyte/kobweb/tree/main/frontend/browser-ext"
    click FE_compose_html_ext "https://github.com/varabyte/kobweb/tree/main/frontend/compose-html-ext"
    click FE_kobweb_compose "https://github.com/varabyte/kobweb/tree/main/frontend/kobweb-compose"
    click FE_kobweb_core "https://github.com/varabyte/kobweb/tree/main/frontend/kobweb-core"
    click FE_kobweb_silk "https://github.com/varabyte/kobweb/tree/main/frontend/kobweb-silk"
    click FE_kobweb_worker_interface "https://github.com/varabyte/kobweb/tree/main/frontend/kobweb-worker-interface"
    click FE_kobweb_worker "https://github.com/varabyte/kobweb/tree/main/frontend/kobweb-worker"
    click FE_kobwebx_markdown "https://github.com/varabyte/kobweb/tree/main/frontend/kobwebx-markdown"
    click FE_silk_foundation "https://github.com/varabyte/kobweb/tree/main/frontend/silk-foundation"
    click FE_silk_icons_fa "https://github.com/varabyte/kobweb/tree/main/frontend/silk-icons-fa"
    click FE_silk_icons_mdi "https://github.com/varabyte/kobweb/tree/main/frontend/silk-icons-mdi"
    click FE_silk_widgets_kobweb "https://github.com/varabyte/kobweb/tree/main/frontend/silk-widgets-kobweb"

    %% Click Events for Backend Modules
    click BE_kobweb_api "https://github.com/varabyte/kobweb/tree/main/backend/kobweb-api"
    click BE_server_plugin "https://github.com/varabyte/kobweb/tree/main/backend/server-plugin"
    click BE_server "https://github.com/varabyte/kobweb/tree/main/backend/server"

    %% Click Events for Common Modules
    click Common_client_server_internal "https://github.com/varabyte/kobweb/tree/main/common/client-server-internal"
    click Common_kobweb_common "https://github.com/varabyte/kobweb/tree/main/common/kobweb-common"
    click Common_kobweb_serialization "https://github.com/varabyte/kobweb/tree/main/common/kobweb-serialization"
    click Common_kobwebx_serialization_kotlinx "https://github.com/varabyte/kobweb/tree/main/common/kobwebx-serialization-kotlinx"

    %% Click Events for Build and Tooling
    click Build_gradle_build_logic "https://github.com/varabyte/kobweb/tree/main/gradle/build-logic"
    click Build_gradle_plugins "https://github.com/varabyte/kobweb/tree/main/tools/gradle-plugins"
    click Build_ksp "https://github.com/varabyte/kobweb/tree/main/tools/ksp"
    click Build_build_script "https://github.com/varabyte/kobweb/blob/main/build.gradle.kts"

    %% Click Events for Playground
    click Playground "https://github.com/varabyte/kobweb/tree/main/playground"
    click Playground_sitelib "https://github.com/varabyte/kobweb/tree/main/playground/sitelib"

    %% Class Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef backend fill:#FFF3E0,stroke:#E65100,stroke-width:2px;
    classDef common fill:#E8F5E9,stroke:#1B5E20,stroke-width:2px;
    classDef build fill:#F3E5F5,stroke:#4A148C,stroke-width:2px,stroke-dasharray: 5 5;
    classDef playground fill:#FFFDE7,stroke:#F9A825,stroke-width:2px;
```
