How varabyte/kobweb works
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.