# lordgrim77/postfixer architecture

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

- Interactive diagram: https://gitdiagram.com/lordgrim77/postfixer
- Repository: https://github.com/lordgrim77/postfixer

## Overview

#### Purpose and deployment shape
PostFixer is a Telegram rich-message system deployed as three independent Cloudflare Workers: a bot backend, a formatting Web App, and a custom-emoji manager. The workers are manually deployed as self-contained JavaScript; frontends are embedded into worker artifacts rather than hosted separately.

Core deployable entry points:
- `worker.js`
- `webapp_worker.js`
- `emoji_manager_worker.src.js` (source; compiled target is expected as `emoji_manager_worker.js`, though that non-obfuscated root artifact is absent)
- `obfuscated/emoji_manager_worker.js`

#### Telegram bot backend
`worker.js` is the webhook-facing control plane. It receives Telegram updates, handles normal bot interactions and inline queries, applies rich formatting, and calls Gemini for AI-assisted formatting behavior. It also connects the bot experience to the formatting and emoji-management web apps through configured public URLs.

Relevant boundaries:
- Telegram Bot API through `BOT_TOKEN`
- Google Gemini through `GEMINI_API_KEY`
- Cloudflare bindings: `KV`, `EMOJI_MANAGER_KV`, and D1 `DB`
- Runtime configuration including `BOT_USERNAME`, `ADMINS`, and `EMOJI_MANAGER_URL`

#### Formatting Web App worker
The formatting Web App is an API-and-static-hosting worker. Its editable template is `webapp_worker.src.js`; `webapp_worker.js` is the generated deployable artifact. It serves the rich-text editor UI and coordinates API calls that require the bot token or the bot worker.

Paths:
- `webapp_worker.src.js`
- `webapp_worker.js`
- `frontend/index.html`
- `frontend/app.js`
- `frontend/react_editor.js`

The worker’s infrastructure boundary is Cloudflare `WEBAPP_KV`, with `BOT_WORKER_URL` used to reach the bot backend and `BOT_TOKEN` used for Telegram operations.

#### Emoji manager worker
The emoji manager is a separate Web App/API boundary for associating standard Unicode emojis with Telegram Premium custom emoji stickers. It retrieves sticker metadata from Telegram and supports personal mappings plus administrator-managed global fallback mappings. The UI uses hover-triggered Lottie animation behavior to limit client CPU use.

Paths:
- `emoji_manager_worker.src.js`
- `emoji_manager_frontend/index.html`
- `emoji_manager_frontend/app.js`
- `emoji_manager_frontend/style.css`

It uses `EMOJI_MANAGER_KV` for persisted mappings, `ADMINS` to authorize global edits, and `BOT_TOKEN` to query Telegram.

#### Frontend-to-worker asset pipeline
The source frontends are not independently deployed. `build_all_obfuscated.js` reads the formatting and emoji-manager frontend assets, encodes them into worker-served content, obfuscates JavaScript, and emits deployment artifacts. Any UI modification requires rebuilding before worker deployment.

Paths:
- `build_all_obfuscated.js`
- `frontend/`
- `emoji_manager_frontend/`
- `obfuscated/webapp_worker.js`
- `obfuscated/emoji_manager_worker.js`

`build_combined.js` and related patch scripts indicate an evolving generated-worker workflow, but the all-in-one build script is the documented primary pipeline.

#### Storage and cross-service flow
Primary request flow is: Telegram update → `worker.js` → Telegram/Gemini/KV/D1 as needed → Telegram response. For interactive editing, Telegram opens the formatting worker, which serves its embedded UI and communicates with the bot worker/Telgram APIs. Emoji-manager interactions remain isolated in their own worker and KV namespace binding, while the bot references its public URL to expose the feature.

D1 holds aggregate counters in `global_stats`; KV stores application state, web-app state, and emoji mappings. Cloudflare Workers provide the runtime, Telegram is the user-facing external platform, and Gemini is the AI dependency.

