# JIGAIDO — Specification

> Named after Nanami Kento's Cursed Technique restriction. Suppresses power during normal hours, exerts it during overtime. A bounty tracker that keeps you honest when the clock runs long.

---

## Overview

JIGAIDO is a Telegram bot that lets groups and individuals track bounties — tasks, obligations, and deadlines — with optional due dates and personal tracking.

- **Group mode**: Each Telegram group has its own bounty list. Anyone can add bounties. Only creator can edit/delete.
- **DM mode**: Personal bounty list. Anyone can manage their own bounties.
- **Tracking**: Users can track any bounty (group or personal) to their tracking list.
- **Due dates**: Free-form text (`"april 15"`, `"in 3 days"`, `"tomorrow"`) parsed at add time, stored as Unix timestamp. If unparseable, stored as `NULL`.
- **Links**: Optional. If provided, stored with the bounty.
- **Informed by**: Every bounty stores the Telegram username of who posted/added it.

---

## Architecture

### Stack
- **Bot**: `python-telegram-bot` (pure Python, no C extensions)
- **Storage**: Per-user JSON files (zero-setup, no DB server)
- **Date parsing**: `dateparser`
- **Runtime**: Python 3.10+
- **Deployment**: Any $5 VPS with Python 3.10+

### Directory Structure

```
jigaido/
├── apps/
│   └── telegram-bot/     # Telegram bot app
│       ├── bot.py       # Entrypoint
│       ├── commands.py  # Command handlers
│       ├── storage.py   # JSON file storage
│       ├── data/
│       │   └── users/   # Per-user JSON files
│       │       └── {telegram_user_id}.json
│       ├── requirements.txt
│       └── .env.example
├── SPEC.md          # This document
├── README.md
└── CONTRIBUTING.md
```

### Storage Design

**File structure (`data/users/{telegram_user_id}.json`):**

```json
{
  "user_id": 123,
  "username": "alice",
  "personal_bounties": [
    {
      "id": 1,
      "text": "Fix login bug",
      "link": "https://github.com/example/repo/issues/1",
      "due_date_ts": 1735689600,
      "group_id": null,
      "informed_by_username": "alice",
      "created_at": 1735603200
    }
  ],
  "tracked_bounties": [
    {"bounty_id": 5, "group_id": -1001, "created_at": 1735600000},
    {"bounty_id": 3, "group_id": null, "created_at": 1735590000}
  ]
}
```

**Key design decisions:**

1. **Single file per user** — Personal bounties live in the creator's file. Group bounties also live in creator's file with `group_id` set.
2. **Bounty IDs are sequential integers per file** — Not global. Each user's file has its own ID counter.
3. **Atomic writes** — Uses `tempfile` + `rename` for safe writes.
4. **No reminders in v1** — Dropped for simplicity.

---

## Commands

### In Group

| Command | Who | Description |
|---|---|---|
| `/bounty` | anyone | List all bounties in this group |
| `/my` | anyone | List bounties tracked by you |
| `/add <text> [link] [due date]` | anyone | Add a new bounty to the group |
| `/update <bounty_id> [text] [link] [due_date]` | creator only | Update an existing bounty |
| `/delete <bounty_id>` | creator only | Delete a bounty |
| `/track <bounty_id>` | anyone | Add a group bounty to your tracking |
| `/untrack <bounty_id>` | anyone | Remove a bounty from your tracking |

### In DM (1:1 with bot)

| Command | Description |
|---|---|
| `/bounty` | List all your personal bounties |
| `/my` | List bounties you're tracking |
| `/add <text> [link] [due date]` | Add a personal bounty |
| `/update <bounty_id> [text] [link] [due_date]` | Update a personal bounty |
| `/delete <bounty_id>` | Delete a personal bounty |
| `/track <bounty_id>` | Add a personal bounty to your tracking |

### Add/Update Syntax

```
/add Some task description https://example.com in 3 days
/add Just a text reminder
/add https://link-only.example.com tomorrow
```

- `link` is optional
- `due_date` is optional, free-form

---

## Informed By

When a user triggers `/add`, the bot captures `message.from_user.username` and stores it in `informed_by_username`. This is displayed on bounty listings so the group/DM knows who posted or requested the bounty.

---

## Due Date Parsing

Uses `dateparser` library. Examples:
- `"april 15"`, `"April 15, 2026"`
- `"in 3 days"`
- `"tomorrow"`
- `"2026-04-15"`
- `"next friday"`

If parsing fails → `due_date_ts = NULL`. No error is shown to user.

Stored as Unix timestamp. User-facing display can be localized/converted to any timezone at render time.

---

## Error Handling

- Unknown command → help text with available commands
- `/update`/`/delete` by non-creator → "⛔ Group creator only."
- `/track` already tracked → "Already tracking" (idempotent)
- `/untrack` not tracked → "Not tracking" (idempotent)
- Bounty not found → "Bounty not found"

---

## When to Revert to SQLite

- Multiple concurrent users with write conflicts
- Complex queries across users
- Reminder system with proper dedup
- Scale > 1,000 users
- Need ACID guarantees on concurrent writes