tipibot/docs/DEV_NOTES.md

TipiLAN Bot - Developer Reference

File Structure

The codebase is split into core/ (domain logic), commands/ (Discord slash command handlers), and a thin bot.py that wires everything together.

Top level

File	Purpose
bot.py	Discord client, event handlers (on_ready, on_member_join, ...), background tasks (presence rotation, daily birthday loop), shared helpers (_award_exp, _maybe_remind, _parse_amount, _PAUSED), and register_*_commands(...) wiring for every command module
strings/	Single source of truth for all user-facing text, split into domain submodules (common, commands, member, economy, admin, games, fishing) and re-exported via strings/__init__.py so import strings / strings.NAME works unchanged. Edit the relevant submodule to change any message.
config.py	Environment variables (TOKEN, GUILD_ID, PB_URL, etc.)

core/ - domain logic, no Discord coupling

File	Purpose
core/economy/	Economy business logic package, re-exported via core/economy/__init__.py so callers use from core import economy + attribute access (economy.do_daily, economy.SHOP, ...). Submodules: store.py (user records, per-user locks, COOLDOWNS, ITEM_COOLDOWNS/effective_cooldown, JAIL_DURATION, COIN, get_user/_commit/_txn, pending_wager escrow + reconcile_pending_wagers), income.py, gambling.py, fishing.py, jail.py, heist.py, prestige.py, shop.py, consumables.py (timed buffs + grant_buff), vanity.py (cosmetic badges), lootbox.py (mystery box), bank.py (rob-proof vault), achievements.py (milestone badges), lottery.py (daily draw), levels.py, quests.py, leaderboards.py (incl. get_all_leaderboards/get_economy_stats, net-worth = balance+bank), house.py, admin.py
core/pb_client.py	Async PocketBase REST client - auth token cache, CRUD on economy_users collection
core/sheets.py	Google Sheets integration (member sync)
core/member_sync.py	Birthday/member sync helpers, plus tournament team-role sync + divider placement

commands/ - one slash-command group per file

Each file exposes a register_<group>_commands(tree, bot, ...) function. bot.py calls them all once on startup, passing in shared helpers (coin, cd_ts, award_exp, maybe_remind, parse_amount, ...).

File	Commands / Responsibility
commands/dev_member_commands.py	/check, /member (dev profile only)
commands/dev_member_runtime.py	on_member_join flow + birthday_daily task body
commands/economy_income_commands.py	/daily, /work, /beg, /crime, /rob
commands/economy_games_commands.py	/roulette, /slots, /blackjack, /rps
commands/economy_extra_commands.py	/heist, /jailbreak, /reminders, /request, /give, /lottery, /leaderboard, ...
commands/economy_fish_commands.py	/fish, /fishbook, /fishsell
commands/economy_profile_commands.py	/balance, /rank, /stats, /cooldowns, /achievements
commands/economy_support_commands.py	/shop, /buy, /economysetup, /consumables, /vanity, /lootbox, /bank, /deposit, /withdraw
commands/economy_prestige_commands.py	/prestige, /prestigeshop, /prestigebuy
commands/economy_admin_commands.py	/admincoins, /adminexp, /adminitem, /adminjail, /adminban, /adminreset, /adminview
commands/ops_admin_commands.py	/sync, /restart, /shutdown, /pause, /send, /status
commands/ops_channel_commands.py	Channel allowlist commands
commands/info_commands.py	/patchnotes and other lightweight info commands

scripts/

File	Purpose
scripts/migrate_to_pb.py	One-time legacy migration: data/economy.json → PocketBase. Only relevant if you still have a pre-PB JSON store.
scripts/add_stats_fields.py	Schema migration: adds new fields to the economy_users collection. Idempotent.
scripts/reset_pb_collections.py	Destructive - deletes and recreates the dev + economy collections. Requires --confirm. Use only in dev.

---

Adding a New Economy Command

Pick the commands/economy_*_commands.py file that matches the new command's category (income, games, profile, ...) and add the handler inside its register_*_commands function. If none fit, create a new module and register it from bot.py.

Checklist - do all of these, in order:

