Pearl-Telegram System Requirements Document

1. Introduction

The Pearl-Telegram project is a Telegram bot designed to motivate users to learn through the collection of Pokémon cards. The bot is developed using Python and Aiogram 3, with a focus on modular architecture and JSON-based data storage. It is intended for a single user and does not require authentication beyond verifying the Telegram ID specified in the configuration.

2. System Overview

Pearl-Telegram aims to provide an engaging learning experience by rewarding users with collectible Pokémon cards for their study efforts. The bot features a modular design to facilitate the addition of new mechanics and functionalities over time. Data is stored in JSON files, ensuring easy management and modification of user profiles, card packs, configurations, statistics, and other data.

Key Features:

• Modular architecture for easy expansion.
• JSON-based data storage for profiles, cards, packs, configurations, and statistics.
• Single-user system with Telegram ID verification.
• Educational motivation through Pokémon card collection.
• Customizable card packs, rarities, and rewards.

3. Functional Requirements as Story Points

• As a User, I should be able to start a learning session by entering minutes or starting a timer.
• As a User, I should receive crystals based on my learning time (1 minute = 1 crystal).
• As a User, I should be able to spend crystals on card packs.
• As a User, I should be able to open card packs and view cards one by one.
• As a User, I should see an animation when opening a pack.
• As a User, I should be able to view my profile with avatar, level, total minutes, crystals, stardust, opened packs, unique cards, and collection percentage.
• As a User, I should be able to filter my card collection by date, rarity, pack, and favorites.
• As a User, I should be able to view statistics for today, this week, this month, and overall.
• As a User, I should be able to view achievements and receive rewards for milestones.
• As a User, I should be able to view and manage different card types and rarities.
• As a User, I should be able to view duplicate cards and receive stardust based on rarity.
• As a User, I should be able to view and purchase different types of packs from the shop.

4. User Personas

• Single User: The primary user of the bot, motivated by educational goals and interested in collecting Pokémon cards.

5. Core User Flows

• User starts learning session -> enters minutes or starts timer -> confirms session end -> receives crystals.
• User spends crystals in the shop -> purchases pack -> opens pack -> views cards -> collects new cards or duplicates.
• User views profile -> checks statistics and achievements -> receives rewards for milestones.

6. Visuals Colors and Theme

[Default — not specified by user]

• primary: #FFCC00 (Pokémon Yellow)
• primary_light: #FFE680
• secondary: #3B4CCA (Pokémon Blue)
• accent: #FF0000 (Pokémon Red)
• highlight: #00FF00 (Success Green)
• bg: #FFFFFF (White)
• surface: #F2F2F2 (Light Grey)
• text: #000000 (Black)
• text_muted: #666666 (Dark Grey)
• border: #CCCCCC (Grey)

7. Signature Design Concept

Interactive Card Opening Experience

The Pearl-Telegram bot will feature an engaging card opening experience that mimics the excitement of opening a physical pack of Pokémon cards. When a user opens a pack, an animated sequence will unfold in the Telegram chat, displaying each card one by one. Users will interact with the animation by clicking "Next" to reveal subsequent cards. If a card is new, a special animation will highlight its uniqueness; if it's a duplicate, the animation will indicate the addition of stardust. This interactive experience will be built using motion/react for smooth transitions and animations.

Landing Hero Motion Brief

The landing hero animation will depict a user inputting study minutes, which transform into crystals. These crystals then cascade into a virtual pack, which opens to reveal a series of cards. The animation will loop every 10 seconds, showing the transformation from learning to reward. The animation will be responsive and maintain clarity even in reduced-motion settings.

8. Interaction Model & Motion Direction

• Intended Interaction Model: Animated
  • The landing page will feature moderate scroll-triggered reveals and hover transitions.
  • Interactive elements will have spring physics for a polished user experience.
  • Each section will have a distinctive core mechanic, such as kinetic typography or morphing SVGs.

9. Non-Functional Requirements

• The bot must be responsive and handle user interactions smoothly.
• Data integrity must be maintained across all JSON files.
• The system should be scalable to accommodate additional features and mechanics.

10. Tech Stack

• Frontend: Aiogram 3 for Telegram bot interface
• Backend: Python
• Data Storage: JSON files for user profiles, cards, packs, and configurations

11. Assumptions and Constraints

• The bot is designed for a single user, with no need for multi-user authentication.
• All configurations and data are stored in JSON files, which must be easily editable.
• The bot's architecture must support future expansion and new feature integration.

12. Glossary

• Crystals: In-game currency earned through learning.
• Stardust: A resource gained from duplicate cards, used for various in-game enhancements.
• Pack: A collection of cards that can be purchased and opened by the user.
• Card Rarity: The likelihood of obtaining a specific card, categorized as Common, Uncommon, Rare, Epic, Legendary, or Mythic.