How ramonbouckaert/countback works
Project type and purpose
• This is a client-focused simulation tool built with Kotlin Multiplatform and a React single-page UI.
• Purpose: Run Hare-Clark countback simulations for ACT elections in the browser via a web worker, with no external server dependencies.
File structure
• Top-level build/config files: Gradle wrappers, build.gradle.kts, settings.gradle.kts, .gitignore, LICENSE.
• src/commonMain: Core Kotlin library containing election data models (Ballot, Candidate, Election, etc.), countback logic (Countback.kt, ACTDataLoader.kt, Utils), and an in-memory store.
• src/jsMain: Platform-specific Kotlin code for JavaScript—FileLoader, WebWorker glue.
• src/jvmMain: (Optional) JVM implementation of file loading—suggests potential CLI or batch use.
• src/commonMain/client: A Create-React-App scaffold containing package.json, Webpack/Jest configs, HTML/CSS assets, TypeScript React components (CountbackApp.tsx, DeviceSelect.tsx), and API wrappers (api.ts).
• Tests in commonTest, jsTest, jvmTest mirror the three targets to validate logic across platforms.
Key insights from README
• The heart of the system is written in Kotlin and compiled to JavaScript (and optionally JVM).
• Business logic runs inside a browser Web Worker to keep the UI responsive.
• Build pipeline: Gradle compiles Kotlin targets and packages the React app into dist/.
Components and their interactions
a. Main components
• React UI (src/commonMain/client/src): user interface for selecting data files, candidates, and triggering countbacks.
• API layer (api.ts + WebWorkerRequest/Response classes): marshals requests and responses between the UI and the Web Worker.
• Web Worker (compiled from commonMain + jsMain): executes heavy countback simulation using Kotlin logic.
• Core Kotlin library (commonMain/kotlin): models, algorithms, data loaders, in-memory store.
• File loader modules (JsFileLoader, JvmFileLoader): platform adapters to read election data files.
• Build/CI: Gradle (build.gradle.kts), GitHub Actions (build.yml) to compile and test all targets.
b. Relationships & data flow
1. User interacts with React UI → selects data / enters parameters.
2. UI invokes api.ts → sends a WebWorkerRequest to the worker thread.
3. Web Worker (jsMain + commonMain) loads data via JsFileLoader → populates BallotStore.
4. Business logic (Countback.kt) computes preference distributions and returns WebWorkerResponse.
5. UI receives the response, renders results.
c. Architectural patterns & design principles
• Kotlin Multiplatform: maximizes code reuse (business logic) across JS and JVM.
• Web Worker pattern: isolates CPU-intensive operations.
• Modular separation: UI vs. core logic vs. platform adapters.
• Single-Page Application: Webpack bundle, React frontend.
d. Key technologies
• Kotlin MPP, Gradle Kotlin DSL, Webpack, Babel, Jest, React, TypeScript, Create-React-App, Web Worker API.