1. core/economy/<area>.py (e.g. income.py, gambling.py, fishing.py) - add the do_<cmd> async function with cooldown check, logic, _commit, and _txn logging (get_user/_commit/_txn live in store.py)
2. core/economy/store.py - add the cooldown to COOLDOWNS dict if it has one. Compute the effective cooldown in do_<cmd> with effective_cooldown("<cmd>", user["items"]) rather than an inline timedelta(...) if item in items else ...
3. core/economy/levels.py - add the EXP reward to EXP_REWARDS dict
4. strings/commands.py CMD - add the slash command description
5. strings/commands.py OPT - add any parameter descriptions
6. strings/common.py TITLE - add embed title(s) for success/fail states
7. strings/common.py ERR - add any error messages (banned, cooldown uses CD_MSG, jailed uses CD_MSG["jailed"])
8. strings/common.py CD_MSG - add cooldown message if command has a cooldown
9. strings/commands.py HELP_CATEGORIES["tipibot"]["fields"] - add the command to the help embed
10. commands/economy_<group>_commands.py - inside register_*_commands, add @tree.command(name="<cmd>", ...) cmd_<name>; handle all res["reason"] cases. If do_<cmd> can return db_error (any function that calls get_user/_commit), handle it first in the failure block with await reply_db_error(interaction); return (import from ._replies) - otherwise a DB outage hangs the deferred interaction or shows a misleading message
11. commands/economy_<group>_commands.py - call maybe_remind(user_id, "<cmd>") if the command has a cooldown and reminders make sense (the helper is passed in via the register_* signature)
12. commands/economy_<group>_commands.py - call await award_exp(interaction, economy.EXP_REWARDS["<cmd>"]) on success
13. strings/common.py REMINDER_OPTS - add a reminder option if the command needs one
14. core/economy/store.py ITEM_COOLDOWNS - if an item shortens the command's cooldown, add "<cmd>": ("<item_id>", timedelta(...)) here. This is the single source of truth: effective_cooldown (used by do_<cmd>), _maybe_remind, and _restore_reminders all read it, so you no longer edit the reminder helpers by hand

---

Adding a New Shop Item

Checklist:

1. core/economy/shop.py SHOP - add the item dict {name, emoji, cost, description: strings.ITEM_DESCRIPTIONS["key"]}
2. core/economy/shop.py SHOP_TIERS - add the key to the correct tier list (1/2/3)
3. core/economy/shop.py SHOP_LEVEL_REQ - add minimum level if it is T2 (≥10) or T3 (≥20)
4. strings/economy.py ITEM_DESCRIPTIONS - add the item description (Estonian flavour + English effect)
5. strings/commands.py HELP_CATEGORIES["shop"]["fields"] - add display entry (sorted by cost)
6. If the item modifies a cooldown:
   • core/economy/<area>.py - add the if "item" in user["items"] branch in the relevant do_<cmd> function
   • bot.py _maybe_remind - add elif cmd == "<cmd>" and "<item>" in items: branch with the new delay
   • commands/economy_profile_commands.py cmd_cooldowns - add the item annotation to the relevant status line

---

Adding a New Level Role

1. core/economy/levels.py LEVEL_ROLES - add (min_level, "RoleName") in descending level order (highest first)
2. bot.py _ensure_level_role - no changes needed (uses LEVEL_ROLES dynamically)
3. Run /economysetup in the server to create the role and set its position

---

Adding a New Admin Command

1. strings/commands.py CMD - add "[Admin] ..." description
2. strings/commands.py HELP_CATEGORIES["admin"]["fields"] - add the entry
3. commands/economy_admin_commands.py (or commands/ops_admin_commands.py for non-economy ops) - add the handler with @app_commands.default_permissions(manage_guild=True) and @app_commands.guild_only()

---

Economy System Design

Storage

All economy state is stored in PocketBase (economy_users collection). core/pb_client.py owns all reads/writes. Each do_* function in core/economy/ calls get_user() (from store.py) → mutates the local dict → calls _commit(). _commit does a PATCH to PocketBase.

Currency & Income Sources

Command	Cooldown	Base Earn	Notes
/daily	20h (18h w/ korvaklapid)	150⬡	×streak multiplier, ×2 w/ lan_pass, +25⬡ w/ korvaklapid, +5% interest w/ gaming_laptop
/work	1h (40min w/ monitor)	15-75⬡	×1.5 w/ gaming_hiir, ×1.25 w/ reguleeritav_laud, ×3 30% chance w/ energiajook
/beg	5min (3min w/ hiirematt)	10-40⬡	×2 w/ klaviatuur
/crime	2h	200-500⬡ win	60% success (75% w/ cat6), +30% w/ mikrofon; fail = fine + jail
/rob	2h	10–25% of target	45% success (60% w/ jellyfin); fail = fine; house rob: 35% success, 5–40% jackpot
/slots	-	varies	jackpot=10× (15× w/ monitor_360), triple=4× (6×), pair=1×
/roulette	-	2× red/black, 14× green	1/37 green chance
/blackjack	-	1:1 win, 3:2 BJ, 2:1 double	Dealer stands on 17+; double down on first action only

