How guilhermebanik/sorceweaver works
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: App.kt App shell · Node.kt AST nodes · RollDiceUseCase.kt Roll use case · build.gradle.kts Gradle build
Components 23
Shared KMP core
Common Compose UI, shared domain logic, and reusable utilities.
- App shell · Shared Compose application entry point.
composeApp/src/commonMain/kotlin/io/sorceweaver/app/App.kt - Platform API · Shared platform abstraction used by the app shell.
composeApp/src/commonMain/kotlin/io/sorceweaver/app/Platform.kt - Roll use case · Orchestrates user input into dice roll evaluation.
composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/usecases/RollDiceUseCase.kt - Lexer · Converts dice expressions into tokens.
composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/Lexer.kt - Parser · Builds an expression tree from tokens.
composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/Parser.kt - AST nodes · Core node types for dice, math, variables, and modifiers.
composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/Node.kt - Dice node · Represents dice rolls inside the expression tree.
composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/DiceNode.kt - Math node · Represents arithmetic expressions.
composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/MathNode.kt - Roll modifiers · Keeps highest or drops lowest dice results.
composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/DropLowestNode.kt - Value nodes · Numeric, variable, and empty fallback nodes.
composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/engine/ast/nodes/NumberNode.kt - Token · Token contract produced by the lexer.
composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/models/Token.kt - Roll result · Evaluated outcome returned to the UI.
composeApp/src/commonMain/kotlin/io/sorceweaver/app/domain/models/EvaluationResult.kt - JSON helpers · 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 · Android entry point and app manifest.
composeApp/src/androidMain/kotlin/io/sorceweaver/app/MainActivity.kt - Desktop app · JVM desktop entry point.
composeApp/src/jvmMain/kotlin/io/sorceweaver/app/main.kt - Web app · Browser entry point for the web target.
composeApp/src/webMain/kotlin/io/sorceweaver/app/main.kt - JS platform · JS-specific platform actual for shared code.
composeApp/src/jsMain/kotlin/io/sorceweaver/app/Platform.js.kt - Wasm platform · 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 · Common Compose Multiplatform resources.
composeApp/src/commonMain/composeResources/drawable/compose-multiplatform.xml - Android resources · Android drawables, launcher assets, and strings.
composeApp/src/androidMain/res/values/strings.xml - Web shell · Browser HTML entry and styling.
composeApp/src/webMain/resources/index.html
Build and tests
Repository build setup and shared test surface.
- Shared tests · Cross-target test surface for shared logic.
composeApp/src/commonTest/kotlin/io/sorceweaver/app/ComposeAppCommonTest.kt - Gradle build · Project build and module configuration.
build.gradle.kts
Connections 24
- 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.