System Requirements Document for vortex-casino-bot

1. Introduction

vortex-casino-bot is a Telegram casino bot. The product intent is to let a person play casino games inside Telegram: a player opens a chat with the bot, starts a game session, places a wager, and sees the outcome of each round — all without leaving Telegram. The bot is operated and maintained by a Bot Operator whose goal is to keep it available and functioning so players can play.

The audience is the casual-to-serious mobile player who wants a fast thrill with a sense of occasion, reached through a private Telegram chat on a phone. The product is delivered as a Telegram bot; it is not a standalone web or native application.

2. System Overview

vortex-casino-bot is delivered entirely through Telegram. There is no first-party custom application UI: the player's surface is the Telegram chat with the bot, and the bot's controls are rendered as Telegram messages and inline keyboards. The Bot Operator's surface is likewise the running bot itself — its availability and responsiveness are the operator's observable product state.

Current actors:

• Casino Player — the person who uses the Telegram casino bot to play casino games. Their goal is to start a game session inside Telegram, place wagers, and see the outcome of each round.
• Bot Operator — the person who runs and maintains the Telegram casino bot. Their goal is to keep the bot available and functioning so players can play.

Current accepted behavior: the bot is deployed and available; the player reaches it through a Telegram chat; the player starts a game session; the player places a wager; the bot retains sufficient round and wager state to return each round outcome; the player sees the outcome of each round.

Narrow exclusions: no custom first-party web or native UI is part of the current product; the product is a Telegram bot and nothing else is currently accepted. No adjacent account-management, payment-processing, social, or tournament capabilities are accepted by the source.

2a. Product Interpretation and Delivery Boundary

The product is a Telegram bot, and Telegram is the delivery and access owner for the player's interaction surface. The player does not create a vortex-casino-bot account and does not log in to a first-party application; the player reaches the bot through a Telegram chat, and Telegram owns that chat surface, its identity, and its message delivery. The bot owns the game session, the wager, the round state, and the round outcome it returns into that chat.

The Bot Operator's responsibility is operational: keeping the bot deployed, available, and functioning. Operator-facing status is expressed through the bot's own running state and its observable responsiveness to players.

Current boundary: the Telegram bot, its game session, its wager handling, its round state retention, and its round outcome delivery. Future boundary: anything not accepted by the source — including any first-party application surface, any additional game catalog beyond "casino games" as stated, and any account, payment, or social capability — is out of current scope and is not implemented now.

2b. Source Content Inventory

Not applicable. No reference directive in this project declares a content_source, so no source content inventory is produced.

2c. Page Content and Component Coverage

The current product has no first-party custom pages. The delivery shape is provider-managed: the player's surface is the Telegram chat with the bot, and the bot's controls are Telegram messages and inline keyboards. The single first-party surface is the bot itself, which is a headless service that renders into Telegram rather than a custom page.

Telegram Chat with the Bot (provider-managed surface)

• Information and state: the bot's greeting and session entry message; the current game session state; the current wager; the current round state; the round outcome once resolved; the player's live balance as displayed by the bot; muted metadata such as odds and timestamps.
• Primary actions: start a game session; place a wager; confirm the wager; spin/play the round; view the round outcome; continue with another round.
• Supporting actions: view the current balance; view the current wager before confirming; return to the session entry after a round.
• Domain entities: Casino Player (as represented by the Telegram chat identity), game session, wager, round, round outcome, balance.
• Component responsibilities: the bot's message renderer (session entry, wager prompt, round result), the inline keyboard renderer (capsule rows for wager selection, confirmation, and continuation), the round engine (resolves the round and produces the outcome), the state store (retains round and wager state so the outcome can be returned), and the Telegram transport (delivers messages and receives player input).
• Loading state: while a round is resolving, the bot indicates that the round is in progress rather than leaving the chat silent.
• Empty state: before a session is started, the bot presents the session entry rather than a wager prompt; before a wager is placed, no round is resolved.
• Success state: the round outcome is returned into the chat and the player can continue.
• Error state: if the bot cannot resolve or return a round, the player is told the round did not complete rather than being left without a result.
• Recovery state: the player can retry the round or return to the session entry; the bot retains sufficient round and wager state to return the outcome rather than losing the round silently.

Bot Operator Runtime Surface (first-party operational surface)

