# bluebikebase-inc/kmp-application-foundation architecture

> Architecture diagram of the GitHub repository bluebikebase-inc/kmp-application-foundation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bluebikebase-inc/kmp-application-foundation
- Repository: https://github.com/bluebikebase-inc/kmp-application-foundation

## Overview

Foundation is a Kotlin multiplatform application and UI framework, with a localization feature and a web Gradle plugin that generates an HTML entry page. The documented user-facing flow is application lifecycle initialization, view registration and composable rendering, then start/stop/destroy. Core supplies feature registration and lifecycle control; UI supplies renderable views, containers and presentation layers. The README describes the UI lifecycle, while source excerpts and the SOURCE INDEX support the shown calls; links for unsampled subsystems are omitted where their wiring is not evidenced.

Main entry points: [`ui/src/commonMain/kotlin/org/b3/foundation/ui/view/ViewLayer.kt`](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/view/ViewLayer.kt) (View Layer), [`core/src/commonMain/kotlin/org/b3/foundation/application/Application.kt`](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/core/src/commonMain/kotlin/org/b3/foundation/application/Application.kt) (Application), [`plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/GenerateTemplateTask.kt`](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/GenerateTemplateTask.kt) (Template Task), [`core/src/commonMain/kotlin/org/b3/foundation/runtime/LifecycleController.kt`](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/core/src/commonMain/kotlin/org/b3/foundation/runtime/LifecycleController.kt) (Lifecycle Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Application Core"]
  node_application["Application<br/>[Application.kt]"]
  node_features["Feature Contracts<br/>[Feature.kt]"]
  node_featurekey["Feature Key<br/>[FeatureKey.kt]"]
  node_registry["Feature Registry<br/>[FeatureRegistry.kt]"]
  node_lifecycle["Lifecycle API<br/>[Lifecycle.kt]"]
  node_controller["Lifecycle Controller"]
end

subgraph group_ui["UI Runtime"]
  node_uiapp["UI Application<br/>[UiApplication.kt]"]
  node_uiconfig["UI Configuration<br/>[UiConfiguration.kt]"]
  node_bind["Lifecycle Binding<br/>[BindLifecycle.kt]"]
  node_view["View<br/>[View.kt]"]
  node_viewlayer["View Layer<br/>[ViewLayer.kt]"]
  node_containers["UI Containers<br/>[Container.kt]"]
  node_theme["Theme Layer"]
  node_surface["Surface Layer<br/>[SurfaceLayer.kt]"]
  node_loclayer["Localization Layer"]
end

subgraph group_localization["Localization"]
  node_localization["Localization Feature<br/>[Localization.kt]"]
  node_locservice["Localization Service"]
  node_locstate["Language State"]
end

subgraph group_web["Web Plugin"]
  node_webplugin["Web Plugin<br/>[B3WebPlugin.kt]"]
  node_webtask["Template Task"]
  node_webconfig["Web Page Config<br/>[WebPageConfig.kt]"]
  node_indexhtml["HTML Generator<br/>[IndexHtml.kt]"]
end

node_developer(("Application Developer"))
node_platform(("JVM / Wasm Host"))

node_developer -.->|"configures"| node_application
node_application -->|"registers features"| node_registry
node_registry -->|"keys entries"| node_featurekey
node_features -->|"declares key"| node_featurekey
node_application -->|"implements"| node_lifecycle
node_controller -->|"dispatches callbacks"| node_lifecycle
node_platform -->|"drives lifecycle"| node_controller
node_bind -->|"starts and stops"| node_controller
node_uiapp -->|"extends"| node_application
node_uiapp -->|"renders"| node_view
node_viewlayer -->|"renders children"| node_view
node_containers -->|"implements layer"| node_viewlayer
node_theme -->|"wraps rendering"| node_viewlayer
node_surface -->|"wraps rendering"| node_viewlayer
node_loclayer -->|"wraps rendering"| node_viewlayer
node_loclayer -->|"reads language"| node_locstate
node_localization -->|"creates service"| node_locservice
node_locservice -->|"holds state"| node_locstate
node_webplugin -->|"registers task"| node_webtask
node_webtask -->|"generates page"| node_indexhtml
node_webtask -->|"uses config"| node_webconfig
node_indexhtml -->|"reads settings"| node_webconfig

click node_application "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/core/src/commonMain/kotlin/org/b3/foundation/application/Application.kt"
click node_features "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/core/src/commonMain/kotlin/org/b3/foundation/application/Feature.kt"
click node_featurekey "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/core/src/commonMain/kotlin/org/b3/foundation/application/FeatureKey.kt"
click node_registry "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/core/src/commonMain/kotlin/org/b3/foundation/application/FeatureRegistry.kt"
click node_lifecycle "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/core/src/commonMain/kotlin/org/b3/foundation/runtime/Lifecycle.kt"
click node_controller "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/core/src/commonMain/kotlin/org/b3/foundation/runtime/LifecycleController.kt"
click node_uiapp "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/UiApplication.kt"
click node_uiconfig "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/UiConfiguration.kt"
click node_bind "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/runtime/BindLifecycle.kt"
click node_view "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/view/View.kt"
click node_viewlayer "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/view/ViewLayer.kt"
click node_containers "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/container/Container.kt"
click node_theme "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/theme/MaterialThemeLayer.kt"
click node_surface "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/surface/SurfaceLayer.kt"
click node_loclayer "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/localization/LocalizationLayer.kt"
click node_localization "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/feature/localization/src/commonMain/kotlin/org/b3/foundation/localization/Localization.kt"
click node_locservice "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/feature/localization/src/commonMain/kotlin/org/b3/foundation/localization/LocalizationService.kt"
click node_locstate "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/feature/localization/src/commonMain/kotlin/org/b3/foundation/localization/LocalizationState.kt"
click node_webplugin "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/B3WebPlugin.kt"
click node_webtask "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/GenerateTemplateTask.kt"
click node_webconfig "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/template/WebPageConfig.kt"
click node_indexhtml "https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/template/IndexHtml.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_application,node_features,node_featurekey,node_registry,node_lifecycle,node_controller toneBlue
class node_uiapp,node_uiconfig,node_bind,node_view,node_viewlayer,node_containers,node_theme,node_surface,node_loclayer toneAmber
class node_localization,node_locservice,node_locstate toneMint
class node_webplugin,node_webtask,node_webconfig,node_indexhtml toneRose
class node_developer,node_platform toneIndigo
```

## Components

### Application Core

- [Application](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/core/src/commonMain/kotlin/org/b3/foundation/application/Application.kt): `core/src/commonMain/kotlin/org/b3/foundation/application/Application.kt`
- [Feature Contracts](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/core/src/commonMain/kotlin/org/b3/foundation/application/Feature.kt): `core/src/commonMain/kotlin/org/b3/foundation/application/Feature.kt`
- [Feature Key](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/core/src/commonMain/kotlin/org/b3/foundation/application/FeatureKey.kt): `core/src/commonMain/kotlin/org/b3/foundation/application/FeatureKey.kt`
- [Feature Registry](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/core/src/commonMain/kotlin/org/b3/foundation/application/FeatureRegistry.kt): `core/src/commonMain/kotlin/org/b3/foundation/application/FeatureRegistry.kt`
- [Lifecycle API](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/core/src/commonMain/kotlin/org/b3/foundation/runtime/Lifecycle.kt): `core/src/commonMain/kotlin/org/b3/foundation/runtime/Lifecycle.kt`
- [Lifecycle Controller](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/core/src/commonMain/kotlin/org/b3/foundation/runtime/LifecycleController.kt): `core/src/commonMain/kotlin/org/b3/foundation/runtime/LifecycleController.kt`

### UI Runtime

- [UI Application](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/UiApplication.kt): `ui/src/commonMain/kotlin/org/b3/foundation/ui/UiApplication.kt`
- [UI Configuration](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/UiConfiguration.kt): `ui/src/commonMain/kotlin/org/b3/foundation/ui/UiConfiguration.kt`
- [Lifecycle Binding](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/runtime/BindLifecycle.kt): `ui/src/commonMain/kotlin/org/b3/foundation/ui/runtime/BindLifecycle.kt`
- [View](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/view/View.kt): `ui/src/commonMain/kotlin/org/b3/foundation/ui/view/View.kt`
- [View Layer](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/view/ViewLayer.kt): `ui/src/commonMain/kotlin/org/b3/foundation/ui/view/ViewLayer.kt`
- [UI Containers](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/container/Container.kt): `ui/src/commonMain/kotlin/org/b3/foundation/ui/container/Container.kt`
- [Theme Layer](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/theme/MaterialThemeLayer.kt): `ui/src/commonMain/kotlin/org/b3/foundation/ui/theme/MaterialThemeLayer.kt`
- [Surface Layer](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/surface/SurfaceLayer.kt): `ui/src/commonMain/kotlin/org/b3/foundation/ui/surface/SurfaceLayer.kt`
- [Localization Layer](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/ui/src/commonMain/kotlin/org/b3/foundation/ui/localization/LocalizationLayer.kt): `ui/src/commonMain/kotlin/org/b3/foundation/ui/localization/LocalizationLayer.kt`

### Localization

- [Localization Feature](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/feature/localization/src/commonMain/kotlin/org/b3/foundation/localization/Localization.kt): `feature/localization/src/commonMain/kotlin/org/b3/foundation/localization/Localization.kt`
- [Localization Service](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/feature/localization/src/commonMain/kotlin/org/b3/foundation/localization/LocalizationService.kt): `feature/localization/src/commonMain/kotlin/org/b3/foundation/localization/LocalizationService.kt`
- [Language State](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/feature/localization/src/commonMain/kotlin/org/b3/foundation/localization/LocalizationState.kt): `feature/localization/src/commonMain/kotlin/org/b3/foundation/localization/LocalizationState.kt`

### Web Plugin

- [Web Plugin](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/B3WebPlugin.kt): `plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/B3WebPlugin.kt`
- [Template Task](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/GenerateTemplateTask.kt): `plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/GenerateTemplateTask.kt`
- [Web Page Config](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/template/WebPageConfig.kt): `plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/template/WebPageConfig.kt`
- [HTML Generator](https://github.com/bluebikebase-inc/kmp-application-foundation/blob/feature/core-lifecycle/plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/template/IndexHtml.kt): `plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/template/IndexHtml.kt`

### Other components

- **Application Developer**
- **JVM / Wasm Host**

## Connections

- Application Developer → Application: configures
- Application → Feature Registry: registers features (evidence: `core/src/commonMain/kotlin/org/b3/foundation/application/Application.kt`)
- Feature Registry → Feature Key: keys entries (evidence: `core/src/commonMain/kotlin/org/b3/foundation/application/FeatureRegistry.kt`)
- Feature Contracts → Feature Key: declares key (evidence: `core/src/commonMain/kotlin/org/b3/foundation/application/Feature.kt`)
- Application → Lifecycle API: implements (evidence: `core/src/commonMain/kotlin/org/b3/foundation/application/Application.kt`)
- Lifecycle Controller → Lifecycle API: dispatches callbacks (evidence: `core/src/commonMain/kotlin/org/b3/foundation/runtime/LifecycleController.kt`)
- JVM / Wasm Host → Lifecycle Controller: drives lifecycle
- Lifecycle Binding → Lifecycle Controller: starts and stops (evidence: `ui/src/commonMain/kotlin/org/b3/foundation/ui/runtime/BindLifecycle.kt`)
- UI Application → Application: extends (evidence: `ui/src/commonMain/kotlin/org/b3/foundation/ui/UiApplication.kt`)
- UI Application → View: renders (evidence: `ui/src/commonMain/kotlin/org/b3/foundation/ui/UiApplication.kt`)
- View Layer → View: renders children (evidence: `ui/src/commonMain/kotlin/org/b3/foundation/ui/view/ViewLayer.kt`)
- UI Containers → View Layer: implements layer (evidence: `ui/src/commonMain/kotlin/org/b3/foundation/ui/container/Container.kt`)
- Theme Layer → View Layer: wraps rendering (evidence: `ui/src/commonMain/kotlin/org/b3/foundation/ui/theme/MaterialThemeLayer.kt`)
- Surface Layer → View Layer: wraps rendering (evidence: `ui/src/commonMain/kotlin/org/b3/foundation/ui/surface/SurfaceLayer.kt`)
- Localization Layer → View Layer: wraps rendering (evidence: `ui/src/commonMain/kotlin/org/b3/foundation/ui/localization/LocalizationLayer.kt`)
- Localization Layer → Language State: reads language (evidence: `ui/src/commonMain/kotlin/org/b3/foundation/ui/localization/LocalizationLayer.kt`)
- Localization Feature → Localization Service: creates service (evidence: `feature/localization/src/commonMain/kotlin/org/b3/foundation/localization/Localization.kt`)
- Localization Service → Language State: holds state (evidence: `feature/localization/src/commonMain/kotlin/org/b3/foundation/localization/LocalizationService.kt`)
- Web Plugin → Template Task: registers task (evidence: `plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/B3WebPlugin.kt`)
- Template Task → HTML Generator: generates page (evidence: `plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/GenerateTemplateTask.kt`)
- Template Task → Web Page Config: uses config (evidence: `plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/GenerateTemplateTask.kt`)
- HTML Generator → Web Page Config: reads settings (evidence: `plugins/web/src/main/kotlin/org/b3/foundation/plugin/web/template/IndexHtml.kt`)
