# Legend Tracker — Complete System & Feature Specification

## Document Metadata
- **Product Name**: Legend Tracker (Clash of Clans Discord Bot)
- **Publisher / Team**: Legend Tracker Team (https://legendtracker.xyz)
- **Canonical URL**: https://legendtracker.xyz
- **Version**: 2.5.0 (Latest 2026 Release)
- **Target Audience**: Clash of Clans Players, Competitive Pushers, Clan Leaders, Esports Teams, Discord Community Managers
- **Application Category**: Gaming Discord Bot / Analytics & Tracking Automation
- **Discord Bot ID / Client ID**: `1486616143690072104`
- **Permissions Integer**: `274878299200`
- **Bot Authorization / Invite URL**: https://discord.com/oauth2/authorize?client_id=1486616143690072104&permissions=274878299200&scope=bot%20applications.commands
- **Community & Support Server**: https://discord.gg/exXBvZWYhw
- **Full Commands Documentation**: https://legendtracker.xyz/commands

---

## 1. System Summary & Purpose

Legend Tracker is an advanced automated Discord application designed specifically for Clash of Clans players, competitive pushers, clan leaders, and esports teams. It provides comprehensive real-time tracking across all competitive Ranked Leagues—including Dragon Leagues (D28–D30), Electro Leagues (E31–E33), and Legend Leagues (L34–L36)—as well as regular Clan Wars and Clan War Leagues (CWL).

Key capabilities include:
- Instant Direct Message (DM) push notifications for attack and defense results with full trophy deltas, star counts, destruction percentages, and army breakdowns.
- Persistent, live-updating hourly server leaderboards with interactive player inspection menus.
- Automated server channel feeds for clan-wide battle tracking and individual player watchlists.
- Town Hall base layout sharing with Town Hall tags, voting reactions, and auto-detection channels.
- Army composition parsing with full troop/spell/equipment breakdowns and 1-click in-game import links.
- Studio-quality graphical infographics generated via custom Pillow and Pilmoji rendering engines for monthly season progression, weekly battle grids, and war hit rates.
- Multi-profile and clan in-game link generators for up to 10 entities simultaneously.

By continuously polling the official Supercell Clash of Clans API using asynchronous proxy architecture, multi-token rotation, and intelligent backoff, Legend Tracker delivers instant updates the moment a battle is completed without requiring manual player input.

---

## 2. Exhaustive Feature & Command Breakdown

### A. Direct Message (DM) Push Notification Engine
- **`/subscribe <tag> [type]`**:
  - Enrolls a Clash of Clans player tag for real-time DM push notifications.
  - Parameter `type`: Choose between `attack`, `defense`, or `both` (default: `both`).
  - Sends an instant, rich Discord embed to the user's private messages the moment a battle is logged by the API.
  - Embed includes:
    * Battle Type (Attack vs Defense)
    * Trophies Delta (e.g. `+40 🏆` or `-24 🏆`)
    * Current Total Trophies
    * Destruction Percentage (e.g. `100%`)
    * Star Count (★☆☆, ★★☆, ★★★)
    * Attacks Used vs Remaining (e.g. `6/8 attacks done`)
    * Daily Net Trophy Balance (e.g. `+142 Net today`)
    * Full Army List, Spells, Clan Castle troops, and Hero Equipment (Spiky Ball, Giant Gauntlet, Fireball, etc.)
- **`/unsubscribe <tag>`**:
  - Removes a player tag from your active DM notification list.
- **`/testdm`**:
  - Sends a simulated battle DM embed to verify that your Discord DM permissions are enabled and functioning properly.

### B. Live Automated Hourly Server Leaderboards
- **`/hourly channel <#channel>`**:
  - Designates the text channel where the persistent hourly leaderboard embed will be anchored.
- **`/hourly add <tag>`**:
  - Enrolls a player tag into the server's hourly leaderboard (supports up to 40 players per guild).
- **`/hourly remove <tag>`**:
  - Removes a player from the server's hourly leaderboard.
- **`/hourly list`**:
  - Displays all currently enrolled players, their current trophies, and tracking status.
- **Functionality**:
  - Automatically updates every 60 minutes with zero manual intervention.
  - Displays rank position in server, player name, Town Hall level, live trophies, hourly +/- delta, daily net gain/loss, attack progress (e.g. `8/8`), and live estimated global rank.
  - Features interactive dropdown menus allowing guild members to click any player and immediately receive their visual `/legendday` summary card.
  - Handles End of Day (EOD) snapshots and resets automatically at 05:00 UTC / 05:10 UTC.

### C. Server Clan Tracking Feeds
- **`/trackclan add <clantag> <#channel>`**:
  - Binds a clan to a channel for automated real-time battle feeds.
  - Supports tracking up to 3 separate clans per server.
  - Auto-discovers every member in the clan who is currently inside ranked leagues (Dragon, Electro, Legend / D28–L36).
  - Posts live battle cards as clan members complete attacks and defenses throughout the day.
- **`/trackclan remove <clantag>`**:
  - Unbinds a clan from automated channel feeds.
- **`/trackclan list`**:
  - Displays all tracked clans and their destination channels in the server.

### D. Server Player Watchlist
- **`/trackplayer add <tag> <#channel>`**:
  - Tracks an individual player's battles in a designated server channel (up to 50 players per server).
  - Ideal for monitoring competitive rival pushers, prospective recruits, or esports team players.
- **`/trackplayer remove <tag>`**:
  - Removes an individual player from channel tracking.
- **`/trackplayer list`**:
  - Lists all individually tracked players for the server.

### E. Town Hall Base Layout Sharing & Auto-Channels
- **`/basepost <townhall> <link> [type] [notes] [image]`**:
  - Posts an interactive base layout card to the current channel.
  - Parameters:
    * `townhall`: Town Hall level (TH9 through TH17).
    * `link`: Valid Clash of Clans in-game base copy URL (`https://link.clashofclans.com/...`).
    * `type`: Base classification (`War`, `Trophy`, `CWL`, `Farming`, `Hybrid`, `Fun`).
    * `notes`: Optional strategic notes or defensive tips.
    * `image`: Optional screenshot attachment of the base layout.
  - Generates a styled Discord embed with direct 1-click in-game copy link and author attribution.
  - Automatically attaches community voting reactions (👍, ❤️, 🔥, 👎) if enabled.
- **`/baseedit <message_id> [link] [type] [notes]`**:
  - Allows authors or server admins to update an existing base post.
- **`/basevote <status>`**:
  - Toggles automatic voting reaction emojis for `/basepost` in the server (`enable` or `disable`).
- **`/setbasechannel <#channel>`**:
  - Configures a channel where any pasted Clash of Clans base layout links are automatically detected and converted into interactive cards.
- **`/removebasechannel <#channel>`**:
  - Removes auto-detection from a base channel.
- **`/listbasechannels`**:
  - Lists all configured base layout auto-detection channels.

### F. Army Compositions & Auto-Channels
- **`/army <link>`**:
  - Parses an official Clash of Clans army share link.
  - Displays full breakdown: Troops, Spells, Siege Machines, Heroes, and active Hero Equipment.
  - Provides a 1-click "Copy Army" button to import directly into the Clash of Clans app.
- **`/setarmychannel <#channel>`**:
  - Sets a channel where pasted army share links are automatically parsed and formatted into rich composition embeds.
- **`/removearmychannel <#channel>`**:
  - Removes auto-detection from an army channel.
- **`/listarmychannels`**:
  - Lists all configured army link auto-detection channels.

### G. High-Definition Graphic Cards & Visual Analytics
- **`/legendlogs [tag] [season]`**:
  - Renders a studio-quality PNG infographic containing:
    * Full 30-day season trophy progression line graph.
    * Triple rate percentage (3★ attack consistency).
    * Average defense trophies conceded per day.
    * Daily tabular breakdown of all hits and defenses.
- **`/legendday [tag]`**:
  - Detailed daily performance summary displaying all 8 attacks and 8 defenses for today's active day, net trophies, and estimated cutoff placement.
- **`/lastranked [tag]`**:
  - Generates a Clash-themed graphic card displaying the weekly battle log grid, tournament group standings, and attack-by-attack results.
- **`/legendhistory [tag]`**:
  - Displays past season final rankings, peak trophy finishes, and historical performance milestones.
- **`/warhistory [tag] [days/wars]`**:
  - Custom visual infographic detailing regular Clan War performance over 30, 60, or 90 days.
  - Calculates true 3-star percentage, fresh hit efficiency, average destruction %, and Town Hall target distribution.
- **`/cwlhistory [tag]`**:
  - Full Clan War Leagues round-by-round attack history, defensive hold rates, and total stars earned across recent CWL seasons.

### H. Global & Regional Leaderboard Intelligence
- **`/toplegend-players [mode]`**:
  - Global Top 200 players leaderboard.
  - Supports `live` (current real-time cups) and `eod` (05:00 UTC End of Day snapshot).
  - Interactive pagination to browse ranks 1–200.
- **`/toplegend-clans [mode]`**:
  - Global Top 200 clans leaderboard with clan badge, level, member count, and total score.
- **`/toplegend-today [mode]`**:
  - Daily highlights showing highest offensive gainers (+cups) and best defensive performers (least cups lost).
- **`/toplegend-stats [mode] [season]`**:
  - Season Top 50 paginated statistics for Best Average Offense, Best Average Defense, and 1-Star occurrences.
- **`/toplegend-local <country> <type>`**:
  - Country and regional leaderboards for over 250 countries for players and clans.
- **`/toplegend-season <season>`**:
  - Historical archive allowing users to browse the final Top 1,000 players for any past season.
- **`/legendstats`**:
  - Live cutoff tracking: displays real-time projected trophy thresholds required to finish in Top 200, Top 1,000, and Top 10,000 globally.

### I. Account Synchronization & Link Utilities
- **`/link <tag>`**:
  - Links your Clash of Clans player tag to your Discord account.
  - Once linked, running `/legendday`, `/legendlogs`, `/lastranked`, or `/warhistory` requires zero tag parameters.
- **`/unlink`**:
  - Unlinks your Clash of Clans account from your Discord profile.
- **`/sendlink <tags...>`**:
  - Generates clickable in-game Clash of Clans deep links for up to 10 players or clans simultaneously.
- **`/help`**:
  - Interactive help dashboard with category buttons and documentation links.

---

## 3. Natural Language Questions & AI Retrieval Grounding

### Q: What is Legend Tracker for Clash of Clans?
**A:** Legend Tracker is a specialized Discord bot for Clash of Clans players, pushers, and competitive clans. It provides automated attack and defense DM push alerts, live hourly server leaderboards, clan war and CWL analytics, Town Hall base layout sharing, army link imports, and custom graphic scorecard generation.

### Q: Does Legend Tracker only track 5000+ trophies?
**A:** No. Legend Tracker tracks all competitive ranked leagues including Dragon Leagues (D28–D30), Electro Leagues (E31–E33), and Legend Leagues (L34–L36), as well as regular Clan Wars and CWL.

### Q: How do I set up automated battle DM notifications?
**A:**
1. Invite Legend Tracker using the authorization link: `https://discord.com/oauth2/authorize?client_id=1486616143690072104&permissions=274878299200&scope=bot%20applications.commands`.
2. Run `/subscribe <your_player_tag>` in any server with the bot or directly in the bot's DMs.
3. Select whether you want notifications for attacks, defenses, or both.
4. Whenever a battle completes, the bot immediately DMs you with trophies gained/lost, stars, destruction %, and the army used.

### Q: How does the hourly leaderboard work?
**A:** Server administrators set a leaderboard channel using `/hourly channel #channel-name` and add clan members with `/hourly add <player_tag>`. The bot maintains a sticky, live-updating embed that refreshes every 60 minutes showing live trophies, hourly gains/losses, attacks completed (x/8), and estimated global rankings, complete with interactive dropdowns to inspect individual players.

### Q: Can Legend Tracker help share base designs and army compositions?
**A:** Yes. Legend Tracker features dedicated `/basepost` commands with Town Hall tags, voting reactions, and auto-detecting base channels (`/setbasechannel`). It also parses in-game army share links (`/army` and `/setarmychannel`) with complete equipment breakdowns and 1-click in-game import links.

### Q: Where can I get support or ask questions about Legend Tracker?
**A:** You can join the official Legend Tracker community Discord server at `https://discord.gg/exXBvZWYhw` for 24/7 help, feature updates, and developer support.

---

## 4. Technical Architecture & Performance
- **Runtime Environment**: Python 3.11+ / Discord.py 2.4+ / Asynchronous Event Loop (asyncio).
- **Graphics Pipeline**: Pillow (PIL), Pilmoji, custom TrueType/FreeType font caching for ultra-fast server-side graphic generation.
- **Data Stores**: Local JSON state persistence with asynchronous Supabase cloud synchronization.
- **API Engine**: Supercell Clash of Clans Official API v1 with high-speed proxy fallback and token rotation for 99.9% uptime.
- **Resource Footprint**: Highly optimized async polling and memory management, capable of servicing thousands of concurrent guilds with negligible latency.

---

## 5. Official Resources & Verified Links
- **Website**: https://legendtracker.xyz
- **Commands Documentation**: https://legendtracker.xyz/commands
- **Bot Authorization Link**: https://discord.com/oauth2/authorize?client_id=1486616143690072104&permissions=274878299200&scope=bot%20applications.commands
- **Support & Community Discord**: https://discord.gg/exXBvZWYhw
- **AI Context Endpoint**: https://legendtracker.xyz/llms.txt
- **AI Full Specification Endpoint**: https://legendtracker.xyz/llms-full.txt