# Lagomare GateKeeper Bot

A Telegram bot for managing access to gates, with user roles, credential management, and integration with AVConnect.

---

## Features

- **Role-based access:** Admins, members, and guests with different permissions.
- **Gate control:** Open gates via Telegram commands or inline keyboards.
- **Credential management:** Users can set and update their own credentials.
- **Access requests:** Guests can request access; admins can grant or revoke it.
- **Grant tracking:** Usage of guest grants is tracked.
- **Integration:** Connects to AVConnect for actual gate operations.

---

## Project Structure

```
lagomareGateKeeperBot/
│
├── bot.py                # Main entry point
├── config.py             # Bot configuration loader
├── handlers/             # Telegram command and callback handlers
├── models/               # Data models (users, gates, etc.)
├── services/             # External integrations (e.g., AVConnect)
├── utils/                # Helper functions
├── data/                 # Persistent data (users.json, gates.json, etc.)
└── README.md
```

---

## Setup

1. **Clone the repository:**
   ```sh
   git clone https://git.dreucci.it/noettore/lagomareGateKeeperBot.git
   cd lagomareGateKeeperBot
   ```

2. **Install dependencies:**
   ```sh
   pip install -r requirements.txt
   ```

3. **Configure the bot:**
   - Edit `data/config.json` with your bot token and settings.
   - Add gate and user data to `data/gates.json` and `data/users.json`.

4. **Run the bot:**
   ```sh
   python bot.py
   ```

---

## Usage

- `/start` — Show main menu (with inline keyboard based on user role)
- `/setcredentials <username> <password>` — Set your AVConnect credentials
- `/opengate <gate>` — Open a gate
- `/requestaccess` — Guests can request access
- `/grantaccess <user_id> <gate|all> <expires_at>` — Admins grant access

---

## Development

- Handlers are in the `handlers/` directory, grouped by feature.
- Data models are in `models/`.
- External services (like AVConnect) are in `services/`.
- Utilities and keyboard builders are in `utils/`.

---

## License

MIT License

---

## Authors

- [Ettore Dreucci](https://ettore.dreucci.it)