"all" Keyword

Commands that accept a coin amount (/give, /roulette, /rps, /slots, /blackjack) accept "all" to mean the user's full current balance. Parsed by _parse_amount(value, balance) in bot.py.

Daily Streak Multipliers

• 1-2 days: ×1.0 (150⬡)
• 3-6 days: ×1.5 (225⬡)
• 7-13 days: ×2.0 (300⬡)
• 14+ days: ×3.0 (450⬡)
• karikas item: streak survives missed days

Jail

• Duration: 30 minutes (JAIL_DURATION)
• gaming_tool: prevents jail on crime fail
• /jailbreak: 3 dice rolls, need doubles to escape free. On fail - bail = 20-30% of balance, min 350⬡. If balance < 350⬡, player stays jailed until timer.
• Blocked while jailed: /work, /beg, /crime, /rob, /give (checked in do_* functions via _is_jailed)

EXP Rewards (from EXP_REWARDS in core/economy/levels.py)

EXP is awarded on every successful command use. Level formula: level = max(1, floor(sqrt(exp / 6))) (see get_level / exp_for_level). Thresholds: Level 5 = 150 EXP, Level 10 = 600, Level 20 = 2 400, Level 30 = 5 400.

Gambling EXP is bet-scaled via gamble_exp(bet); fish EXP is per-species in FISH_CATALOGUE (common 2–3, uncommon 6–7, rare 10, epic 14–15, legendary 25).

---

Tournament Team Roles

Economy profile only. Roster-independent: matches Discord usernames straight against TEAM_SHEET_ID, never the member sheet. Entry points are /teamsync (commands/economy_team_commands.py) and the hourly team_sync_hourly task in bot.py; both call sheets.refresh_teams() then member_sync.sync_all_team_roles().

Pipeline

Step	Where	Notes
Split a tab into per-game blocks	sheets.parse_team_sections	Returns TeamSection(title, rosters). The merged title row above each header is the only thing identifying game + year
Flatten to {team: [players]}	sheets.parse_team_rosters	Thin wrapper over parse_team_sections
Section title → divider role name	sheets.resolve_divider	Matches config.TEAM_DIVIDERS; most specific key wins
Cache	sheets._refresh_teams_sync	Populates _team_roster, _team_by_username, _team_names, _team_divider
Grant/remove roles per member	member_sync.sync_team_role	Only names in all_team_names() are ever touched
Compute new role positions	member_sync.plan_team_positions	Pure - list of names ascending + managed set + placements → {name: new position}. Unit-tested without Discord
Apply	member_sync.apply_team_role_positions	One guild.edit_role_positions call per sync

Adding a game to the divider config

1. .env - add TEAM_DIVIDER_<GAME>_<YEAR>="<exact Discord role name>". No code change; config._parse_team_dividers discovers any var with that prefix at startup.
2. Restart the bot (env is read once at import).

Position maths gotchas

• Discord positions are ascending from the bottom (@everyone = 0), so "under the divider in the UI" means a lower number. plan_team_positions therefore inserts each block reverse-sorted.
• The bot can only reorder roles strictly below its own highest role. Dividers at or above it are skipped with an error rather than attempted.
• managed roles (integration/bot/booster) are never emitted in the plan.
• Roles are matched by name throughout the feature; with duplicate names the lowest-positioned one wins.
• Only roles whose position actually changed are submitted, so a settled guild costs zero API calls.

---

Role Hierarchy (Discord)

Order top to bottom in server roles:

[Bot managed role]  ← bot's own role, always at top of our stack
ECONOMY             ← given to everyone who uses any economy command
TipiLEGEND          ← level 30+
TipiCHAD            ← level 20+
TipiHUSTLER         ← level 10+
TipiGRINDER         ← level 5+
TipiNOOB            ← level 1+

Run /economysetup to auto-create all roles and set their positions. The command is idempotent - safe to run multiple times.

Role assignment:

• ECONOMY role: given automatically on first EXP award (i.e. first successful economy command)
• Level roles: given/swapped automatically on level-up; synced on /rank

---

Shop Tiers & Level Requirements

