# gaaash/matchday-bot architecture

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

- Interactive diagram: https://gitdiagram.com/gaaash/matchday-bot
- Repository: https://github.com/gaaash/matchday-bot

## Overview

Matchdaybot is a Telegram football-information bot. Users request today’s games, a team’s next match, recent results, standings, or lineups; the bot returns formatted information in Telegram. A scheduled worker refreshes match and result data, while lineup lookup resolves an opponent and fetches official or predicted players. The README is empty, so capabilities and relationships here are based on the excerpts and SOURCE INDEX; the database implementation and stored-data layout are not present in the tree.

Main entry points: [`findLineup.py`](https://github.com/gaaash/matchday-bot/blob/main/findLineup.py) (Lineup lookup), [`scheduler.py`](https://github.com/gaaash/matchday-bot/blob/main/scheduler.py) (Match scheduler), [`main.py`](https://github.com/gaaash/matchday-bot/blob/main/main.py) (Team commands), [`findtable.py`](https://github.com/gaaash/matchday-bot/blob/main/findtable.py) (League standings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram interface"]
  node_telegram["Telegram bot<br/>[main.py]"]
  node_team_commands["Team commands<br/>[main.py]"]
  node_standings["League standings<br/>[findtable.py]"]
  node_usage_store[("Usage persistence")]
end

subgraph group_matchdata["Match data"]
  node_match_scheduler["Match scheduler<br/>[scheduler.py]"]
  node_match_cache[("Match and result files")]
end

subgraph group_lineups["Lineup lookup"]
  node_lineup_lookup["Lineup lookup<br/>[findLineup.py]"]
end

subgraph group_reference["Team reference"]
  node_team_ids["Team mappings<br/>[data.py]"]
end

node_user(("Telegram user"))
node_sportsdb["TheSportsDB"]
node_scores365["365Scores"]
node_flashscore["Flashscore"]
node_livesport["Livesport search"]
node_lineup_api["Lineup GraphQL API"]
node_heartbeat["Better Stack heartbeat"]

node_user -->|"sends commands"| node_telegram
node_telegram -->|"dispatches commands"| node_team_commands
node_telegram -->|"imports standings"| node_standings
node_team_commands -->|"requests lineup"| node_lineup_lookup
node_team_commands -->|"reads match files"| node_match_cache
node_team_commands -->|"saves usage"| node_usage_store
node_match_scheduler -->|"uses team IDs"| node_team_ids
node_match_scheduler -->|"fetches next events"| node_sportsdb
node_match_scheduler -->|"fetches recent games"| node_scores365
node_match_scheduler -->|"writes match files"| node_match_cache
node_match_scheduler -->|"pings heartbeat"| node_heartbeat
node_lineup_lookup -->|"uses team mappings"| node_team_ids
node_lineup_lookup -->|"fetches match pages"| node_flashscore
node_lineup_lookup -->|"searches opponent"| node_livesport
node_lineup_lookup -->|"fetches lineups"| node_lineup_api
node_lineup_lookup -->|"writes lineup file"| node_match_cache
node_standings -->|"fetches standings"| node_scores365
node_standings -->|"writes standings file"| node_match_cache

click node_telegram "https://github.com/gaaash/matchday-bot/blob/main/main.py"
click node_team_commands "https://github.com/gaaash/matchday-bot/blob/main/main.py"
click node_standings "https://github.com/gaaash/matchday-bot/blob/main/findtable.py"
click node_match_scheduler "https://github.com/gaaash/matchday-bot/blob/main/scheduler.py"
click node_team_ids "https://github.com/gaaash/matchday-bot/blob/main/data.py"
click node_lineup_lookup "https://github.com/gaaash/matchday-bot/blob/main/findLineup.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_telegram,node_team_commands,node_standings,node_usage_store,node_user toneBlue
class node_match_scheduler,node_match_cache toneAmber
class node_lineup_lookup,node_lineup_api toneMint
class node_team_ids toneRose
class node_sportsdb,node_scores365,node_flashscore,node_livesport,node_heartbeat toneIndigo
```

## Components

### Telegram interface

- [Telegram bot](https://github.com/gaaash/matchday-bot/blob/main/main.py): `main.py`
- [Team commands](https://github.com/gaaash/matchday-bot/blob/main/main.py): `main.py`
- [League standings](https://github.com/gaaash/matchday-bot/blob/main/findtable.py): `findtable.py`
- **Usage persistence**

### Match data

- [Match scheduler](https://github.com/gaaash/matchday-bot/blob/main/scheduler.py): `scheduler.py`
- **Match and result files**

### Lineup lookup

- [Lineup lookup](https://github.com/gaaash/matchday-bot/blob/main/findLineup.py): `findLineup.py`

### Team reference

- [Team mappings](https://github.com/gaaash/matchday-bot/blob/main/data.py): `data.py`

### Other components

- **Telegram user**
- **TheSportsDB**
- **365Scores**
- **Flashscore**
- **Livesport search**
- **Lineup GraphQL API**
- **Better Stack heartbeat**

## Connections

- Telegram user → Telegram bot: sends commands (evidence: `main.py`)
- Telegram bot → Team commands: dispatches commands (evidence: `main.py`)
- Telegram bot → League standings: imports standings (evidence: `main.py`)
- Team commands → Lineup lookup: requests lineup (evidence: `main.py`)
- Team commands → Match and result files: reads match files (evidence: `main.py`)
- Team commands → Usage persistence: saves usage (evidence: `main.py`)
- Match scheduler → Team mappings: uses team IDs (evidence: `scheduler.py`)
- Match scheduler → TheSportsDB: fetches next events (evidence: `scheduler.py`)
- Match scheduler → 365Scores: fetches recent games (evidence: `scheduler.py`)
- Match scheduler → Match and result files: writes match files (evidence: `scheduler.py`)
- Match scheduler → Better Stack heartbeat: pings heartbeat (evidence: `scheduler.py`)
- Lineup lookup → Team mappings: uses team mappings (evidence: `findLineup.py`)
- Lineup lookup → Flashscore: fetches match pages (evidence: `findLineup.py`)
- Lineup lookup → Livesport search: searches opponent (evidence: `findLineup.py`)
- Lineup lookup → Lineup GraphQL API: fetches lineups (evidence: `findLineup.py`)
- Lineup lookup → Match and result files: writes lineup file (evidence: `findLineup.py`)
- League standings → 365Scores: fetches standings (evidence: `findtable.py`)
- League standings → Match and result files: writes standings file (evidence: `findtable.py`)
