# jonathansilva/8ballpool architecture

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

- Interactive diagram: https://gitdiagram.com/jonathansilva/8ballpool
- Repository: https://github.com/jonathansilva/8ballpool

## Overview

This Android overlay helper launches 8 Ball Pool, then displays a floating aiming guide when the phone is shaken. Users choose Normal, Trickshot, or the legacy Nine Ball guide; Trickshot also supports a second reflection line. The sampled code shows the permission and foreground-service flow, sensor handling, and guide geometry. README-described modes are included; unsampled service logic and resource details are not inferred beyond the documented behavior and visible references.

Main entry points: [`app/src/main/java/app/hack/eightballpool/ViewService.java`](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/ViewService.java) (Overlay service), [`app/src/main/java/app/hack/eightballpool/MainActivity.java`](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/MainActivity.java) (Main activity), [`app/src/main/java/app/hack/eightballpool/Control.java`](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/Control.java) (Service control), [`app/src/main/java/app/hack/eightballpool/Trickshot.java`](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/Trickshot.java) (Trickshot guide)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["Launch and service"]
  node_activity["Main activity<br/>[MainActivity.java]"]
  node_control["Service control<br/>[Control.java]"]
  node_helper["Game launcher<br/>[Helper.java]"]
  node_app["App setup<br/>[App.java]"]
end

subgraph group_overlay["Floating overlay"]
  node_service["Overlay service<br/>[ViewService.java]"]
end

subgraph group_guides["Aiming guides"]
  node_normal["Normal guide<br/>[Normal.java]"]
  node_trickshot["Trickshot guide<br/>[Trickshot.java]"]
  node_nineball["Nine Ball guide<br/>[NineBall.java]"]
  node_intersection["Wall intersections"]
end

subgraph group_resources["UI resources"]
  node_layout["Overlay layout<br/>[main.xml]"]
  node_dimensions["Table dimensions<br/>[dimens.xml]"]
  node_sound["Touch sound<br/>[touch.mp3]"]
end

node_user(("User"))
node_android["Android system"]
node_game["8 Ball Pool"]

node_user -->|"opens app"| node_activity
node_activity -->|"checks overlay permission"| node_android
node_android -->|"returns permission result"| node_activity
node_activity -->|"starts service"| node_control
node_control -->|"launches game"| node_helper
node_helper -->|"starts game"| node_game
node_control -->|"starts foreground"| node_service
node_app -->|"creates notification channel"| node_android
node_service -->|"registers accelerometer"| node_android
node_android -->|"sends sensor events"| node_service
node_service -->|"inflates"| node_layout
node_service -->|"adds overlay window"| node_android
node_service -->|"positions and toggles"| node_normal
node_service -->|"positions and toggles"| node_trickshot
node_service -->|"positions and toggles"| node_nineball
node_service -->|"reads sizing"| node_dimensions
node_service -->|"loads playback"| node_sound
node_trickshot -->|"calculates wall hit"| node_intersection
node_user -->|"shakes phone"| node_service
node_user -->|"drags guide"| node_normal
node_user -->|"adjusts guide"| node_trickshot

click node_activity "https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/MainActivity.java"
click node_control "https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/Control.java"
click node_helper "https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/Helper.java"
click node_app "https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/App.java"
click node_service "https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/ViewService.java"
click node_layout "https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/res/layout/main.xml"
click node_dimensions "https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/res/values/dimens.xml"
click node_sound "https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/res/raw/touch.mp3"
click node_normal "https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/Normal.java"
click node_trickshot "https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/Trickshot.java"
click node_nineball "https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/NineBall.java"
click node_intersection "https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/LineIntersection.java"

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_activity,node_control,node_helper,node_app,node_user toneBlue
class node_service toneAmber
class node_normal,node_trickshot,node_nineball,node_intersection toneMint
class node_layout,node_dimensions,node_sound toneRose
class node_android,node_game toneIndigo
```

## Components

### Launch and service

- [Main activity](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/MainActivity.java): `app/src/main/java/app/hack/eightballpool/MainActivity.java`
- [Service control](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/Control.java): `app/src/main/java/app/hack/eightballpool/Control.java`
- [Game launcher](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/Helper.java): `app/src/main/java/app/hack/eightballpool/Helper.java`
- [App setup](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/App.java): `app/src/main/java/app/hack/eightballpool/App.java`

### Floating overlay

- [Overlay service](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/ViewService.java): `app/src/main/java/app/hack/eightballpool/ViewService.java`

### Aiming guides

- [Normal guide](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/Normal.java): `app/src/main/java/app/hack/eightballpool/Normal.java`
- [Trickshot guide](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/Trickshot.java): `app/src/main/java/app/hack/eightballpool/Trickshot.java`
- [Nine Ball guide](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/NineBall.java): `app/src/main/java/app/hack/eightballpool/NineBall.java`
- [Wall intersections](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/java/app/hack/eightballpool/LineIntersection.java): `app/src/main/java/app/hack/eightballpool/LineIntersection.java`

### UI resources

- [Overlay layout](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/res/layout/main.xml): `app/src/main/res/layout/main.xml`
- [Table dimensions](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/res/values/dimens.xml): `app/src/main/res/values/dimens.xml`
- [Touch sound](https://github.com/jonathansilva/8ballpool/blob/main/app/src/main/res/raw/touch.mp3): `app/src/main/res/raw/touch.mp3`

### Other components

- **User**
- **Android system**
- **8 Ball Pool**

## Connections

- User → Main activity: opens app
- Main activity → Android system: checks overlay permission
- Android system → Main activity: returns permission result
- Main activity → Service control: starts service
- Service control → Game launcher: launches game
- Game launcher → 8 Ball Pool: starts game
- Service control → Overlay service: starts foreground
- App setup → Android system: creates notification channel
- Overlay service → Android system: registers accelerometer
- Android system → Overlay service: sends sensor events
- Overlay service → Overlay layout: inflates
- Overlay service → Android system: adds overlay window
- Overlay service → Normal guide: positions and toggles
- Overlay service → Trickshot guide: positions and toggles
- Overlay service → Nine Ball guide: positions and toggles
- Overlay service → Table dimensions: reads sizing
- Overlay service → Touch sound: loads playback
- Trickshot guide → Wall intersections: calculates wall hit
- User → Overlay service: shakes phone
- User → Normal guide: drags guide
- User → Trickshot guide: adjusts guide