# kamoteprice/lf-alerts architecture

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

- Interactive diagram: https://gitdiagram.com/kamoteprice/lf-alerts
- Repository: https://github.com/kamoteprice/lf-alerts

## Overview

LF Alerts is an Android app for scanning Telegram LF groups against shared keywords and alerting buyers about matches. The principal workflow starts in the Kivy app, activates a device-bound license, runs Telegram workers, and delivers matches through Telegram Saved Messages and phone notifications. The repository also includes seller-side license-key tooling, worker reliability features, and app-level support capabilities. The README documents the user workflow; several subsystem implementations were not sampled, so their internal links are omitted or marked unverified.

Main entry points: [`_src/_lf_bootstrap.py`](https://github.com/kamoteprice/lf-alerts/blob/main/_src/_lf_bootstrap.py) (Kivy app UI), [`_src/worker.py`](https://github.com/kamoteprice/lf-alerts/blob/main/_src/worker.py) (Telegram workers), [`_src/notifier.py`](https://github.com/kamoteprice/lf-alerts/blob/main/_src/notifier.py) (Match notifications), [`_src/license.py`](https://github.com/kamoteprice/lf-alerts/blob/main/_src/license.py) (License manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_entry["App entry<br/>[main.py]"]
  node_ui["Kivy app UI<br/>[_lf_bootstrap.py]"]
  node_match_banner["Match banner<br/>[banner.py]"]
  node_themes["Themes<br/>[themes.py]"]
end

subgraph group_scanning["Telegram scanning"]
  node_worker["Telegram workers<br/>[worker.py]"]
  node_blacklist["Chat blacklist<br/>[blacklist.py]"]
  node_match_alerts["Match notifications<br/>[notifier.py]"]
  node_session_store[("App data<br/>[db.py]")]
end

subgraph group_licensing["Licensing and seller tools"]
  node_license["License manager<br/>[license.py]"]
  node_keygen["Key generation<br/>[keygen.py]"]
  node_key_inventory["Key inventory<br/>[keystats.py]"]
end

subgraph group_support["App support"]
  node_telemetry["License telemetry<br/>[telemetry.py]"]
  node_seller_ping["Seller activation pings<br/>[pinger.py]"]
  node_android_service["Foreground service<br/>[service.py]"]
  node_stability["Stability controls<br/>[stability.py]"]
  node_updater["App updater<br/>[updater.py]"]
end

node_user(("Buyer"))
node_telegram(("Telegram"))
node_license_service(("License service"))

node_user -->|"launches"| node_entry
node_entry -->|"starts"| node_ui
node_user -->|"configures workers"| node_ui
node_ui -->|"activates key"| node_license
node_ui -.->|"starts scanning"| node_worker
node_worker -->|"scans groups"| node_telegram
node_worker -.->|"checks exclusions"| node_blacklist
node_worker -.->|"notifies matches"| node_match_alerts
node_match_alerts -->|"sends Saved Message"| node_telegram
node_match_alerts -->|"shows phone alert"| node_user
node_ui -.->|"uses match modal"| node_match_banner
node_license -->|"checks activation"| node_license_service
node_license -->|"reports license events"| node_telemetry
node_ui -->|"pings activation"| node_seller_ping
node_keygen -.->|"tracks generated keys"| node_key_inventory
node_ui -.->|"manages scanning notice"| node_android_service
node_ui -.->|"uses reliability controls"| node_stability
node_ui -.->|"offers updates"| node_updater
node_ui -.->|"uses themes"| node_themes

click node_entry "https://github.com/kamoteprice/lf-alerts/blob/main/main.py"
click node_ui "https://github.com/kamoteprice/lf-alerts/blob/main/_src/_lf_bootstrap.py"
click node_match_banner "https://github.com/kamoteprice/lf-alerts/blob/main/_src/banner.py"
click node_worker "https://github.com/kamoteprice/lf-alerts/blob/main/_src/worker.py"
click node_blacklist "https://github.com/kamoteprice/lf-alerts/blob/main/_src/blacklist.py"
click node_match_alerts "https://github.com/kamoteprice/lf-alerts/blob/main/_src/notifier.py"
click node_session_store "https://github.com/kamoteprice/lf-alerts/blob/main/_src/db.py"
click node_license "https://github.com/kamoteprice/lf-alerts/blob/main/_src/license.py"
click node_keygen "https://github.com/kamoteprice/lf-alerts/blob/main/_src/keygen.py"
click node_key_inventory "https://github.com/kamoteprice/lf-alerts/blob/main/_src/keystats.py"
click node_telemetry "https://github.com/kamoteprice/lf-alerts/blob/main/_src/telemetry.py"
click node_seller_ping "https://github.com/kamoteprice/lf-alerts/blob/main/_src/pinger.py"
click node_android_service "https://github.com/kamoteprice/lf-alerts/blob/main/_src/service.py"
click node_stability "https://github.com/kamoteprice/lf-alerts/blob/main/_src/stability.py"
click node_updater "https://github.com/kamoteprice/lf-alerts/blob/main/_src/updater.py"
click node_themes "https://github.com/kamoteprice/lf-alerts/blob/main/_src/themes.py"

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_entry,node_ui,node_match_banner,node_themes toneBlue
class node_worker,node_blacklist,node_match_alerts,node_session_store toneAmber
class node_license,node_keygen,node_key_inventory toneMint
class node_telemetry,node_seller_ping,node_android_service,node_stability,node_updater toneRose
class node_user,node_telegram,node_license_service toneIndigo
```

## Components

### App experience

- [App entry](https://github.com/kamoteprice/lf-alerts/blob/main/main.py): `main.py`
- [Kivy app UI](https://github.com/kamoteprice/lf-alerts/blob/main/_src/_lf_bootstrap.py): `_src/_lf_bootstrap.py`
- [Match banner](https://github.com/kamoteprice/lf-alerts/blob/main/_src/banner.py): `_src/banner.py`
- [Themes](https://github.com/kamoteprice/lf-alerts/blob/main/_src/themes.py): `_src/themes.py`

### Telegram scanning

- [Telegram workers](https://github.com/kamoteprice/lf-alerts/blob/main/_src/worker.py): `_src/worker.py`
- [Chat blacklist](https://github.com/kamoteprice/lf-alerts/blob/main/_src/blacklist.py): `_src/blacklist.py`
- [Match notifications](https://github.com/kamoteprice/lf-alerts/blob/main/_src/notifier.py): `_src/notifier.py`
- [App data](https://github.com/kamoteprice/lf-alerts/blob/main/_src/db.py): `_src/db.py`

### Licensing and seller tools

- [License manager](https://github.com/kamoteprice/lf-alerts/blob/main/_src/license.py): `_src/license.py`
- [Key generation](https://github.com/kamoteprice/lf-alerts/blob/main/_src/keygen.py): `_src/keygen.py`
- [Key inventory](https://github.com/kamoteprice/lf-alerts/blob/main/_src/keystats.py): `_src/keystats.py`

### App support

- [License telemetry](https://github.com/kamoteprice/lf-alerts/blob/main/_src/telemetry.py): `_src/telemetry.py`
- [Seller activation pings](https://github.com/kamoteprice/lf-alerts/blob/main/_src/pinger.py): `_src/pinger.py`
- [Foreground service](https://github.com/kamoteprice/lf-alerts/blob/main/_src/service.py): `_src/service.py`
- [Stability controls](https://github.com/kamoteprice/lf-alerts/blob/main/_src/stability.py): `_src/stability.py`
- [App updater](https://github.com/kamoteprice/lf-alerts/blob/main/_src/updater.py): `_src/updater.py`

### Other components

- **Buyer**
- **Telegram**
- **License service**

## Connections

- Buyer → App entry: launches (evidence: `README.md`)
- App entry → Kivy app UI: starts (evidence: `main.py`)
- Buyer → Kivy app UI: configures workers (evidence: `README.md`)
- Kivy app UI → License manager: activates key (evidence: `_src/_lf_bootstrap.py`)
- Kivy app UI → Telegram workers: starts scanning (evidence: `_src/_lf_bootstrap.py`)
- Telegram workers → Telegram: scans groups (evidence: `README.md`)
- Telegram workers → Chat blacklist: checks exclusions
- Telegram workers → Match notifications: notifies matches (evidence: `_src/worker.py`)
- Match notifications → Telegram: sends Saved Message (evidence: `README.md`)
- Match notifications → Buyer: shows phone alert (evidence: `README.md`)
- Kivy app UI → Match banner: uses match modal (evidence: `_src/_lf_bootstrap.py`)
- License manager → License service: checks activation (evidence: `_src/license.py`)
- License manager → License telemetry: reports license events (evidence: `_src/license.py`)
- Kivy app UI → Seller activation pings: pings activation (evidence: `_src/_lf_bootstrap.py`)
- Key generation → Key inventory: tracks generated keys
- Kivy app UI → Foreground service: manages scanning notice (evidence: `_src/_lf_bootstrap.py`)
- Kivy app UI → Stability controls: uses reliability controls (evidence: `_src/_lf_bootstrap.py`)
- Kivy app UI → App updater: offers updates (evidence: `_src/_lf_bootstrap.py`)
- Kivy app UI → Themes: uses themes (evidence: `_src/_lf_bootstrap.py`)
