Implement new storage design per issue #2

- Replace SQLite db module with file-based JSON storage in ~/.jigaido/ - Group bounties: ~/.jigaido/{group_id}/group.json - User tracking: ~/.jigaido/{group_id}/user_{id}.json - Personal bounties: ~/.jigaido/user_{id}/user.json - Anyone can add bounties to groups; only creator can edit/delete - Bounty IDs are sequential per group, not global - Fix test mock compatibility issues in format_bounty function
2026-04-02 13:48:52 +00:00
parent 2e7b20ed81
commit 8e589fbc47
6 changed files with 381 additions and 264 deletions
--- a/SPEC.md
+++ b/SPEC.md
@@ -8,12 +8,12 @@

 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.
+- **Group mode**: Each Telegram group has its own bounty list. Anyone can add bounties. Only bounty creator can edit/delete.
+- **DM mode**: Personal bounty list. Creator can manage their own bounties.
+- **Tracking**: Users can track group bounties 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.
+- **Created by**: Every bounty stores the Telegram username of who created it.

 ---

@@ -21,7 +21,7 @@ JIGAIDO is a Telegram bot that lets groups and individuals track bounties — ta

 ### Stack
 - **Bot**: `python-telegram-bot` (pure Python, no C extensions)
- **Storage**: Per-user JSON files (zero-setup, no DB server)
+- **Storage**: Per-group JSON files (zero-setup, no DB server)
 - **Date parsing**: `dateparser`
 - **Runtime**: Python 3.10+
 - **Deployment**: Any $5 VPS with Python 3.10+
@@ -29,54 +29,75 @@ JIGAIDO is a Telegram bot that lets groups and individuals track bounties — ta
 ### 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
+~/.jigaido/                    # Data directory (home of user running bot)
+├── {group_id}/
+│   ├── group.json              # Group bounties
+│   └── user_{user_id}.json    # User tracking within this group
+└── user_{user_id}/
+    └── user.json              # User's personal bounties (DM mode)
 ```

 ### Storage Design

-**File structure (`data/users/{telegram_user_id}.json`):**
+**File structure (`~/.jigaido/{group_id}/group.json`):**

 ```json
 {
-  "user_id": 123,
-  "username": "alice",
-  "personal_bounties": [
+  "group_id": -100123456789,
+  "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_by_user_id": 123456,
+      "created_by_username": "alice",
+      "created_at": 1735603200
+    }
+  ]
+}
+```
+
+**File structure (`~/.jigaido/{group_id}/user_{user_id}.json`):**
+
+```json
+{
+  "user_id": 123456,
+  "tracked": [
+    {"bounty_id": 1, "tracked_at": 1735600000}
+  ]
+}
+```
+
+**File structure (`~/.jigaido/user_{user_id}/user.json`):**
+
+```json
+{
+  "user_id": 123456,
+  "username": "alice",
+  "bounties": [
+    {
+      "id": 1,
+      "text": "Personal task",
+      "link": "https://example.com/task",
+      "due_date_ts": null,
+      "created_by_user_id": 123456,
+      "created_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.
+1. **Data at ~/.jigaido/** — Not inside the app directory, so data persists across app updates.
+2. **Per-group bounties** — All group bounties stored in `group.json`, not scattered across creator files.
+3. **Per-user tracking** — Each user's tracking within a group stored in their own `user_{id}.json`.
+4. **Bounty IDs are sequential per group** — Not global. Each `group.json` has its own ID counter.
+5. **Personal bounties isolated** — Stored in `user_{id}/user.json` separate from group bounties.
+6. **Atomic writes** — Uses `tempfile` + `rename` for safe writes.
+7. **No reminders in v1** — Dropped for simplicity.

 ---

@@ -87,7 +108,7 @@ jigaido/
 | Command | Who | Description |
 |---|---|---|
 | `/bounty` | anyone | List all bounties in this group |
-| `/my` | anyone | List bounties tracked by you |
+| `/my` | anyone | List bounties you're tracking |
 | `/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 |
@@ -99,11 +120,10 @@ jigaido/
 | Command | Description |
 |---|---|
 | `/bounty` | List all your personal bounties |
-| `/my` | List bounties you're tracking |
+| `/my` | List your personal bounties (same as /bounty in DM) |
 | `/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

@@ -118,9 +138,9 @@ jigaido/

 ---

-## Informed By
+## Created 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.
+When a user triggers `/add`, the bot captures `message.from_user.username` and stores it in `created_by_username`. This is displayed on bounty listings so the group/DM knows who created the bounty.

 ---

@@ -142,10 +162,11 @@ Stored as Unix timestamp. User-facing display can be localized/converted to any
 ## Error Handling

 - Unknown command → help text with available commands
- `/update`/`/delete` by non-creator → "⛔ Group creator only."
+- `/update`/`/delete` by non-creator → "⛔ Only the creator can edit/delete this bounty."
 - `/track` already tracked → "Already tracking" (idempotent)
 - `/untrack` not tracked → "Not tracking" (idempotent)
- Bounty not found → "Bounty not found"
+- Bounty not found → "Bounty not found."
+- Tracking in DM → "Tracking is only available in groups."

 ---

@@ -155,4 +176,4 @@ Stored as Unix timestamp. User-facing display can be localized/converted to any
 - Complex queries across users
 - Reminder system with proper dedup
 - Scale > 1,000 users
- Need ACID guarantees on concurrent writes
+- Need ACID guarantees on concurrent writes