Tier	Level Required	Items
T1	0 (any)	gaming_hiir, hiirematt, korvaklapid, lan_pass, anticheat, energiajook, gaming_laptop
T2	10	reguleeritav_laud, jellyfin, mikrofon, klaviatuur, monitor, cat6
T3	20	monitor_360, karikas, gaming_tool

Shop display is sorted by cost (ascending) within each tier. The SHOP_LEVEL_REQ dict in core/economy/shop.py controls per-item lock thresholds.

---

strings/ Organisation

Imported as import strings as S everywhere. strings/ is a package: the names below live in domain submodules and are re-exported from strings/__init__.py, so S.CMD, S.ERR, etc. resolve unchanged regardless of which submodule they live in. Dicts are read from bot.py and from every commands/*.py module. Edit the submodule shown in the Module column.

Section	Dict	Module	Typical usage
Flavour text	WORK_JOBS, BEG_LINES, CRIME_WIN, CRIME_LOSE	economy.py	Randomised descriptions
Command descriptions	CMD["key"]	commands.py	@tree.command(description=S.CMD["key"])
Parameter descriptions	OPT["key"]	commands.py	@app_commands.describe(param=S.OPT["key"])
Help embed	HELP_CATEGORIES["cat"]	commands.py	cmd_help (in bot.py)
Banned message	MSG_BANNED	common.py	All banned checks
Maintenance mode	MSG_MAINTENANCE	common.py	Shown when _PAUSED=True in bot.py (toggled by /pause in commands/ops_admin_commands.py)
Reminder options	REMINDER_OPTS	common.py	RemindersSelect dropdown
Slots outcomes	SLOTS_TIERS["tier"] → (title, color)	games.py	cmd_slots (in commands/economy_games_commands.py)
Embed titles	TITLE["key"]	common.py	discord.Embed(title=S.TITLE["key"])
Error messages	ERR["key"]	common.py	send_message(S.ERR["key"]) - use .format(**kwargs) for dynamic parts
Cooldown messages	CD_MSG["cmd"].format(ts=cd_ts(...))	common.py	Cooldown responses (cd_ts helper passed in by bot.py)
Shop UI	SHOP_UI["key"]	economy.py	_shop_embed (in commands/economy_support_commands.py)
Item descriptions	ITEM_DESCRIPTIONS["item_key"]	economy.py	core/economy/shop.py SHOP[key]["description"]
Patch notes UI	PATCHNOTES_UI["key"]	common.py	commands/info_commands.py (/patchnotes)

---

Constants Location Quick-Reference

All are re-exported from core/economy/__init__.py, so code reads them as economy.<NAME> regardless of which submodule defines them. Edit the file in the Defined in column.

Constant	Defined in	Description
SHOP	core/economy/shop.py	All shop items (name, emoji, cost, description)
SHOP_TIERS	core/economy/shop.py	Which items are in T1/T2/T3
SHOP_LEVEL_REQ	core/economy/shop.py	Min level per item
COOLDOWNS	core/economy/store.py	Base cooldown per command
JAIL_DURATION	core/economy/store.py	How long jail lasts
LEVEL_ROLES	core/economy/levels.py	[(min_level, "RoleName"), ...] highest first
ECONOMY_ROLE	core/economy/levels.py	Name of the base economy participation role
EXP_REWARDS	core/economy/levels.py	EXP per command
FISH_CATALOGUE	core/economy/fishing.py	Fish species table (rarity, weight, coins, exp)
HOUSE_ID	core/economy/house.py	Bot's user ID (house account for /rob)
MIN_BAIL	core/economy/jail.py	Minimum bail payment (350⬡)
COIN	core/economy/store.py	The coin emoji string
_PAUSED	bot.py	In-memory maintenance flag; toggled by /pause; blocks all non-admin commands

---

Balance Notes (as of current version)

• Beg is most efficient for active players (3min cooldown + 2× multiplier w/ klaviatuur = high ⬡/hr)
• Work is best for passive players (1h cooldown, fire and forget)
• Crime is high risk/reward - best with cat6 + mikrofon
• lan_pass (1200⬡) doubles daily - good long-term investment
• gaming_laptop (1500⬡) 5% interest, capped 500⬡/day - snowballs with large balance
• anticheat is consumable (2 uses) - only item that can be re-bought
• karikas (T3) is the only item that preserves a daily streak across missed days
• reguleeritav_laud (T2) stacks with gaming_hiir: combined ×1.5 × ×1.25 = ×1.875