Larry the Bot, Part 1: What Larry Actually Is (and Does)

This is Part 1 of the Larry series and the product companion to the launch story. Part 2 covers the architecture. Part 3, scheduled for July 24, covers caching and cross-process sync.

Clash of Clans recruiting on Discord looks like a messaging problem. At community scale, it is an identity, formatting, and policy problem wearing a messaging hat.

Clans need players. Players need clans. Both advertise in shared channels, and moderators get to answer the same questions every evening: is that account genuine, is the data current, and has this clan waited long enough to post again?

Larry automates that middle without trying to become the community. He verifies the game account, builds the recruiting post, applies the server’s rules, and stays quiet until somebody calls a command.

One journey from setup to recruiting

A server operator starts with /setup or the web admin panel. They choose the recruiting channels, roles, embed colors, cooldown settings, and any server-specific feature switches. One bot process serves many Discord servers—called guilds in the Discord API—and Larry keeps guild-owned configuration and cache entries scoped by guildId.

A player then runs /link with their public player tag and a valid API token generated in the Clash of Clans settings. Larry sends both to Supercell’s API. A successful verification proves that the user can produce the current token for that village; knowing somebody else’s public tag is not enough.

Once linked, the player can:

• use /clan-post to advertise their clan in one or more configured channels
• use /need-clan to publish a player profile when they are looking for a clan
• save templates so the next post does not begin with another empty modal
• schedule recurring clan posts when the server’s booster rules allow it

If a cooldown blocks the post, Larry explains which scope is blocked and when it expires. If an operator decides the block should be cleared, the admin panel invalidates that post as the active blocker without deleting the history.

That last detail is small and important. “Reset cooldown” does not mean “pretend the post never happened.”

The command reference

Larry’s current production command surface:

The upcoming /me profile command exists on the development branch but is not part of the production surface yet.

What “current data” means

Larry uses Supercell’s API, but “API-backed” does not mean “a fresh request for every field.”

Clan lookups are cached for up to ten minutes. Linked accounts store a normalized snapshot—identity, clan role, league, trophies, level, town hall, and hero summary—with a sync timestamp. Recruiting commands refresh player snapshots that are older than two hours.

That balance keeps ordinary commands away from Larry’s conservative process-wide CoC request throttle while still making recruiting data recent enough for the job. The /link ownership check is different: every link attempt calls token verification instead of reusing a cached “yes.”

For /need-clan, Larry can render the player’s profile and army as an image. Clan posts use clan details, a stats view, and an optional banner. Similar commands; different evidence.

Cooldowns belong to the post scope

Manual recruiting cooldowns are not attached only to the Discord user:

• a clan post is scoped by the clan tag and target channel
• a player post is scoped by the player tag
• free users wait 24 hours; eligible boosters wait 12
• scheduled posts follow their own cadence and skip rules

That means a clanmate cannot bypass the rule by posting the same clan from another account. For multichannel clan posts, each target channel has its own scope. One channel is a policy; three is a lifestyle.

The admin panel is for operators

Slash commands are good at short interactions and bad at showing a server’s entire configuration. Operators get a web panel instead:

• Discord login — no separate Larry account
• Guild dashboard — servers the user can manage, plus an invite flow where Larry is missing
• Module-based configuration — general, recruiting, and push settings in forms instead of one enormous setup dialog
• Setup status — evaluated through shared setup logic used by both surfaces, which reduces drift between web and Discord
• Cooldown management — currently blocking posts with one-click invalidation and preserved history

The API checks the user’s Discord-backed guild permissions before serving guild-scoped data or accepting a mutation. Those lookups use a short cache, so “permission checked” is accurate; “the web knows the exact current state at every microsecond” would be theater.

The panel does not replace the bot. Players still link and post in Discord. Schedule management and linked-account management also remain primarily Discord workflows today.

The boundary that shapes Part 2

The product above runs across four deployables:

• apps/bot — long-lived Discord process, schedulers, CoC client, and image rendering
• apps/api — Firebase Functions serving authentication and the admin API
• apps/web — React admin application
• apps/site — Astro marketing site at getlarry.io

The bot and API share typed Firestore repositories and document shapes, but they are separate processes with different lifecycles. When the web panel changes configuration, the bot does not learn that through shared memory.

That is the fact that shapes Part 2: the architecture. The product tour ends at the button. The architecture starts with what has to happen after somebody presses it.