tlw-database-tool/AGENTS.md

RTK (Rust Token Killer) - Token-Optimized Commands

When running shell commands, always prefix with rtk. This reduces context usage by 60-90% with zero behavior change. If rtk has no filter for a command, it passes through unchanged — so it is always safe to use.

Key Commands

# Git (59-80% savings)
rtk git status          rtk git diff            rtk git log

# Files & Search (60-75% savings)
rtk ls <path>           rtk read <file>         rtk grep <pattern>
rtk find <pattern>      rtk diff <file>

# Build (80-90% savings) — shows errors only
rtk ./gradlew build     rtk ./gradlew compileJava

# Test (90-99% savings) — shows failures only
rtk ./gradlew test

# Analysis (70-90% savings)
rtk err <cmd>           rtk log <file>          rtk json <file>
rtk summary <cmd>       rtk deps                rtk env

# GitHub (26-87% savings)
rtk gh pr view <n>      rtk gh run list         rtk gh issue list

# Infrastructure (85% savings)
rtk docker ps           rtk kubectl get         rtk docker logs <c>

Rules

• In command chains, prefix each segment: rtk git add . && rtk git commit -m "msg"
• For debugging, use raw command without rtk prefix
• rtk proxy <cmd> runs command without filtering but tracks usage

---

TLW Database Tool — Agent Guide

Project Overview

Java CLI tool managing the Tippliga Würzburg football prediction league. Syncs match data from API-Football, manages MySQL database (phpBB forum), pushes Google Calendar events, sends WhatsApp reminders via OpenAI-generated messages, and uploads fixtures to S3.

Build & Test

./gradlew build          # compile + test + jar
./gradlew test           # run all tests
./gradlew clean test     # clean build + test
./gradlew jar            # build fat JAR (all deps bundled)
./gradlew dependencies   # list dependency tree

Run Modes (CLI)

-m MatchdaysUpdater        - Update delivery dates from match times
-m MatchesCreatorFootball  - Create match schedule from API-Football
-m MatchesUpdaterFootball  - Update match team/datetime from API-Football
-m MatchesResultsUpdater   - Push match results to website
-m TeamsUpdater            - Add missing teams to DB
-m APIFootballUpdater      - Fetch fixtures/rounds from API-Football → S3
-m MatchesListGistUpdater  - Update forum posts with fixture lists
-m PostChecksum            - Print checksum of a config post
-m WhatsAppNotifier        - Send WhatsApp reminders for missing bets

Required: -s <season> -l <league> -c <configFile>

Architecture

App.java (CLI entry)
├── apifootball/        — API-Football HTTP client, match model, S3 caching
├── googlecalendar/     — Google Calendar API CRUD for matchday events
├── teamidmatcher/      — BiMap: Tippliga team ID ↔ API-Football team ID
├── tippliga/           — Domain models & operations (match, matchday, team, league)
├── tippligaforum/      — MySQL DB connector, phpBB forum post management
└── whatsapp/           — OpenAI-generated reminders, WhatsApp API sender

Code Conventions

• Package: de.jeyp91.*
• SQL columns referenced by ordinal position (constants like final int SEASON = 1)
• Logger via SLF4J: LoggerFactory.getLogger(Class.class)
• Config stored as JSON in phpBB forum posts (not local files)
• API keys / secrets in environment variables

Testing

• JUnit 4 + TestNG
• Tests in src/test/java/de/jeyp91/
• Run single test: ./gradlew test --tests "de.jeyp91.apifootball.APIFootballMatchTest"