• Information and state: whether the bot is deployed and reachable; whether it is serving players; its uptime and responsiveness as observable operational state.
• Primary actions: deploy the bot; keep it running; observe its availability.
• Supporting actions: restart or redeploy the bot when it is not serving players.
• Domain entities: bot deployment, bot runtime, availability state.
• Component responsibilities: the deployment/runtime host, the bot process, and the availability signal the operator observes.
• Loading state: during deployment or restart, the bot is not yet serving players.
• Empty state: before first deployment, no bot is available to players.
• Success state: the bot is running and serving players.
• Error state: the bot is unreachable or not responding to players.
• Recovery state: the operator redeploys or restarts the bot until it is serving players again.

3. Functional Requirements

FR-1 — Deploy the Telegram casino bot (explicit) As a Bot Operator, I should deploy the Telegram casino bot so that it is available before a player can start a game session.

• Trigger/input: the operator deploys the bot.
• Observable result: the bot is deployed and available.
• Access state: operator-side operational action; no player-facing access involved.
• Failure/recovery: if deployment fails, the bot is not available and the operator redeploys until it is.
• Continuation: once available, players can reach the bot through a Telegram chat.
• Acceptance: the bot is deployed and reachable before any player starts a game session.

FR-2 — Reach the bot through a Telegram chat (required_inference) As a Casino Player, I should reach the bot through a Telegram chat so that I can start a game session.

• Trigger/input: the player opens a Telegram chat with the bot.
• Observable result: the bot responds in that chat with its session entry.
• Access state: the player's access is through Telegram; no first-party account is created.
• Failure/recovery: if the bot does not respond, the player cannot start a session and must retry later.
• Continuation: the player proceeds to start a game session.
• Acceptance: the player reaches the bot through a Telegram chat and receives its session entry.

FR-3 — Start a game session (explicit) As a Casino Player, I should start a game session inside Telegram so that I can play casino games through the bot without leaving Telegram.

• Trigger/input: the player starts a session from the bot's session entry.
• Observable result: an active game session exists for that player in that chat.
• Access state: within the Telegram chat with the bot.
• Failure/recovery: if the session cannot be started, the player is told so and can retry from the session entry.
• Continuation: the player proceeds to place a wager.
• Acceptance: the player has an active game session and can place a wager.

FR-4 — Place a wager (explicit) As a Casino Player, I should place a wager so that I can play a round.

• Trigger/input: the player selects and confirms a wager within the session.
• Observable result: the wager is recorded against the current round.
• Access state: within the active game session in the Telegram chat.
• Failure/recovery: if the wager cannot be accepted, the player is told so and can select a wager again.
• Continuation: the player plays the round.
• Acceptance: the wager is recorded and the round can be played.

FR-5 — Play a round and receive its outcome (explicit) As a Casino Player, I should play a round and see the outcome of each round so that I know the result of my wager.

• Trigger/input: the player plays the round after placing a wager.
• Observable result: the round resolves and its outcome is returned into the Telegram chat.
• Access state: within the active game session in the Telegram chat.
• Failure/recovery: if the round cannot be resolved or its outcome cannot be returned, the player is told the round did not complete and can retry.
• Continuation: the player can continue with another round.
• Acceptance: the player sees the outcome of the round in the chat.

FR-6 — Retain round and wager state to return each round outcome (required_inference) As a Casino Player, I should have my round and wager state retained so that each round outcome can be returned to me.

• Trigger/input: the player places a wager and plays a round.
• Observable result: the bot retains sufficient round and wager state to return the outcome of that round.
• Access state: within the active game session in the Telegram chat.
• Failure/recovery: if state is insufficient to return an outcome, the round cannot be completed and the player is told so.
• Continuation: the retained state allows the outcome to be returned and the player to continue.
• Acceptance: each round's outcome is returned using retained round and wager state.

FR-7 — Keep the bot available and functioning (required_inference) As a Bot Operator, I should keep the bot available and functioning so that players can play.

• Trigger/input: the operator monitors and maintains the running bot.
• Observable result: the bot is running and serving players.
• Access state: operator-side operational action.
• Failure/recovery: if the bot stops serving players, the operator restarts or redeploys it.
• Continuation: players can continue to reach the bot and play.
• Acceptance: the bot is running and serving players.

4. User Personas

Casino Player

The Casino Player is the person who uses the Telegram casino bot to play casino games. Their product context is a private Telegram chat on a phone: they do not install a separate application, do not visit a website, and do not manage a first-party account. Their primary goal is to start a game session inside Telegram, place wagers, and see the outcome of each round.

Their distinct accepted responsibilities are: reaching the bot through a Telegram chat, starting a game session, placing a wager, playing a round, and reading the round outcome. Their relevant inputs and decisions are the choice to start a session, the selection and confirmation of a wager, and the decision to continue with another round. Their interaction with the other accepted participant is indirect: the Bot Operator keeps the bot available so the player's session can run, but the player never interacts with the operator directly.

