# elviisaeva/petty-thief architecture

> Architecture diagram of the GitHub repository elviisaeva/petty-thief, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elviisaeva/petty-thief
- Repository: https://github.com/elviisaeva/petty-thief

## Overview

Petty Thief captures links from Telegram (or directly from a user), makes them available to Claude Code, and turns them into analyses or collection cards stored in the user’s local loot folder. The Cloudflare Worker handles bot setup, ownership, link intake, and the API; the plugin’s Markdown skill guides analysis and local organization. Worker relationships are supported by excerpts and the SOURCE INDEX. Plugin internals were not sampled, so those connections reflect README-documented behavior rather than inspected calls.

Main entry points: [`worker/src/telegram.ts`](https://github.com/elviisaeva/petty-thief/blob/main/worker/src/telegram.ts) (Bot commands and intake), [`worker/src/setup.ts`](https://github.com/elviisaeva/petty-thief/blob/main/worker/src/setup.ts) (Bot setup), [`worker/src/db.ts`](https://github.com/elviisaeva/petty-thief/blob/main/worker/src/db.ts) (Stash data access), [`plugin/skills/petty-thief/SKILL.md`](https://github.com/elviisaeva/petty-thief/blob/main/plugin/skills/petty-thief/SKILL.md) (Petty Thief skill)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Setup and intake"]
  node_setup["Bot setup<br/>[setup.ts]"]
end

subgraph group_worker["Cloudflare worker"]
  node_router["Request router<br/>[index.ts]"]
  node_webhook["Webhook handler<br/>[webhook.ts]"]
  node_telegram_logic["Bot commands and intake<br/>[telegram.ts]"]
  node_url_parse["Link and tag parsing<br/>[urls.ts]"]
  node_api["Stash API<br/>[api.ts]"]
  node_db["Stash data access<br/>[db.ts]"]
  node_schema["Database schema<br/>[schema.ts]"]
  node_auth["Tokens and secrets<br/>[auth.ts]"]
  node_tg_client["Telegram client<br/>[telegram-client.ts]"]
  node_branding["Bot branding<br/>[branding.ts]"]
end

subgraph group_skill["Claude skill"]
  node_skill["Petty Thief skill<br/>[SKILL.md]"]
  node_gather["Stash gathering<br/>[gather.sh]"]
end

subgraph group_analysis["Analysis and collections"]
  node_lenses["Analysis lenses"]
  node_collections["Collection handling<br/>[collections.md]"]
end

subgraph group_local["Local loot"]
  node_loot["Loot files"]
  node_stash_script["Stash commands<br/>[stash.sh]"]
end

node_phone(("Phone user"))
node_telegram(("Telegram"))
node_claude(("Claude Code"))
node_d1[("Cloudflare D1")]

node_phone -->|"forwards links"| node_telegram
node_telegram -->|"sends updates"| node_router
node_router -->|"routes webhook"| node_webhook
node_router -->|"routes setup"| node_setup
node_router -->|"routes API"| node_api
node_setup -->|"registers webhook"| node_tg_client
node_tg_client -->|"calls Telegram API"| node_telegram
node_webhook -->|"dispatches update"| node_telegram_logic
node_telegram_logic -->|"extracts links"| node_url_parse
node_telegram_logic -->|"stores and queries"| node_db
node_api -->|"reads and updates"| node_db
node_webhook -->|"checks secret"| node_db
node_setup -->|"stores setup state"| node_db
node_setup -->|"creates secrets"| node_auth
node_telegram_logic -->|"issues tokens"| node_auth
node_setup -->|"applies branding"| node_branding
node_telegram_logic -->|"applies branding"| node_branding
node_setup -->|"ensures schema"| node_schema
node_webhook -->|"ensures schema"| node_schema
node_api -->|"ensures schema"| node_schema
node_db -->|"generates IDs"| node_auth
node_d1 -.->|"persists stash"| node_db
node_telegram_logic -.->|"replies to owner"| node_telegram
node_telegram_logic -.->|"exposes stash"| node_api
node_claude -->|"runs skill"| node_skill
node_skill -.->|"gathers waiting links"| node_gather
node_gather -.->|"fetches stash"| node_api
node_skill -->|"analyzes with"| node_lenses
node_skill -->|"files collections"| node_collections
node_skill -.->|"manages stash"| node_stash_script
node_lenses -->|"writes analysis"| node_loot
node_collections -->|"writes cards"| node_loot
node_stash_script -.->|"updates files"| node_loot

click node_setup "https://github.com/elviisaeva/petty-thief/blob/main/worker/src/setup.ts"
click node_router "https://github.com/elviisaeva/petty-thief/blob/main/worker/src/index.ts"
click node_webhook "https://github.com/elviisaeva/petty-thief/blob/main/worker/src/webhook.ts"
click node_telegram_logic "https://github.com/elviisaeva/petty-thief/blob/main/worker/src/telegram.ts"
click node_url_parse "https://github.com/elviisaeva/petty-thief/blob/main/worker/src/urls.ts"
click node_api "https://github.com/elviisaeva/petty-thief/blob/main/worker/src/api.ts"
click node_db "https://github.com/elviisaeva/petty-thief/blob/main/worker/src/db.ts"
click node_schema "https://github.com/elviisaeva/petty-thief/blob/main/worker/src/schema.ts"
click node_auth "https://github.com/elviisaeva/petty-thief/blob/main/worker/src/auth.ts"
click node_tg_client "https://github.com/elviisaeva/petty-thief/blob/main/worker/src/telegram-client.ts"
click node_branding "https://github.com/elviisaeva/petty-thief/blob/main/worker/src/branding.ts"
click node_skill "https://github.com/elviisaeva/petty-thief/blob/main/plugin/skills/petty-thief/SKILL.md"
click node_gather "https://github.com/elviisaeva/petty-thief/blob/main/plugin/skills/petty-thief/scripts/gather.sh"
click node_lenses "https://github.com/elviisaeva/petty-thief/tree/main/plugin/skills/petty-thief/lenses"
click node_collections "https://github.com/elviisaeva/petty-thief/blob/main/plugin/skills/petty-thief/reference/collections.md"
click node_stash_script "https://github.com/elviisaeva/petty-thief/blob/main/plugin/skills/petty-thief/scripts/stash.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_setup,node_phone toneBlue
class node_router,node_webhook,node_telegram_logic,node_url_parse,node_api,node_db,node_schema,node_auth,node_tg_client,node_branding,node_d1 toneAmber
class node_skill,node_gather toneMint
class node_lenses,node_collections toneRose
class node_loot,node_stash_script,node_telegram,node_claude toneIndigo
```

## Components

### Setup and intake

- [Bot setup](https://github.com/elviisaeva/petty-thief/blob/main/worker/src/setup.ts): `worker/src/setup.ts`

### Cloudflare worker

- [Request router](https://github.com/elviisaeva/petty-thief/blob/main/worker/src/index.ts): `worker/src/index.ts`
- [Webhook handler](https://github.com/elviisaeva/petty-thief/blob/main/worker/src/webhook.ts): `worker/src/webhook.ts`
- [Bot commands and intake](https://github.com/elviisaeva/petty-thief/blob/main/worker/src/telegram.ts): `worker/src/telegram.ts`
- [Link and tag parsing](https://github.com/elviisaeva/petty-thief/blob/main/worker/src/urls.ts): `worker/src/urls.ts`
- [Stash API](https://github.com/elviisaeva/petty-thief/blob/main/worker/src/api.ts): `worker/src/api.ts`
- [Stash data access](https://github.com/elviisaeva/petty-thief/blob/main/worker/src/db.ts): `worker/src/db.ts`
- [Database schema](https://github.com/elviisaeva/petty-thief/blob/main/worker/src/schema.ts): `worker/src/schema.ts`
- [Tokens and secrets](https://github.com/elviisaeva/petty-thief/blob/main/worker/src/auth.ts): `worker/src/auth.ts`
- [Telegram client](https://github.com/elviisaeva/petty-thief/blob/main/worker/src/telegram-client.ts): `worker/src/telegram-client.ts`
- [Bot branding](https://github.com/elviisaeva/petty-thief/blob/main/worker/src/branding.ts): `worker/src/branding.ts`

### Claude skill

- [Petty Thief skill](https://github.com/elviisaeva/petty-thief/blob/main/plugin/skills/petty-thief/SKILL.md): `plugin/skills/petty-thief/SKILL.md`
- [Stash gathering](https://github.com/elviisaeva/petty-thief/blob/main/plugin/skills/petty-thief/scripts/gather.sh): `plugin/skills/petty-thief/scripts/gather.sh`

### Analysis and collections

- [Analysis lenses](https://github.com/elviisaeva/petty-thief/tree/main/plugin/skills/petty-thief/lenses): `plugin/skills/petty-thief/lenses`
- [Collection handling](https://github.com/elviisaeva/petty-thief/blob/main/plugin/skills/petty-thief/reference/collections.md): `plugin/skills/petty-thief/reference/collections.md`

### Local loot

- **Loot files**
- [Stash commands](https://github.com/elviisaeva/petty-thief/blob/main/plugin/skills/petty-thief/scripts/stash.sh): `plugin/skills/petty-thief/scripts/stash.sh`

### Other components

- **Phone user**
- **Telegram**
- **Claude Code**
- **Cloudflare D1**

## Connections

- Phone user → Telegram: forwards links (evidence: `README.md`)
- Telegram → Request router: sends updates (evidence: `README.md`)
- Request router → Webhook handler: routes webhook (evidence: `worker/src/index.ts`)
- Request router → Bot setup: routes setup (evidence: `worker/src/index.ts`)
- Request router → Stash API: routes API (evidence: `worker/src/index.ts`)
- Bot setup → Telegram client: registers webhook (evidence: `worker/src/setup.ts`)
- Telegram client → Telegram: calls Telegram API (evidence: `worker/src/telegram-client.ts`)
- Webhook handler → Bot commands and intake: dispatches update (evidence: `worker/src/webhook.ts`)
- Bot commands and intake → Link and tag parsing: extracts links (evidence: `worker/src/telegram.ts`)
- Bot commands and intake → Stash data access: stores and queries (evidence: `worker/src/telegram.ts`)
- Stash API → Stash data access: reads and updates (evidence: `worker/src/api.ts`)
- Webhook handler → Stash data access: checks secret (evidence: `worker/src/webhook.ts`)
- Bot setup → Stash data access: stores setup state (evidence: `worker/src/setup.ts`)
- Bot setup → Tokens and secrets: creates secrets (evidence: `worker/src/setup.ts`)
- Bot commands and intake → Tokens and secrets: issues tokens (evidence: `worker/src/telegram.ts`)
- Bot setup → Bot branding: applies branding (evidence: `worker/src/setup.ts`)
- Bot commands and intake → Bot branding: applies branding (evidence: `worker/src/telegram.ts`)
- Bot setup → Database schema: ensures schema (evidence: `worker/src/setup.ts`)
- Webhook handler → Database schema: ensures schema (evidence: `worker/src/webhook.ts`)
- Stash API → Database schema: ensures schema (evidence: `worker/src/api.ts`)
- Stash data access → Tokens and secrets: generates IDs (evidence: `worker/src/db.ts`)
- Cloudflare D1 → Stash data access: persists stash
- Bot commands and intake → Telegram: replies to owner
- Bot commands and intake → Stash API: exposes stash
- Claude Code → Petty Thief skill: runs skill (evidence: `README.md`)
- Petty Thief skill → Stash gathering: gathers waiting links
- Stash gathering → Stash API: fetches stash
- Petty Thief skill → Analysis lenses: analyzes with (evidence: `README.md`)
- Petty Thief skill → Collection handling: files collections (evidence: `README.md`)
- Petty Thief skill → Stash commands: manages stash
- Analysis lenses → Loot files: writes analysis (evidence: `README.md`)
- Collection handling → Loot files: writes cards (evidence: `README.md`)
- Stash commands → Loot files: updates files
