🧺 LaundryBot

🌐 Visit the project website

A Telegram bot that lets students in a university dormitory book and manage laundry machines through a guided conversation — replacing a fragmented, message-based manual process with an automated, persistent, self-service system.

Table of Contents

• Preview
• Features
• Tech Stack
• Project Structure
• Getting Started
• Usage
• Configuration and Environment
• Security
• Contributing
• License

Preview

Before LaundryBot Bookings managed manually via messages and handwritten notes	After LaundryBot Self-service booking directly in Telegram

Features

• Guided conversational booking flow: choose machine type (washer/dryer) → select a specific available machine → set duration in minutes
• Manages 5 washing machines (A–E) and 4 dryers (1–4), only surfacing machines not currently in use
• /view shows all active bookings with live remaining time
• /free releases a machine manually before its timer expires
• Automatic release: a per-booking background task frees the machine when time is up
• Bookings persist to a local JSON file and survive restarts — expired entries are discarded on load
• Runs via long polling — no open ports, no server, no webhook infrastructure required

Tech Stack

• Language: Python 3.10+
• Framework: python-telegram-bot >=22.0 (async, ConversationHandler-based API)
• Storage: local JSON file (data/bookings.json) — no database dependency

requirements.txt includes Flask, intended for a future webhook or web dashboard. The current implementation runs exclusively via long polling and does not instantiate a Flask app.

Design Decisions

Long polling was chosen over webhooks deliberately: the bot runs on a student laptop, not a server with a public IP or SSL certificate. Long polling requires no infrastructure setup and is functionally equivalent for a low-traffic single-dorm deployment. If the user base grows or the bot is redeployed on a VPS, switching to webhooks is a one-line change in PTB.

JSON was chosen over SQLite for the same reason — the booking state is small (at most 9 concurrent entries) and human-readable for debugging. A database would add a native dependency with no practical benefit at this scale.

Project Structure

LaundryBot/
├── app.py              # Bot logic — conversation handlers, booking and release
├── config.py           # Bot token (not committed — copied from config.example.py)
├── config.example.py   # Configuration template
├── requirements.txt
├── data/
│   ├── bookings.json   # Active bookings (runtime-generated, not committed)
│   └── users.json      # Present in repo but not currently referenced by app.py
└── images/
    ├── before.png
    └── after.png

Getting Started

Prerequisites

• Python 3.9 or later
• A Telegram bot token from @BotFather

Installation

git clone https://github.com/mirconegri/LaundryBot.git
cd LaundryBot
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

Copy the configuration template and add your token:

cp config.example.py config.py   # Windows: copy config.example.py config.py

# config.py
BOT_TOKEN = "your_token_here"

Run the bot:

python app.py

Open Telegram, search for your bot, and send /start.

Usage

Command	Description
/start	Begin a new booking (guided conversation)
/view	Show all active bookings with remaining time
/free	Release a machine before the timer expires
/cancel	Abort the current operation mid-conversation
/help	List available commands

Example booking flow:

/start
> Lavatrice   Asciugatrice
[user selects Lavatrice]
> Which machine? A  B  C  D  E
[user selects A]
> How many minutes?
[user enters 40]
> Machine A booked for 40 minutes.

Configuration and Environment

Variable	File	Required	Description
BOT_TOKEN	config.py	Yes	Telegram bot token from @BotFather
ADMIN_CHAT_ID	config.py	No	Reserved for future admin commands — not read by any current handler

config.py is excluded from version control via .gitignore. No .env file is used.

Security

• Token handling: BOT_TOKEN lives in config.py, which is listed in .gitignore and never committed. The example file (config.example.py) contains only a placeholder.
• No user data leaves the host: all booking state is written to a local JSON file on the machine running the bot. No external database, no third-party storage.
• No open ports: long polling means the bot initiates all connections outbound to Telegram's servers. There is no listener, no exposed endpoint, and no SSL certificate required.
• No authentication layer: the bot is currently open to anyone who finds it on Telegram. For a real deployment, restrict access via a WHITELIST of allowed chat_id values checked at the start of each handler.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes with a clear message
4. Open a Pull Request

For bugs or feature ideas, open an Issue.

Author

Mirco Negri — Computer Science @ UniTrento

License

This project is licensed under the MIT License — see the LICENSE file for details.