Switchyard

Overview

Switchyard is a sample case study for a small routing service that moves information between the tools a team already uses. A note sent to a Telegram bot or an email with a certain label becomes a task on the board or a row in a spreadsheet, without anyone copying and pasting.

The problem

Small teams rarely need a large automation platform. They need three or four reliable paths between tools, and they need to know when one of those paths breaks. Hosted automation services work, until a rule fails silently and the team finds out a week later.

Goals

• Define each route as a short, readable rule.
• Process every incoming message exactly once.
• Log every run, with enough detail to replay a failed one.
• Run on the same small server as everything else.

Technical approach

Incoming messages arrive through a Telegram webhook or by polling a mailbox. Each message is stored with a unique source identifier before anything else happens, so a redelivered message is recognised and skipped.

The router matches messages against an ordered list of rules. A rule has a condition, such as a hashtag, a sender or an email label, and an action, such as creating a task or appending a row. Each action uses an idempotency key derived from the source message, so a retried action does not create a duplicate.

Architecture

Figure 1 shows the flow. Messages from Telegram and email enter the router, which records every run in the log and dispatches the result to the task board or the spreadsheet.

Technology stack

• Python for the router and its actions.
• Telegram Bot API for chat input.
• SQLite for the message store and the run log.
• Webhooks where the target tools support them.

Challenges and solutions

Duplicate deliveries

Every source message has a stable identifier, stored with a unique constraint. The database refuses the second copy, so the router never sees it.

Failures nobody notices

Every run writes a log row with its status. A daily summary lists failures, and a single command replays a failed run once the cause is fixed.

Rules that grow unreadable

Rules are kept short on purpose. When a rule needs real logic, it becomes a small named function with a test, rather than a longer configuration entry.

Results

Sample entry. Record measured outcomes here, such as how many manual copy steps the routes replaced and how often a run failed, once you have real numbers.

Lessons learned

• Idempotency is the whole game in automation. Design it in from the first route.
• A run log is cheap to build and expensive to lack.
• Keep the number of routes small. Each one is a promise to maintain.