Main entry points: [`webapp_worker.js`](https://github.com/lordgrim77/postfixer/blob/main/webapp_worker.js) (Formatting Web App), [`build_all_obfuscated.js`](https://github.com/lordgrim77/postfixer/blob/main/build_all_obfuscated.js) (Artifact builder), [`worker.js`](https://github.com/lordgrim77/postfixer/blob/main/worker.js) (Update & formatting handler), [`obfuscated/emoji_manager_worker.js`](https://github.com/lordgrim77/postfixer/blob/main/obfuscated/emoji_manager_worker.js) (Emoji manager Web App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workers["Cloudflare Workers"]
  node_bot_worker["Bot backend<br/>webhook worker<br/>[worker.js]"]
  node_bot_handler["Update &amp; formatting handler<br/>bot control layer<br/>[worker.js]"]
  node_format_worker_src["Formatting worker source<br/>worker template"]
  node_format_worker["Formatting Web App<br/>API and static worker<br/>[webapp_worker.js]"]
  node_emoji_worker_src["Emoji worker source<br/>worker template"]
  node_emoji_worker["Emoji manager Web App<br/>API and static worker"]
end

subgraph group_frontend["Embedded frontends"]
  node_format_ui["Rich-text editor UI<br/>frontend assets"]
  node_format_html["Editor shell<br/>HTML asset<br/>[index.html]"]
  node_format_app["Editor client<br/>JavaScript asset<br/>[app.js]"]
  node_react_editor["React editor<br/>editor component<br/>[react_editor.js]"]
  node_emoji_ui["Emoji manager UI<br/>frontend assets"]
  node_emoji_html["Emoji UI shell<br/>HTML asset<br/>[index.html]"]
  node_emoji_app["Emoji UI client<br/>JavaScript asset<br/>[app.js]"]
  node_emoji_styles["Emoji UI styles<br/>CSS asset<br/>[style.css]"]
  node_builder{{"Artifact builder<br/>build pipeline"}}
end

subgraph group_platform["External services &amp; storage"]
  node_telegram{{"Telegram<br/>external platform"}}
  node_gemini{{"Google Gemini<br/>AI API"}}
  node_kv[("Cloudflare KV<br/>KV bindings")]
  node_d1[("Cloudflare D1<br/>database binding")]
end

node_telegram -->|"webhook updates"| node_bot_worker
node_bot_worker -->|"dispatches"| node_bot_handler
node_bot_handler -->|"Bot API responses"| node_telegram
node_bot_handler -->|"AI formatting"| node_gemini
node_bot_handler -->|"state and emoji mappings"| node_kv
node_bot_handler -->|"global_stats"| node_d1
node_bot_worker -->|"opens Web App URL"| node_format_worker
node_bot_worker -->|"exposes manager URL"| node_emoji_worker
node_telegram -->|"opens editor"| node_format_worker
node_format_worker -->|"BOT_WORKER_URL"| node_bot_worker
node_format_worker -->|"bot-token operations"| node_telegram
node_format_worker -->|"WEBAPP_KV"| node_kv
node_telegram -->|"opens manager"| node_emoji_worker
node_emoji_worker -->|"sticker metadata"| node_telegram
node_emoji_worker -->|"EMOJI_MANAGER_KV"| node_kv
node_format_html -.->|"part of"| node_format_ui
node_format_app -.->|"part of"| node_format_ui
node_react_editor -.->|"part of"| node_format_ui
node_emoji_html -.->|"part of"| node_emoji_ui
node_emoji_app -.->|"part of"| node_emoji_ui
node_emoji_styles -.->|"part of"| node_emoji_ui
node_format_ui -->|"bundled"| node_builder
node_emoji_ui -->|"bundled"| node_builder
node_format_worker_src -->|"build input"| node_builder
node_emoji_worker_src -->|"build input"| node_builder
node_builder -->|"generated artifact"| node_format_worker
node_builder -->|"obfuscated artifact"| node_emoji_worker

click node_bot_worker "https://github.com/lordgrim77/postfixer/blob/main/worker.js"
click node_bot_handler "https://github.com/lordgrim77/postfixer/blob/main/worker.js"
click node_format_worker_src "https://github.com/lordgrim77/postfixer/blob/main/webapp_worker.src.js"
click node_format_worker "https://github.com/lordgrim77/postfixer/blob/main/webapp_worker.js"
click node_emoji_worker_src "https://github.com/lordgrim77/postfixer/blob/main/emoji_manager_worker.src.js"
click node_emoji_worker "https://github.com/lordgrim77/postfixer/blob/main/obfuscated/emoji_manager_worker.js"
click node_format_html "https://github.com/lordgrim77/postfixer/blob/main/frontend/index.html"
click node_format_app "https://github.com/lordgrim77/postfixer/blob/main/frontend/app.js"
click node_react_editor "https://github.com/lordgrim77/postfixer/blob/main/frontend/react_editor.js"
click node_emoji_html "https://github.com/lordgrim77/postfixer/blob/main/emoji_manager_frontend/index.html"
click node_emoji_app "https://github.com/lordgrim77/postfixer/blob/main/emoji_manager_frontend/app.js"
click node_emoji_styles "https://github.com/lordgrim77/postfixer/blob/main/emoji_manager_frontend/style.css"
click node_builder "https://github.com/lordgrim77/postfixer/blob/main/build_all_obfuscated.js"

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_bot_worker,node_bot_handler,node_format_worker_src,node_format_worker,node_emoji_worker_src,node_emoji_worker toneBlue
class node_format_ui,node_format_html,node_format_app,node_react_editor,node_emoji_ui,node_emoji_html,node_emoji_app,node_emoji_styles,node_builder toneAmber
class node_telegram,node_gemini,node_kv,node_d1 toneMint
```

## Components

### Cloudflare Workers

Three independently deployed worker applications.

- [Bot backend](https://github.com/lordgrim77/postfixer/blob/main/worker.js): webhook worker · Receives updates, applies formatting, and handles inline queries. · `worker.js`
- [Update & formatting handler](https://github.com/lordgrim77/postfixer/blob/main/worker.js): bot control layer · Coordinates bot interactions, rich messages, and AI-assisted behavior. · `worker.js`
- [Formatting worker source](https://github.com/lordgrim77/postfixer/blob/main/webapp_worker.src.js): worker template · `webapp_worker.src.js`
- [Formatting Web App](https://github.com/lordgrim77/postfixer/blob/main/webapp_worker.js): API and static worker · Serves the embedded editor and coordinates bot-backed operations. · `webapp_worker.js`
- [Emoji worker source](https://github.com/lordgrim77/postfixer/blob/main/emoji_manager_worker.src.js): worker template · `emoji_manager_worker.src.js`
- [Emoji manager Web App](https://github.com/lordgrim77/postfixer/blob/main/obfuscated/emoji_manager_worker.js): API and static worker · Manages personal and admin global custom-emoji mappings. · `obfuscated/emoji_manager_worker.js`

### Embedded frontends

Source UI assets are bundled into worker artifacts.

- **Rich-text editor UI**: frontend assets
- [Editor shell](https://github.com/lordgrim77/postfixer/blob/main/frontend/index.html): HTML asset · `frontend/index.html`
- [Editor client](https://github.com/lordgrim77/postfixer/blob/main/frontend/app.js): JavaScript asset · `frontend/app.js`
- [React editor](https://github.com/lordgrim77/postfixer/blob/main/frontend/react_editor.js): editor component · `frontend/react_editor.js`
- **Emoji manager UI**: frontend assets · Includes hover-triggered Lottie animation behavior.
- [Emoji UI shell](https://github.com/lordgrim77/postfixer/blob/main/emoji_manager_frontend/index.html): HTML asset · `emoji_manager_frontend/index.html`
- [Emoji UI client](https://github.com/lordgrim77/postfixer/blob/main/emoji_manager_frontend/app.js): JavaScript asset · `emoji_manager_frontend/app.js`
- [Emoji UI styles](https://github.com/lordgrim77/postfixer/blob/main/emoji_manager_frontend/style.css): CSS asset · `emoji_manager_frontend/style.css`
- [Artifact builder](https://github.com/lordgrim77/postfixer/blob/main/build_all_obfuscated.js): build pipeline · Embeds assets, obfuscates JavaScript, and emits deployable workers. · `build_all_obfuscated.js`

### External services & storage

- **Telegram**: external platform · User-facing Bot API and Web App platform.
- **Google Gemini**: AI API
- **Cloudflare KV**: KV bindings · KV, WEBAPP_KV, and EMOJI_MANAGER_KV hold application and mapping state.
- **Cloudflare D1**: database binding · Stores aggregate counters in global_stats.

## Connections

- Telegram → Bot backend: webhook updates
- Bot backend → Update & formatting handler: dispatches
- Update & formatting handler → Telegram: Bot API responses
- Update & formatting handler → Google Gemini: AI formatting
- Update & formatting handler → Cloudflare KV: state and emoji mappings
- Update & formatting handler → Cloudflare D1: global_stats
- Bot backend → Formatting Web App: opens Web App URL
- Bot backend → Emoji manager Web App: exposes manager URL
- Telegram → Formatting Web App: opens editor
- Formatting Web App → Bot backend: BOT_WORKER_URL
- Formatting Web App → Telegram: bot-token operations
- Formatting Web App → Cloudflare KV: WEBAPP_KV
- Telegram → Emoji manager Web App: opens manager
- Emoji manager Web App → Telegram: sticker metadata
- Emoji manager Web App → Cloudflare KV: EMOJI_MANAGER_KV
- Editor shell → Rich-text editor UI: part of
- Editor client → Rich-text editor UI: part of
- React editor → Rich-text editor UI: part of
- Emoji UI shell → Emoji manager UI: part of
- Emoji UI client → Emoji manager UI: part of
- Emoji UI styles → Emoji manager UI: part of
- Rich-text editor UI → Artifact builder: bundled
- Emoji manager UI → Artifact builder: bundled
- Formatting worker source → Artifact builder: build input
- Emoji worker source → Artifact builder: build input
- Artifact builder → Formatting Web App: generated artifact
- Artifact builder → Emoji manager Web App: obfuscated artifact