Victor Hugo Vargas ab510d8b31 docs: document auto-compaction behavior in architecture guide

Adds the §4.5 Auto-compaction section to architecture.md and
architecture.es.md describing the trigger, fallback, persistence and
the new SSE 'compaction' event so consumers know how to react.

Includes the three placeholder projects used while exercising the
feature end to end (bot-onboarding, dashboard-metricas, tienda-ropa)
so /api/reindex picks them up without further setup.

2026-07-18 00:08:37 -07:00

1.4 KiB

Raw Blame History

title

date

status

Telegram Onboarding Bot

Conversational bot that walks new users through the initial setup of a B2B product.

Description

A Telegram assistant that reduces the time-to-first-value of a B2B product. Replaces an 8-step web form with a guided conversation. Each user has a long-running state machine that persists across days.

Tech stack

Runtime: Node.js
Database: PostgreSQL (state persistence per user)
Bot API: Telegram Bot API with inline keyboards
State machine: Hand-rolled, no FSM library

Main features

Conversational onboarding replacing the legacy 8-step form
Long-running per-user state machine with PostgreSQL-backed persistence
Telegram inline keyboards keep interaction inside the chat app
Watchdog that re-sends the last message if the user has not responded in 24h

Learnings

Handling Telegram timeouts without losing user state was the main challenge. The watchdog pattern with an explicit "give up" option turned out to be more reliable than trying to be too clever about timeout semantics. The state machine approach beat a more declarative framework for this use case because every state had bespoke transitions.

1.4 KiB Raw Blame History