# inckie/aisuper architecture

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

- Interactive diagram: https://gitdiagram.com/inckie/aisuper
- Repository: https://github.com/inckie/aisuper

## Overview

AI Super App is a multiplatform runtime for loading and executing applets: artifact resources and manifests feed an applet/feature lifecycle, sandboxed JavaScript and permission-guarded modules, state storage, and UI rendering. Users interact through Compose, Android widgets, a terminal app, or a React headless-session client; the README also documents a REST/SSE server and headless sessions. The principal path is applet selection/loading, feature execution, then rendered interaction. Some documented subsystems were not sampled, so their links are documented rather than inferred from unseen implementation.

Main entry points: [`kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/Applet.kt`](https://github.com/inckie/aisuper/blob/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/Applet.kt) (Applet lifecycle), [`kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/Feature.kt`](https://github.com/inckie/aisuper/blob/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/Feature.kt) (Feature runtime), [`kotlin/composeApp/src/commonMain/kotlin/com/damn/aisuper/App.kt`](https://github.com/inckie/aisuper/blob/master/kotlin/composeApp/src/commonMain/kotlin/com/damn/aisuper/App.kt) (Compose application), [`client-react/src/App.tsx`](https://github.com/inckie/aisuper/blob/master/client-react/src/App.tsx) (React client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Applet runtime"]
  node_providers["Resource providers"]
  node_applet["Applet lifecycle<br/>[Applet.kt]"]
  node_feature["Feature runtime<br/>[Feature.kt]"]
  node_storage[("Scoped state<br/>[StateStorage.kt]")]
  node_storage_bindings["JS storage bindings<br/>[StorageBindings.kt]"]
  node_headless["Headless sessions"]
end

subgraph group_execution["Execution services"]
  node_js_engine["JS engines"]
  node_modules["Feature modules"]
  node_module_examples["HTTP audio GPS"]
  node_mcp["MCP harness"]
end

subgraph group_presentation["User interfaces"]
  node_compose_app["Compose application<br/>[App.kt]"]
  node_compose_renderers["Compose renderers"]
  node_android_widgets["Android widgets"]
  node_terminal["Terminal UI<br/>[Main.kt]"]
  node_react_client["React client<br/>[App.tsx]"]
  node_widget_renderer["Widget renderer<br/>[WidgetRenderer.tsx]"]
end

subgraph group_access["Remote access"]
  node_server["REST SSE server"]
  node_api["Headless API<br/>[api.ts]"]
end

node_user(("Applet user"))
node_artifact["Applet artifacts"]

node_user -->|"uses"| node_compose_app
node_user -->|"uses"| node_terminal
node_user -->|"uses"| node_react_client
node_artifact -->|"loaded by"| node_providers
node_providers -->|"supplies resources"| node_applet
node_compose_app -->|"creates"| node_applet
node_applet -->|"launches"| node_feature
node_applet -->|"creates stores"| node_storage
node_feature -->|"scopes state"| node_storage
node_feature -->|"registers modules"| node_modules
node_feature -.->|"runs scripts"| node_js_engine
node_storage_bindings -->|"reads and writes"| node_storage
node_modules -.->|"includes"| node_module_examples
node_compose_app -->|"renders layouts"| node_compose_renderers
node_android_widgets -->|"manages applets"| node_applet
node_terminal -->|"loads applet"| node_applet
node_react_client -->|"renders widgets"| node_widget_renderer
node_react_client -.->|"calls API"| node_api
node_headless -.->|"wraps runtime"| node_applet
node_server -.->|"serves sessions"| node_headless
node_mcp -.->|"exposes tools"| node_applet

click node_providers "https://github.com/inckie/aisuper/tree/master/kotlin/applet-provider/src"
click node_applet "https://github.com/inckie/aisuper/blob/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/Applet.kt"
click node_feature "https://github.com/inckie/aisuper/blob/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/Feature.kt"
click node_storage "https://github.com/inckie/aisuper/blob/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/storage/StateStorage.kt"
click node_storage_bindings "https://github.com/inckie/aisuper/blob/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/StorageBindings.kt"
click node_headless "https://github.com/inckie/aisuper/tree/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/headless"
click node_js_engine "https://github.com/inckie/aisuper/tree/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/engine"
click node_modules "https://github.com/inckie/aisuper/tree/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/modules"
click node_module_examples "https://github.com/inckie/aisuper/tree/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/modules/impl"
click node_mcp "https://github.com/inckie/aisuper/tree/master/kotlin/shared/src/jvmMain/kotlin/com/damn/aisuper/harness"
click node_compose_app "https://github.com/inckie/aisuper/blob/master/kotlin/composeApp/src/commonMain/kotlin/com/damn/aisuper/App.kt"
click node_compose_renderers "https://github.com/inckie/aisuper/tree/master/kotlin/composeApp/src/commonMain/kotlin/com/damn/aisuper/layout/frontend"
click node_android_widgets "https://github.com/inckie/aisuper/tree/master/kotlin/composeApp/src/androidMain/kotlin/com/damn/aisuper/widget"
click node_terminal "https://github.com/inckie/aisuper/blob/master/kotlin/lanternaApp/src/main/kotlin/com/damn/aisuper/lanterna/Main.kt"
click node_react_client "https://github.com/inckie/aisuper/blob/master/client-react/src/App.tsx"
click node_widget_renderer "https://github.com/inckie/aisuper/blob/master/client-react/src/WidgetRenderer.tsx"
click node_server "https://github.com/inckie/aisuper/tree/master/kotlin/server/src/main/kotlin/com/damn/aisuper/server"
click node_api "https://github.com/inckie/aisuper/blob/master/client-react/src/api.ts"

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_providers,node_applet,node_feature,node_storage,node_storage_bindings,node_headless,node_user toneBlue
class node_js_engine,node_modules,node_module_examples,node_mcp toneAmber
class node_compose_app,node_compose_renderers,node_android_widgets,node_terminal,node_react_client,node_widget_renderer toneMint
class node_server,node_api toneRose
class node_artifact toneIndigo
```

## Components

### Applet runtime

- [Resource providers](https://github.com/inckie/aisuper/tree/master/kotlin/applet-provider/src): `kotlin/applet-provider/src`
- [Applet lifecycle](https://github.com/inckie/aisuper/blob/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/Applet.kt): `kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/Applet.kt`
- [Feature runtime](https://github.com/inckie/aisuper/blob/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/Feature.kt): `kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/Feature.kt`
- [Scoped state](https://github.com/inckie/aisuper/blob/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/storage/StateStorage.kt): `kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/storage/StateStorage.kt`
- [JS storage bindings](https://github.com/inckie/aisuper/blob/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/StorageBindings.kt): `kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/StorageBindings.kt`
- [Headless sessions](https://github.com/inckie/aisuper/tree/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/headless): `kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/headless`

### Execution services

- [JS engines](https://github.com/inckie/aisuper/tree/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/engine): `kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/engine`
- [Feature modules](https://github.com/inckie/aisuper/tree/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/modules): `kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/modules`
- [HTTP audio GPS](https://github.com/inckie/aisuper/tree/master/kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/modules/impl): `kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/modules/impl`
- [MCP harness](https://github.com/inckie/aisuper/tree/master/kotlin/shared/src/jvmMain/kotlin/com/damn/aisuper/harness): `kotlin/shared/src/jvmMain/kotlin/com/damn/aisuper/harness`

### User interfaces

- [Compose application](https://github.com/inckie/aisuper/blob/master/kotlin/composeApp/src/commonMain/kotlin/com/damn/aisuper/App.kt): `kotlin/composeApp/src/commonMain/kotlin/com/damn/aisuper/App.kt`
- [Compose renderers](https://github.com/inckie/aisuper/tree/master/kotlin/composeApp/src/commonMain/kotlin/com/damn/aisuper/layout/frontend): `kotlin/composeApp/src/commonMain/kotlin/com/damn/aisuper/layout/frontend`
- [Android widgets](https://github.com/inckie/aisuper/tree/master/kotlin/composeApp/src/androidMain/kotlin/com/damn/aisuper/widget): `kotlin/composeApp/src/androidMain/kotlin/com/damn/aisuper/widget`
- [Terminal UI](https://github.com/inckie/aisuper/blob/master/kotlin/lanternaApp/src/main/kotlin/com/damn/aisuper/lanterna/Main.kt): `kotlin/lanternaApp/src/main/kotlin/com/damn/aisuper/lanterna/Main.kt`
- [React client](https://github.com/inckie/aisuper/blob/master/client-react/src/App.tsx): `client-react/src/App.tsx`
- [Widget renderer](https://github.com/inckie/aisuper/blob/master/client-react/src/WidgetRenderer.tsx): `client-react/src/WidgetRenderer.tsx`

### Remote access

- [REST SSE server](https://github.com/inckie/aisuper/tree/master/kotlin/server/src/main/kotlin/com/damn/aisuper/server): `kotlin/server/src/main/kotlin/com/damn/aisuper/server`
- [Headless API](https://github.com/inckie/aisuper/blob/master/client-react/src/api.ts): `client-react/src/api.ts`

### Other components

- **Applet user**
- **Applet artifacts**

## Connections

- Applet user → Compose application: uses
- Applet user → Terminal UI: uses
- Applet user → React client: uses
- Applet artifacts → Resource providers: loaded by
- Resource providers → Applet lifecycle: supplies resources (evidence: `kotlin/applet-provider/src/commonMain/kotlin/com/damn/aisuper/applet/ComposeAppletProvider.kt`)
- Compose application → Applet lifecycle: creates (evidence: `kotlin/composeApp/src/commonMain/kotlin/com/damn/aisuper/App.kt`)
- Applet lifecycle → Feature runtime: launches (evidence: `kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/Applet.kt`)
- Applet lifecycle → Scoped state: creates stores (evidence: `kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/Applet.kt`)
- Feature runtime → Scoped state: scopes state (evidence: `kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/Feature.kt`)
- Feature runtime → Feature modules: registers modules (evidence: `kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/Feature.kt`)
- Feature runtime → JS engines: runs scripts
- JS storage bindings → Scoped state: reads and writes (evidence: `kotlin/shared/src/commonMain/kotlin/com/damn/aisuper/runtime/StorageBindings.kt`)
- Feature modules → HTTP audio GPS: includes
- Compose application → Compose renderers: renders layouts (evidence: `kotlin/composeApp/src/commonMain/kotlin/com/damn/aisuper/App.kt`)
- Android widgets → Applet lifecycle: manages applets (evidence: `kotlin/composeApp/src/androidMain/kotlin/com/damn/aisuper/widget/WidgetAppletManager.kt`)
- Terminal UI → Applet lifecycle: loads applet (evidence: `kotlin/lanternaApp/src/main/kotlin/com/damn/aisuper/lanterna/Main.kt`)
- React client → Widget renderer: renders widgets (evidence: `client-react/src/App.tsx`)
- React client → Headless API: calls API (evidence: `client-react/src/App.tsx`)
- Headless sessions → Applet lifecycle: wraps runtime
- REST SSE server → Headless sessions: serves sessions
- MCP harness → Applet lifecycle: exposes tools