# guilhermebanik/sorceweaver architecture

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

- Interactive diagram: https://gitdiagram.com/guilhermebanik/sorceweaver
- Repository: https://github.com/guilhermebanik/sorceweaver

## Overview

1. **Project shape**
   - This is a **Kotlin Multiplatform + Compose Multiplatform** app.
   - It targets **Android, Desktop/JVM, Web (JS and Wasm)** from one shared codebase under `composeApp`.

2. **High-level layering**
   - The repository is split into:
     - **shared application/domain code** in `commonMain`
     - **platform entry points and adapters** in `androidMain`, `jvmMain`, `jsMain`, `wasmJsMain`, and `webMain`
     - **platform resources** in Android and web-specific resource folders
   - The shared code appears to contain the main product logic, while platform folders mainly bootstrap the app.

3. **Shared UI/application shell**
   - `composeApp/src/commonMain/kotlin/io/sorceweaver/app/App.kt` is the shared Compose entry point for the UI.
   - `Platform.kt` in common code plus platform-specific `Platform.*.kt` files indicate an **expect/actual-style platform abstraction** for shared UI behavior such as naming or environment differences.

4. **Core domain subsystem: dice expression engine**
   - The most important non-UI subsystem is under `domain/engine/ast`.
   - It is structured like a classic expression pipeline:
     - **Lexer**: tokenizes an input dice expression
     - **Parser**: builds an AST
     - **AST nodes**: represent expression constructs and evaluation behavior
   - This strongly suggests the app’s central purpose is to **parse and evaluate dice-roll expressions**.

5. **AST/node model**
   - The node types show the supported expression features:
     - `DiceNode` for dice rolls
     - `NumberNode` for numeric literals
     - `VarNode` for variables
     - `MathNode` for arithmetic
     - `DropLowestNode` / `KeepHighestNode` for dice modifiers
     - `EmptyNode` for fallback/invalid/blank cases
   - These nodes form the internal evaluation tree used by the engine.

6. **Use-case boundary**
   - `domain/usecases/RollDiceUseCase.kt` is the main orchestration boundary between UI and engine.
   - The likely flow is: user input → use case → lexer/parser/AST evaluation → result returned to UI.
   - This is the clearest place to draw a boundary between presentation and domain logic.

7. **Domain models**
   - `domain/models/Token.kt` represents lexer output.
   - `domain/models/EvaluationResult.kt` represents the computed outcome of a roll.
   - These are the data contracts between the lexer/parser/evaluator and the rest of the app.

8. **Platform-specific entry points**
   - **Android**: `MainActivity.kt` and `AndroidManifest.xml` start the app on Android.
   - **Desktop/JVM**: `jvmMain/kotlin/.../main.kt` is the desktop launcher.
   - **Web**: `webMain/kotlin/.../main.kt` plus `webMain/resources/index.html` and `styles.css` provide the browser entry point and shell.
   - **JS/Wasm** targets also have platform stubs, likely to satisfy shared platform abstraction and browser-specific packaging.

9. **Resource split**
   - Shared Compose resources live in `commonMain/composeResources`.
   - Android has conventional `res/` assets and launchers.
   - Web has its own HTML/CSS shell.
   - This means the app’s visual structure is mostly shared, but packaging and launch surfaces differ by target.

10. **Utilities**
   - `utils/Extensions/JsonHelpers.kt` suggests some helper logic for JSON-related transformations.
   - It is ancillary to the main engine/UI flow and likely supports serialization or formatting if needed.

11. **Testing**
   - `commonTest` contains shared tests, which implies the critical engine/domain logic is intended to be validated once and reused across targets.
   - For architecture diagrams, this belongs around the shared domain layer rather than any specific platform.

12. **Build/tooling**
   - The repo is Gradle-based (`build.gradle.kts`, `settings.gradle.kts`, version catalog, wrapper).
   - The build is organized around KMP targets rather than separate codebases per platform, which is key to the architecture: one shared engine/UI core, multiple thin platform launchers.

13. **Notably absent**
   - There is no visible backend, database, or external service integration in the tree.
   - The architecture appears to be **fully client-side**, with all core logic running locally on each target.

