# ramonbouckaert/countback architecture

> Architecture diagram of the GitHub repository ramonbouckaert/countback, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ramonbouckaert/countback
- Repository: https://github.com/ramonbouckaert/countback

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        ReactUI["React SPA UI"]:::presentation
        API_TS["API Layer (api.ts)"]:::presentation
    end

    %% Execution Layer
    subgraph "Execution Layer"
        direction TB
        Worker["Web Worker Thread\n(WebWorker.kt)"]:::logic
        Core["Kotlin Core Library"]:::logic
        WRQ["WebWorkerRequest.kt"]:::logic
        WRP["WebWorkerResponse.kt"]:::logic
    end

    %% Data Layer
    subgraph "Data & Storage Layer"
        direction TB
        BS["BallotStore.kt"]:::data
        IMS["InMemoryBallotStore.kt"]:::data
        FileJS["JsFileLoader.kt"]:::data
        FileJVM["JvmFileLoader.kt"]:::data
    end

    %% JVM CLI/Batch
    subgraph "JVM CLI/Batch"
        direction TB
        CLI["CLI Entry"]:::logic
    end

    %% Build & CI
    subgraph "Build & CI"
        direction TB
        Gradle["Gradle Build"]:::build
        CI["GitHub Actions"]:::build
    end

    %% Relationships
    ReactUI -->|"user actions"| API_TS
    API_TS -->|"WebWorkerRequest"| Worker
    Worker -->|"executes logic"| Core
    Core -->|"uses"| BS
    Core -->|"uses"| IMS
    Worker -->|"loads data"| FileJS
    CLI -->|"loads data"| FileJVM
    Worker -->|"returns WebWorkerResponse"| API_TS
    API_TS -->|"renders results"| ReactUI

    Gradle -->|"compiles targets"| Core
    Gradle -->|"packages SPA"| ReactUI
    CI -->|"triggers"| Gradle

    %% Click Events
    click ReactUI "https://github.com/ramonbouckaert/countback/tree/main/src/commonMain/client/src"
    click API_TS "https://github.com/ramonbouckaert/countback/blob/main/src/commonMain/client/src/api.ts"
    click Worker "https://github.com/ramonbouckaert/countback/blob/main/src/jsMain/kotlin/io/bouckaert/countback/WebWorker.kt"
    click WRQ "https://github.com/ramonbouckaert/countback/blob/main/src/commonMain/kotlin/io/bouckaert/countback/WebWorkerRequest.kt"
    click WRP "https://github.com/ramonbouckaert/countback/blob/main/src/commonMain/kotlin/io/bouckaert/countback/WebWorkerResponse.kt"
    click Core "https://github.com/ramonbouckaert/countback/tree/main/src/commonMain/kotlin/io/bouckaert/countback"
    click BS "https://github.com/ramonbouckaert/countback/blob/main/src/commonMain/kotlin/io/bouckaert/countback/store/BallotStore.kt"
    click IMS "https://github.com/ramonbouckaert/countback/blob/main/src/commonMain/kotlin/io/bouckaert/countback/store/InMemoryBallotStore.kt"
    click FileJS "https://github.com/ramonbouckaert/countback/blob/main/src/jsMain/kotlin/io/bouckaert/countback/JsFileLoader.kt"
    click FileJVM "https://github.com/ramonbouckaert/countback/blob/main/src/jvmMain/kotlin/io/bouckaert/countback/JvmFileLoader.kt"

    %% Styles
    classDef presentation fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef logic fill:#C8E6C9,stroke:#2E7D32,color:#1B5E20
    classDef data fill:#FFE0B2,stroke:#EF6C00,color:#E65100
    classDef build fill:#ECEFF1,stroke:#90A4AE,color:#455A64
```
