# oiwexo/poolpredictor architecture

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

- Interactive diagram: https://gitdiagram.com/oiwexo/poolpredictor
- Repository: https://github.com/oiwexo/poolpredictor

## Overview

PoolPredictor is an Android overlay mod for 8 Ball Pool 5.8.0 that configures the table area and displays shot predictions and a floating settings menu. The documented entry point launches an activity, which checks overlay permission and starts a service; the service either sets up table selection or creates the prediction and menu overlays. Settings and table coordinates are persisted, while native code reads game state and computes shot results. Several Kotlin use-case and native bridge implementations were not sampled, so those connections are limited to relationships supported by the tree, names, and documented workflow.

Main entry points: [`app/src/main/java/com/iwex/poolpredictor/presentation/service/PredictorService.kt`](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/service/PredictorService.kt) (Predictor service), [`app/src/main/cpp/mod/memory/MemoryManager.cpp`](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/cpp/mod/memory/MemoryManager.cpp) (Game memory access), [`app/src/main/java/com/iwex/poolpredictor/di/factory/RepositoryFactory.kt`](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/di/factory/RepositoryFactory.kt) (Repository factory), [`app/src/main/java/com/iwex/poolpredictor/presentation/activity/LauncherActivity.kt`](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/activity/LauncherActivity.kt) (Launcher activity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Launch and overlays"]
  node_launcher["Launcher activity"]
  node_service["Predictor service"]
  node_overlays["Prediction and menu overlays<br/>[PredictionView.kt]"]
end

subgraph group_configuration["Setup and settings"]
  node_table_setup["Table setup overlay"]
  node_table_vm["Table setup view models"]
  node_aim_esp_tabs["Aim and ESP tabs<br/>[AimTab.kt]"]
  node_aim_vm["Aim and ESP view models<br/>[AimTabViewModel.kt]"]
end

subgraph group_domain["Application domain"]
  node_usecases["Settings and table use cases"]
  node_repository_factory["Repository factory"]
  node_menu_repo["Menu settings repository"]
  node_table_repo["Table position repository"]
  node_preferences[("Shared preferences")]
  node_native_repo["Native repository"]
end

subgraph group_native["Native prediction"]
  node_jni["Kotlin native bridge<br/>[NativeBridge.kt]"]
  node_cpp_bridge["JNI bridge<br/>[NativeBridge.cpp]"]
  node_memory["Game memory access<br/>[MemoryManager.cpp]"]
  node_game_state["Game state readers<br/>[GameManager.cpp]"]
  node_prediction["Shot prediction<br/>[Prediction.cpp]"]
end

node_game_host(("8 Ball Pool host"))
node_game_process(("8 Ball Pool process"))

node_game_host -->|"launches"| node_launcher
node_launcher -->|"starts"| node_service
node_service -->|"shows setup"| node_table_setup
node_service -->|"creates overlays"| node_overlays
node_service -->|"sets table position"| node_usecases
node_table_setup -->|"updates selection"| node_table_vm
node_aim_esp_tabs -->|"sends settings"| node_aim_vm
node_repository_factory -->|"creates"| node_menu_repo
node_repository_factory -->|"creates"| node_table_repo
node_menu_repo -->|"reads and writes"| node_preferences
node_table_repo -->|"reads and writes"| node_preferences
node_repository_factory -->|"creates"| node_native_repo
node_native_repo -->|"uses bridge"| node_jni
node_jni -->|"invokes JNI"| node_cpp_bridge
node_cpp_bridge -->|"accesses game state"| node_memory
node_memory -->|"initializes readers"| node_game_state
node_prediction -->|"reads game data"| node_memory
node_game_process -->|"provides process memory"| node_memory

click node_launcher "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/activity/LauncherActivity.kt"
click node_service "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/service/PredictorService.kt"
click node_overlays "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/view/PredictionView.kt"
click node_table_setup "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/view/tablePosition/TablePositionSetupView.kt"
click node_table_vm "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/viewmodel/tablePosition/TablePositionSetupViewModel.kt"
click node_aim_esp_tabs "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/view/menu/tabs/AimTab.kt"
click node_aim_vm "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/viewmodel/AimTabViewModel.kt"
click node_usecases "https://github.com/oiwexo/poolpredictor/tree/master/app/src/main/java/com/iwex/poolpredictor/domain/usecase"
click node_repository_factory "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/di/factory/RepositoryFactory.kt"
click node_menu_repo "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/data/repository/MenuSettingsRepositoryImpl.kt"
click node_table_repo "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/data/repository/TablePositionRepositoryImpl.kt"
click node_native_repo "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/data/repository/NativeRepositoryImpl.kt"
click node_jni "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/data/NativeBridge.kt"
click node_cpp_bridge "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/cpp/bridge/NativeBridge.cpp"
click node_memory "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/cpp/mod/memory/MemoryManager.cpp"
click node_game_state "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/cpp/mod/memory/inner/GameManager.cpp"
click node_prediction "https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/cpp/mod/predictor/Prediction.cpp"

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_launcher,node_service,node_overlays toneBlue
class node_table_setup,node_table_vm,node_aim_esp_tabs,node_aim_vm toneAmber
class node_usecases,node_repository_factory,node_menu_repo,node_table_repo,node_preferences,node_native_repo toneMint
class node_jni,node_cpp_bridge,node_memory,node_game_state,node_prediction toneRose
class node_game_host,node_game_process toneIndigo
```

## Components

### Launch and overlays

- [Launcher activity](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/activity/LauncherActivity.kt): `app/src/main/java/com/iwex/poolpredictor/presentation/activity/LauncherActivity.kt`
- [Predictor service](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/service/PredictorService.kt): `app/src/main/java/com/iwex/poolpredictor/presentation/service/PredictorService.kt`
- [Prediction and menu overlays](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/view/PredictionView.kt): `app/src/main/java/com/iwex/poolpredictor/presentation/view/PredictionView.kt`

### Setup and settings

- [Table setup overlay](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/view/tablePosition/TablePositionSetupView.kt): `app/src/main/java/com/iwex/poolpredictor/presentation/view/tablePosition/TablePositionSetupView.kt`
- [Table setup view models](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/viewmodel/tablePosition/TablePositionSetupViewModel.kt): `app/src/main/java/com/iwex/poolpredictor/presentation/viewmodel/tablePosition/TablePositionSetupViewModel.kt`
- [Aim and ESP tabs](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/view/menu/tabs/AimTab.kt): `app/src/main/java/com/iwex/poolpredictor/presentation/view/menu/tabs/AimTab.kt`
- [Aim and ESP view models](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/presentation/viewmodel/AimTabViewModel.kt): `app/src/main/java/com/iwex/poolpredictor/presentation/viewmodel/AimTabViewModel.kt`

### Application domain

- [Settings and table use cases](https://github.com/oiwexo/poolpredictor/tree/master/app/src/main/java/com/iwex/poolpredictor/domain/usecase): `app/src/main/java/com/iwex/poolpredictor/domain/usecase`
- [Repository factory](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/di/factory/RepositoryFactory.kt): `app/src/main/java/com/iwex/poolpredictor/di/factory/RepositoryFactory.kt`
- [Menu settings repository](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/data/repository/MenuSettingsRepositoryImpl.kt): `app/src/main/java/com/iwex/poolpredictor/data/repository/MenuSettingsRepositoryImpl.kt`
- [Table position repository](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/data/repository/TablePositionRepositoryImpl.kt): `app/src/main/java/com/iwex/poolpredictor/data/repository/TablePositionRepositoryImpl.kt`
- **Shared preferences**
- [Native repository](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/data/repository/NativeRepositoryImpl.kt): `app/src/main/java/com/iwex/poolpredictor/data/repository/NativeRepositoryImpl.kt`

### Native prediction

- [Kotlin native bridge](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/java/com/iwex/poolpredictor/data/NativeBridge.kt): `app/src/main/java/com/iwex/poolpredictor/data/NativeBridge.kt`
- [JNI bridge](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/cpp/bridge/NativeBridge.cpp): `app/src/main/cpp/bridge/NativeBridge.cpp`
- [Game memory access](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/cpp/mod/memory/MemoryManager.cpp): `app/src/main/cpp/mod/memory/MemoryManager.cpp`
- [Game state readers](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/cpp/mod/memory/inner/GameManager.cpp): `app/src/main/cpp/mod/memory/inner/GameManager.cpp`
- [Shot prediction](https://github.com/oiwexo/poolpredictor/blob/master/app/src/main/cpp/mod/predictor/Prediction.cpp): `app/src/main/cpp/mod/predictor/Prediction.cpp`

### Other components

- **8 Ball Pool host**
- **8 Ball Pool process**

## Connections

- 8 Ball Pool host → Launcher activity: launches
- Launcher activity → Predictor service: starts
- Predictor service → Table setup overlay: shows setup
- Predictor service → Prediction and menu overlays: creates overlays
- Predictor service → Settings and table use cases: sets table position
- Table setup overlay → Table setup view models: updates selection
- Aim and ESP tabs → Aim and ESP view models: sends settings
- Repository factory → Menu settings repository: creates
- Repository factory → Table position repository: creates
- Menu settings repository → Shared preferences: reads and writes
- Table position repository → Shared preferences: reads and writes
- Repository factory → Native repository: creates
- Native repository → Kotlin native bridge: uses bridge
- Kotlin native bridge → JNI bridge: invokes JNI
- JNI bridge → Game memory access: accesses game state
- Game memory access → Game state readers: initializes readers
- Shot prediction → Game memory access: reads game data
- 8 Ball Pool process → Game memory access: provides process memory