14. **Recommended diagram boundaries**
   - Draw one central **shared KMP core** containing UI + dice engine.
   - Draw separate **platform adapters/entry points** for Android, Desktop JVM, and Web/Wasm/JS.
   - Inside the core, separate **presentation/UI**, **use case**, and **engine/domain** layers.
   - Show the data flow from user input to lexer/parser/AST evaluation to `EvaluationResult`.

Main entry points: [`composeApp/src/commonMain/kotlin/io/sorceweaver/app/App.kt`](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/App.kt) (App shell), [`composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/Node.kt`](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/Node.kt) (AST nodes), [`composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/usecases/RollDiceUseCase.kt`](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/usecases/RollDiceUseCase.kt) (Roll use case), [`build.gradle.kts`](https://github.com/guilhermebanik/sorceweaver/blob/main/build.gradle.kts) (Gradle build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_shared_core["Shared KMP core"]
  node_node_app["App shell<br/>Compose entry<br/>[App.kt]"]
  node_node_platform_common["Platform API<br/>expect contract<br/>[Platform.kt]"]
  node_node_usecase["Roll use case<br/>application use case<br/>[RollDiceUseCase.kt]"]
  node_node_lexer["Lexer<br/>tokenizer<br/>[Lexer.kt]"]
  node_node_parser["Parser<br/>AST builder<br/>[Parser.kt]"]
  node_node_ast_nodes{{"AST nodes<br/>expression model<br/>[Node.kt]"}}
  node_node_dice_node["Dice node<br/>roll node<br/>[DiceNode.kt]"]
  node_node_math_node["Math node<br/>operator node<br/>[MathNode.kt]"]
  node_node_modifiers["Roll modifiers<br/>modifier nodes<br/>[DropLowestNode.kt]"]
  node_node_value_nodes["Value nodes<br/>literal/var nodes<br/>[NumberNode.kt]"]
  node_node_token["Token<br/>lexer model<br/>[Token.kt]"]
  node_node_result["Roll result<br/>domain model"]
  node_node_json_helpers["JSON helpers<br/>[JsonHelpers.kt]"]
end

subgraph group_group_platforms["Platform entry points"]
  node_node_android["Android app<br/>android launcher<br/>[MainActivity.kt]"]
  node_node_jvm["Desktop app<br/>jvm launcher<br/>[main.kt]"]
  node_node_web["Web app<br/>web launcher<br/>[main.kt]"]
  node_node_js_platform["JS platform<br/>js adapter<br/>[Platform.js.kt]"]
  node_node_wasm_platform["Wasm platform<br/>wasm adapter<br/>[Platform.wasmJs.kt]"]
end

subgraph group_group_resources["Resources"]
  node_node_common_resources["Shared resources<br/>compose resources"]
  node_node_android_resources["Android resources<br/>[strings.xml]"]
  node_node_web_resources["Web shell<br/>html/css shell<br/>[index.html]"]
end

subgraph group_group_tooling["Build and tests"]
  node_node_common_test["Shared tests<br/>common test"]
  node_node_build["Gradle build<br/>build config<br/>[build.gradle.kts]"]
end

node_node_android -->|"starts"| node_node_app
node_node_jvm -->|"starts"| node_node_app
node_node_web -->|"starts"| node_node_app
node_node_app -->|"calls"| node_node_usecase
node_node_usecase -->|"tokenizes"| node_node_lexer
node_node_lexer -->|"produces"| node_node_token
node_node_usecase -->|"parses"| node_node_parser
node_node_parser -->|"builds"| node_node_ast_nodes
node_node_ast_nodes -->|"includes"| node_node_dice_node
node_node_ast_nodes -->|"includes"| node_node_math_node
node_node_ast_nodes -->|"includes"| node_node_modifiers
node_node_ast_nodes -->|"includes"| node_node_value_nodes
node_node_usecase -->|"returns"| node_node_result
node_node_app -->|"reads"| node_node_platform_common
node_node_platform_common -->|"actualized by"| node_node_js_platform
node_node_platform_common -->|"actualized by"| node_node_wasm_platform
node_node_app -->|"uses"| node_node_common_resources
node_node_android -->|"packages"| node_node_android_resources
node_node_web -->|"packages"| node_node_web_resources
node_node_common_test -->|"validates"| node_node_usecase
node_node_build -->|"configures"| node_node_app
node_node_build -->|"configures"| node_node_android
node_node_build -->|"configures"| node_node_jvm
node_node_build -->|"configures"| node_node_web

click node_node_app "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/App.kt"
click node_node_platform_common "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/Platform.kt"
click node_node_usecase "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/usecases/RollDiceUseCase.kt"
click node_node_lexer "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/Lexer.kt"
click node_node_parser "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/Parser.kt"
click node_node_ast_nodes "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/Node.kt"
click node_node_dice_node "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/DiceNode.kt"
click node_node_math_node "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/MathNode.kt"
click node_node_modifiers "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/DropLowestNode.kt"
click node_node_value_nodes "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/NumberNode.kt"
click node_node_token "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/models/Token.kt"
click node_node_result "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/models/EvaluationResult.kt"
click node_node_json_helpers "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/utils/Extensions/JsonHelpers.kt"
click node_node_android "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/androidMain/kotlin/io/sorceweaver/app/MainActivity.kt"
click node_node_jvm "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/jvmMain/kotlin/io/sorceweaver/app/main.kt"
click node_node_web "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/webMain/kotlin/io/sorceweaver/app/main.kt"
click node_node_js_platform "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/jsMain/kotlin/io/sorceweaver/app/Platform.js.kt"
click node_node_wasm_platform "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/wasmJsMain/kotlin/io/sorceweaver/app/Platform.wasmJs.kt"
click node_node_common_resources "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/composeResources/drawable/compose-multiplatform.xml"
click node_node_android_resources "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/androidMain/res/values/strings.xml"
click node_node_web_resources "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/webMain/resources/index.html"
click node_node_common_test "https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonTest/kotlin/io/sorceweaver/app/ComposeAppCommonTest.kt"
click node_node_build "https://github.com/guilhermebanik/sorceweaver/blob/main/build.gradle.kts"

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_node_app,node_node_platform_common,node_node_usecase,node_node_lexer,node_node_parser,node_node_ast_nodes,node_node_dice_node,node_node_math_node,node_node_modifiers,node_node_value_nodes,node_node_token,node_node_result,node_node_json_helpers toneBlue
class node_node_android,node_node_jvm,node_node_web,node_node_js_platform,node_node_wasm_platform toneAmber
class node_node_common_resources,node_node_android_resources,node_node_web_resources toneMint
class node_node_common_test,node_node_build toneRose
```

## Components

### Shared KMP core

Common Compose UI, shared domain logic, and reusable utilities.

- [App shell](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/App.kt): Compose entry · Shared Compose application entry point. · `composeApp/src/commonMain/kotlin/io/sorceweaver/app/App.kt`
- [Platform API](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/Platform.kt): expect contract · Shared platform abstraction used by the app shell. · `composeApp/src/commonMain/kotlin/io/sorceweaver/app/Platform.kt`
- [Roll use case](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/usecases/RollDiceUseCase.kt): application use case · Orchestrates user input into dice roll evaluation. · `composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/usecases/RollDiceUseCase.kt`
- [Lexer](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/Lexer.kt): tokenizer · Converts dice expressions into tokens. · `composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/Lexer.kt`
- [Parser](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/Parser.kt): AST builder · Builds an expression tree from tokens. · `composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/Parser.kt`
- [AST nodes](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/Node.kt): expression model · Core node types for dice, math, variables, and modifiers. · `composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/Node.kt`
- [Dice node](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/DiceNode.kt): roll node · Represents dice rolls inside the expression tree. · `composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/DiceNode.kt`
- [Math node](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/MathNode.kt): operator node · Represents arithmetic expressions. · `composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/MathNode.kt`
- [Roll modifiers](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/DropLowestNode.kt): modifier nodes · Keeps highest or drops lowest dice results. · `composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/DropLowestNode.kt`
- [Value nodes](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/NumberNode.kt): literal/var nodes · Numeric, variable, and empty fallback nodes. · `composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/NumberNode.kt`
- [Token](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/models/Token.kt): lexer model · Token contract produced by the lexer. · `composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/models/Token.kt`
- [Roll result](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/models/EvaluationResult.kt): domain model · Evaluated outcome returned to the UI. · `composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/models/EvaluationResult.kt`
- [JSON helpers](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/kotlin/io/sorceweaver/app/utils/Extensions/JsonHelpers.kt): utility · Ancillary helpers for JSON-related transformations. · `composeApp/src/commonMain/kotlin/io/sorceweaver/app/utils/Extensions/JsonHelpers.kt`

### Platform entry points

Thin launchers and adapters for each target runtime.

- [Android app](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/androidMain/kotlin/io/sorceweaver/app/MainActivity.kt): android launcher · Android entry point and app manifest. · `composeApp/src/androidMain/kotlin/io/sorceweaver/app/MainActivity.kt`
- [Desktop app](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/jvmMain/kotlin/io/sorceweaver/app/main.kt): jvm launcher · JVM desktop entry point. · `composeApp/src/jvmMain/kotlin/io/sorceweaver/app/main.kt`
- [Web app](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/webMain/kotlin/io/sorceweaver/app/main.kt): web launcher · Browser entry point for the web target. · `composeApp/src/webMain/kotlin/io/sorceweaver/app/main.kt`
- [JS platform](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/jsMain/kotlin/io/sorceweaver/app/Platform.js.kt): js adapter · JS-specific platform actual for shared code. · `composeApp/src/jsMain/kotlin/io/sorceweaver/app/Platform.js.kt`
- [Wasm platform](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/wasmJsMain/kotlin/io/sorceweaver/app/Platform.wasmJs.kt): wasm adapter · Wasm-specific platform actual for shared code. · `composeApp/src/wasmJsMain/kotlin/io/sorceweaver/app/Platform.wasmJs.kt`

### Resources

Platform-specific and shared visual/resource packaging.

- [Shared resources](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonMain/composeResources/drawable/compose-multiplatform.xml): compose resources · Common Compose Multiplatform resources. · `composeApp/src/commonMain/composeResources/drawable/compose-multiplatform.xml`
- [Android resources](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/androidMain/res/values/strings.xml): android resources · Android drawables, launcher assets, and strings. · `composeApp/src/androidMain/res/values/strings.xml`
- [Web shell](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/webMain/resources/index.html): html/css shell · Browser HTML entry and styling. · `composeApp/src/webMain/resources/index.html`

### Build and tests

Repository build setup and shared test surface.

- [Shared tests](https://github.com/guilhermebanik/sorceweaver/blob/main/composeApp/src/commonTest/kotlin/io/sorceweaver/app/ComposeAppCommonTest.kt): common test · Cross-target test surface for shared logic. · `composeApp/src/commonTest/kotlin/io/sorceweaver/app/ComposeAppCommonTest.kt`
- [Gradle build](https://github.com/guilhermebanik/sorceweaver/blob/main/build.gradle.kts): build config · Project build and module configuration. · `build.gradle.kts`

## Connections

- Android app → App shell: starts · Android launches the shared app shell.
- Desktop app → App shell: starts · Desktop launcher boots the shared UI.
- Web app → App shell: starts · Web launcher boots the shared UI.
- App shell → Roll use case: calls · UI delegates roll handling to application logic.
- Roll use case → Lexer: tokenizes · Use case begins by tokenizing the expression.
- Lexer → Token: produces · Lexer emits token values.
- Roll use case → Parser: parses · Use case feeds tokens into the parser.
- Parser → AST nodes: builds · Parser assembles the expression tree from node types.
- AST nodes → Dice node: includes · Dice expression node.
- AST nodes → Math node: includes · Arithmetic node family.
- AST nodes → Roll modifiers: includes · Keeps highest and drops lowest nodes.
- AST nodes → Value nodes: includes · Literal, variable, and empty nodes.
- Roll use case → Roll result: returns · Domain evaluation result is returned upward.
- App shell → Platform API: reads · Shared UI uses platform abstraction.
- Platform API → JS platform: actualized by · JS target provides a platform implementation.
- Platform API → Wasm platform: actualized by · Wasm target provides a platform implementation.
- App shell → Shared resources: uses · Shared UI consumes common Compose resources.
- Android app → Android resources: packages · Android target uses native resources.
- Web app → Web shell: packages · Web target uses HTML and CSS shell files.
- Shared tests → Roll use case: validates · Shared tests exercise core domain behavior.
- Gradle build → App shell: configures · Gradle wires the shared app module.
- Gradle build → Android app: configures · Gradle configures Android target.
- Gradle build → Desktop app: configures · Gradle configures JVM desktop target.
- Gradle build → Web app: configures · Gradle configures web target.