Observable success for the Casino Player: they can play casino games through the bot without leaving Telegram, and they see the outcome of each round they play. What makes this role's work different from the Bot Operator's is that the player's work is the play itself — session, wager, round, outcome — while the operator's work is the availability of the surface the player plays on.

Bot Operator

The Bot Operator is the person who runs and maintains the Telegram casino bot. Their product context is the bot's runtime: deployment, availability, and responsiveness. Their primary goal is to keep the bot available and functioning so players can play.

Their distinct accepted responsibilities are: deploying the bot so it is available before a player can start a game session, keeping it running, and restoring it when it is not serving players. Their relevant inputs and decisions are whether the bot is reachable and whether it is serving players, and whether to redeploy or restart it. Their interaction with the other accepted participant is one-directional: the operator's work enables the Casino Player's session, but the operator does not participate in the player's rounds.

Observable success for the Bot Operator: the bot is running and serving players. What makes this role's work different from the Casino Player's is that the operator never places a wager or plays a round; the operator's success is measured by the availability of the bot that the player uses.

5. Core User Flows

Flow A — Casino Player: play a round in Telegram

1. The Casino Player opens a Telegram chat with the vortex-casino-bot. This is the player's starting context: a private chat on their phone, with no first-party account and no separate application.
2. The bot responds in the chat with its session entry. The player's access is through Telegram; Telegram owns the chat surface and message delivery.
3. The player starts a game session from the session entry. Observable result: an active game session exists for that player in that chat.
4. The player selects a wager and confirms it. Observable result: the wager is recorded against the current round.
5. The player plays the round. The bot resolves the round using the retained round and wager state.
6. The bot returns the round outcome into the Telegram chat. Observable result: the player sees the outcome of the round.
7. The player continues with another round, returning to step 4, or ends the session.

Material failure and recovery: if the bot does not respond at step 2, the player cannot start a session and must retry later. If the session cannot be started at step 3, the player is told so and can retry from the session entry. If the wager cannot be accepted at step 4, the player is told so and can select a wager again. If the round cannot be resolved or its outcome cannot be returned at steps 5–6, the player is told the round did not complete and can retry, because the bot retains sufficient round and wager state to return the outcome rather than losing the round silently.

Flow B — Bot Operator: deploy and keep the bot available

1. The Bot Operator deploys the Telegram casino bot. This is the operator's starting context: the bot's runtime, before any player can start a game session.
2. Observable result: the bot is deployed and available.
3. The operator keeps the bot running and observes whether it is serving players.
4. Players can now reach the bot through a Telegram chat and play, as in Flow A.

Material failure and recovery: if deployment fails at step 1, the bot is not available and the operator redeploys until it is. If the bot later stops serving players, the operator restarts or redeploys it until it is serving players again. Continuation: once the bot is running and serving players, players can continue to reach it and play.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. The muse is Zaha Hadid: fluid parametric grandeur, where the vortex is the architecture. The headline idea is that the bot's chat surface should read as a composed descent through one continuous surface — a high-roller atrium carved from a single form — rather than a stack of buttons.

Mode: dark mode only.

Colour tokens by role:

Ratio: 70% void, 20% surface, 7% gold, 3% magenta. No blue anywhere.

Typography:

• Headings: Jost, light-to-regular weights (300/400) at very large sizes with tight tracking (−0.02em) and sentence case — architectural, not shouty. The wordmark VORTEX is set at 300 weight, letterspaced +0.18em, all caps, so it reads as an engraved plate on a curved wall.
• Numerals are the display type: balances, multipliers and round results are set at 200 weight, 88–140px, so a number feels like a monument.
• Labels and odds: 500 weight, 11–12px, uppercase, +0.14em tracking.
• Body: Jost.
• Type scale: 1.25 modular with a display tier — 140 / 88 / 56 / 40 / 28 / 18 / 16 / 13 / 11. Mobile display starts at 56px (clamp(56px, 12vw, 140px) for the hero numeral), headings clamp(28px, 5vw, 56px), body 16px/1.6, labels 11px.

Shape language: parametric curves everywhere, and no right angles on the outer silhouette. Section boundaries are cut on a long diagonal or a sweeping arc rather than a horizontal rule. Cards have one soft-curved edge and one straight edge, so a stack of them reads as a continuous ribbon folding down the page. Buttons are capsules with a 2px luminous top edge that catches the gold. The wheel is a true circle with a hairline outer ring and a magenta sweep arc. Corner radii: 24px on panels, 999px on capsules, 4px only on the tiny odds chips so they stay legible.

