Activity Reminder Bot

# Activity Reminder Bot

Telegram-first personal productivity assistant for activity reminders. The bot stores reminder data in Google Sheets, sends scheduled alarms through Telegram, and exposes a small FastAPI health/readiness API for VPS monitoring. There is no web dashboard; every user workflow runs through Telegram buttons and natural language input.

## Feature Summary

- Create reminders from natural Indonesian/English text.
- Preview before saving to Google Sheets.
- Automatic alarm notifications with done, snooze, reschedule, and delete actions.
- Snooze options: 5 minutes, 10 minutes, 30 minutes, 1 hour, and tomorrow.
- Repeat reminders: one-time, daily, weekly, monthly.
- Today schedule, weekly schedule, search, history, edit, delete, cleanup, and settings menu.
- Google Sheets as the primary storage layer.
- APScheduler-based due-reminder scanner.
- FastAPI `/health` and `/ready` endpoints for runtime checks.
- Docker Compose deployment for Ubuntu VPS.

## Folder Structure

```text
Activity Reminder Bot/
  apps/activity_reminder_bot/
    api/                 FastAPI health/readiness app
    bot/                 Aiogram handlers, keyboards, states, polling entrypoint
    core/                Settings and logging
    models/              Reminder models and enums
    scheduler/           APScheduler due-reminder scanner
    services/            Google Sheets repository, reminder use cases, formatters
  packages/reminder_core/
    parsers/             Natural language reminder parser
  docs/                  Product, architecture, deployment, and Hermes docs
  scripts/               Operational helper scripts
  tests/                 Parser and repeat logic tests
```

## Important Files

- `apps/activity_reminder_bot/bot/main.py`: Telegram bot entrypoint.
- `apps/activity_reminder_bot/bot/handlers.py`: Telegram menu, create, preview, search, edit, delete, snooze, and alarm actions.
- `apps/activity_reminder_bot/scheduler/reminder_scheduler.py`: Periodic alarm scanner.
- `apps/activity_reminder_bot/services/sheets.py`: Google Sheets repository and sheet layout management.
- `packages/reminder_core/parsers/natural_datetime.py`: Natural language date/time parser.
- `apps/activity_reminder_bot/api/main.py`: FastAPI health and readiness endpoints.
- `docker-compose.yml`: VPS runtime services.
- `.env.example`: Required environment variable template.

## Install Dependencies

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
```

## Run Locally

```bash
cp .env.example .env
# fill TELEGRAM_BOT_TOKEN, GOOGLE_SHEETS_SPREADSHEET_ID, GOOGLE_SERVICE_ACCOUNT_JSON_BASE64
python -m activity_reminder_bot.bot.main
```

Run the API locally:

```bash
uvicorn activity_reminder_bot.api.main:app --host 0.0.0.0 --port 8000
```

## Build and Run With Docker

```bash
cp .env.example .env
docker compose build
docker compose up -d
curl http://127.0.0.1:8022/health
curl http://127.0.0.1:8022/ready
```

## Required Environment Variables

- `TELEGRAM_BOT_TOKEN`: Bot token from BotFather.
- `GOOGLE_SHEETS_SPREADSHEET_ID`: Spreadsheet ID used as storage.
- `GOOGLE_SERVICE_ACCOUNT_JSON_BASE64`: Base64 encoded Google service account JSON.

Optional:

- `TELEGRAM_ADMIN_IDS`: Comma-separated Telegram user IDs for future admin-only controls.
- `APP_TIMEZONE`: Default `Asia/Jakarta`.
- `GOOGLE_SHEETS_WORKSHEET_NAME`: Default `Sheet1`.
- `SCHEDULER_SCAN_SECONDS`: Default `30`.
- `ALARM_REPEAT_ENABLED`: Default `true`.
- `ALARM_REPEAT_INTERVAL_SECONDS`: Default `60`.
- `ALARM_REPEAT_MAX_COUNT`: Default `5`.
- `ALARM_DELETE_PREVIOUS_MESSAGE`: Default `true`, sends a new notification and removes the previous alarm message.
- `LOG_LEVEL`: Default `INFO`.

## Google Sheets Columns

The bot manages this header row automatically on the configured worksheet:

```text
ID, User ID, Nama User, Nama Kegiatan, Deskripsi, Tanggal, Jam, Repeat, Status, Created At, Updated At, Notified At
```

Share the spreadsheet with the service account email as editor.

## Quality Gates

```bash
ruff check .
mypy apps packages
pytest -q
docker compose build
```

## Manual Testing Checklist

- `/start` shows the main menu.
- Free text creates a reminder preview.
- Preview save writes to Google Sheets.
- Invalid date/time returns a safe error message.
- Today schedule shows active reminders for the current date.
- Weekly schedule shows reminders for the next 7 days.
- `/search meeting` returns matching reminders.
- Edit updates name, date/time, repeat, and notes.
- Delete requires confirmation.
- Cleanup menu deletes only confirmed completed/deleted history or invalid rows.
- Scheduler sends alarm at due time.
- Unfinished alarms repeat until completed or max repeat count is reached.
- Alarm buttons work: done, snooze, reschedule, delete.
- Repeat reminders roll forward after done.
- `/ready` reports missing env before secrets are filled and ready after they are filled.

## Next Development Suggestions

- Add per-user timezone settings.
- Add reminder import/export commands.
- Add stronger date parsing for mixed Indonesian month names.
- Add Google Sheets row-lock retry strategy for high-volume multi-user use.
- Add admin-only broadcast and runtime diagnostics.