Layout: a single centred column with a strong diagonal spine — every section is offset 6–10% left or right of centre in alternation, so scrolling feels like walking down a curved ramp. Full-bleed curved section boundaries separate: hero, the game table, the wager rail, the round history, the operator status block. The Telegram inline keyboard is rendered as a real component: capsule rows that curve in a shallow arc, each button a capsule with its own gold or magenta state. Generous negative space above the wheel — a full viewport of near-empty void with the wheel small and low, so the drama is the emptiness before the spin. At 375px the diagonal offset halves and the keyboard rows stack full-width; at 768px the offset is 4%; at 1280px the column is 720px wide with the diagonal spine visible.

Imagery: no photography and no clip art. The imagery is generated geometry: a parametric wheel rendered in CSS/SVG conic gradients with hairline radial rules, flowing ribbon shapes as section dividers, and a subtle topographic line field (thin 1px strokes at 8% opacity) drifting behind the hero like a contour map of a vortex. The single dramatic image is the wheel itself, treated as an engineered object — concentric rings, engraved tick marks, a gold pointer. Operator status is expressed as a small instrument dial, not an icon.

Avoid: any blue, indigo or violet accent (#0057FF, #2563EB, #6366F1 and neighbours) — the palette is void, champagne gold and magenta only; Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins and system-ui as heading or body fonts; centred headline + subtext paragraph + blue button + gradient-blob hero; a grid of identical hover-lift cards for game modes or history rows; right angles and hard rectangular section dividers — boundaries curve or cut on a diagonal; cartoon dice, slot-machine clip art, emoji-confetti, or red-velvet-and-gold casino kitsch; glassmorphism blur panels over soft multicolour gradients; any text or control cropped, clipped or covered — curves and line fields may bleed off edges, readable content never does.

Readable text and controls stay whole at every viewport: headlines, wordmarks, labels, numbers, cards' text and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Imagery, decoration and motion may be cropped, bled off an edge, rotated, overlapped or cut exactly as the direction asks, as long as it covers no readable text or control. Moving and scrollable content may cross the viewport or container edge by design: judge it by whether it actually moves or scrolls and whether every item becomes fully readable as it passes, never by the item cut at the edge in a still frame. With prefers-reduced-motion it stops and shows whole items: they wrap into rows, or sit in a horizontally scrollable row (overflow-x: auto) whose further items are reached by scrolling. Where a direction, requirement, brief or finding asks readable text or a control to be cropped, clipped, covered or run off an edge, keep it whole and carry the gesture with imagery or decoration instead; for readable text and controls this rule takes precedence.

The generic indigo/blue-on-white SaaS template is forbidden for this project.

7. Signature Design Concept

The signature concept is the vortex wheel as hero, in a void. The first screen is a near-empty deep-void field (#0B0B10) with a faint drifting topographic line field behind it. Low and slightly right of centre sits the wheel — a 320px circle on mobile, 560px on desktop — rendered as concentric hairline rings with a gold pointer at 12 o'clock and one magenta sweep arc mid-rotation. Above it, flush left and bleeding to the container edge, a stacked headline in Jost 300: SPIN THE on line one, VORTEX on line two at clamp(56px, 12vw, 140px), letterspaced, with the letters slightly overlapping the wheel's upper-left arc so type and object are one composition. Beneath the wheel, pinned left, a single gold capsule CTA Open in Telegram and beside it, small and muted, Live balance · 12,480 rounds today.

This concept recomposes only accepted content and controls: the wheel is the product's own spin, the CTA is the player's entry into the Telegram chat, and the muted line is the bot's live state. It adds no new behaviour, page, or destination. The composition is deliberately asymmetric — no centred headline, no subtext paragraph, no blue button, no gradient blob. The first screen is one object in a void with monumental type cutting across it.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: cinematic Hero Dimensionality: dimensional_css

Landing Hero Motion Brief

• Focal subject: the vortex wheel — concentric hairline rings, a gold pointer at 12 o'clock, and one magenta sweep arc — sitting low and slightly right of centre in a full viewport of void, with the SPIN THE / VORTEX headline overlapping its upper-left arc.
• Input → transformation → outcome thesis: the player's entry into the Telegram chat is the input; the wheel's continuous slow rotation and the magenta sweep arc are the transformation; the outcome is the player arriving in the bot's session entry inside Telegram, with the wheel settled and the CTA ready. The motion expresses the product's own spin — it does not simulate a round the player has not placed.
• Motion vocabulary: one continuous slow rotation of the hairline ring around the wheel (40s, linear, infinite) as ambient life; a scroll-linked parallax where the curved section boundaries shift 12% against the content; the spin itself is a 3.2s decelerating rotation of the wheel with a magenta sweep arc that trails the gold pointer and settles with a single soft overshoot; numbers count up with a 600ms ease-out; section entrances are a 24px upward drift + opacity over 500ms, staggered 80ms.
• Composed first frame: deep void #0B0B10 with the topographic line field faintly drifting; the wheel low and slightly right of centre, hairline rings visible, gold pointer at 12 o'clock, magenta sweep arc mid-rotation; SPIN THE and VORTEX stacked flush left and bleeding to the container edge, overlapping the wheel's upper-left arc; the gold capsule CTA Open in Telegram pinned left beneath the wheel with the muted live-state line beside it.
• Reduced-motion state: with prefers-reduced-motion everything stops — the ring is static, the wheel result appears instantly, and counts render final values. The composition remains whole: the wheel, the headline, the CTA and the live-state line all remain fully readable and inside the viewport.

9. Non-Functional Requirements

NFR-1 — Telegram as the delivery surface (explicit) The product is a Telegram bot. The player's interaction surface is the Telegram chat with the bot, and the bot's controls are Telegram messages and inline keyboards. Rationale: this is the explicit hard constraint in the authoritative source.

NFR-2 — Bot availability before play (required_inference) The Telegram bot must be deployed and available before a player can start a game session. Rationale: required to make the accepted current journey executable without adding a product capability.

NFR-3 — Reachability through a Telegram chat (required_inference) The player must reach the bot through a Telegram chat before starting a game session. Rationale: required to make the accepted current journey executable without adding a product capability.

NFR-4 — Round and wager state retention (required_inference) The bot must retain sufficient round and wager state to return each round outcome. Rationale: required to make the accepted current journey executable without adding a product capability.

NFR-5 — Readable text and controls at every viewport (explicit, from the creative direction) Headlines, wordmarks, labels, numbers, cards' text and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling to fit, and no other element covers any part of them. Rationale: the creative direction states this rule takes precedence for readable text and controls.

NFR-6 — Reduced-motion support (explicit, from the creative direction) With prefers-reduced-motion, the ring is static, the wheel result appears instantly, and counts render final values. Rationale: the creative direction specifies this state.

10. Tech Stack

• Bot platform: Telegram Bot API — the product is a Telegram bot, and Telegram owns the chat surface, message delivery, and inline keyboard rendering. (explicit)
• Backend: Python with FastAPI for the bot's service layer, handling session start, wager placement, round resolution, and round outcome delivery. (default — not specified by user)
• Storage: a persistent store for round and wager state sufficient to return each round outcome. (required_inference)
• Containerization: Docker and docker-compose for packaging and running the bot service. (default — not specified by user)
• Frontend: none. There is no first-party custom UI; the player's surface is the Telegram chat. (explicit)

11. Assumptions and Constraints

• Assumption: the bot is deployed and available before a player can start a game session. (required_inference)
• Assumption: the player reaches the bot through a Telegram chat, and Telegram owns that chat surface and its identity. (required_inference)
• Assumption: the bot retains sufficient round and wager state to return each round outcome. (required_inference)
• Constraint: the product is a Telegram bot. (explicit)
• Constraint: no first-party custom UI is part of the current product. (explicit, from the delivery shape)
• Constraint: no blue, indigo or violet accent is used; the palette is void, champagne gold and magenta only. (explicit, from the creative direction)
• Constraint: Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins and system-ui are not used as heading or body fonts. (explicit, from the creative direction)
• Constraint: the generic indigo/blue-on-white SaaS template is forbidden for this project. (explicit)
• Out of current scope: any first-party application surface, any additional game catalog beyond "casino games" as stated, and any account, payment, or social capability. (explicit boundary)

12. Glossary

• Telegram bot — the product's delivery form: a bot that runs on Telegram and interacts with players through Telegram chats and inline keyboards.
• Casino Player — the accepted persona who plays casino games through the bot inside Telegram.
• Bot Operator — the accepted persona who runs and maintains the bot so players can play.
• Game session — the active state a player starts inside Telegram before placing a wager and playing a round.
• Wager — the amount the player selects and confirms for a round.
• Round — a single play of a casino game, resolved by the bot and returning an outcome.
• Round outcome — the result the bot returns into the Telegram chat for a played round.
• Inline keyboard — Telegram's button rows rendered inside the chat, used as the bot's controls.
• Vortex wheel — the signature visual object: concentric hairline rings with a gold pointer and a magenta sweep arc.