# atcasanova/churrasbot architecture

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

- Interactive diagram: https://gitdiagram.com/atcasanova/churrasbot
- Repository: https://github.com/atcasanova/churrasbot

## Overview

CHURRASBOT is a Bash-based Telegram bot for scheduling group barbecues and recording attendance through time-limited live-location check-ins. Its user workflow runs from Telegram updates through the bot’s message/location handling to event administration or check-in validation, then to group responses and attendance ranking. The README also documents venue management, calendar invitations, email notifications, reminders, and admin fraud cancellation. The source excerpts were unavailable, so edges reflect documented behavior and filenames; internal call wiring beyond that is not asserted.

Main entry points: [`src/handleMessage.sh`](https://github.com/atcasanova/churrasbot/blob/main/src/handleMessage.sh) (Message handler), [`src/main.sh`](https://github.com/atcasanova/churrasbot/blob/main/src/main.sh) (Main loop), [`src/newchurras.sh`](https://github.com/atcasanova/churrasbot/blob/main/src/newchurras.sh) (Event scheduling), [`src/achaChurras.sh`](https://github.com/atcasanova/churrasbot/blob/main/src/achaChurras.sh) (Check-in validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_bot["Bot launcher<br/>[bot.sh]"]
  node_main["Main loop<br/>[main.sh]"]
  node_messages["Message handler<br/>[handleMessage.sh]"]
  node_locations["Location handler<br/>[handleLocation.sh]"]
  node_live_location["Live-location handler"]
end

subgraph group_events["Event management"]
  node_venue["Venue setup<br/>[newplace.sh]"]
  node_create_event["Event scheduling<br/>[newchurras.sh]"]
  node_overlap["Schedule conflict check<br/>[checkOverlap.sh]"]
  node_delete_event["Event deletion<br/>[delchurras.sh]"]
  node_event_query["Next event query<br/>[qualchurras.sh]"]
  node_calendar["Calendar invitation<br/>[geraIcs.sh]"]
end

subgraph group_attendance["Attendance"]
  node_checkin["Check-in validation<br/>[achaChurras.sh]"]
  node_distance["Distance check<br/>[distance.sh]"]
  node_ranking["Attendance ranking<br/>[ranking.sh]"]
  node_fraud["Fraud cancellation<br/>[fake.sh]"]
end

subgraph group_communications["Communications"]
  node_reminder["Check-in reminder<br/>[lembrete.sh]"]
  node_email_registration["Email registration<br/>[cadastraEmail.sh]"]
  node_email_notifications["Email notifications<br/>[notificaUsers.sh]"]
end

node_users(("Telegram users"))
node_telegram["Telegram API"]
node_smtp["SMTP mail service"]

node_users -->|"send commands"| node_telegram
node_users -->|"send live location"| node_telegram
node_telegram -->|"deliver updates"| node_bot
node_bot -->|"start"| node_main
node_main -->|"poll updates"| node_telegram
node_main -->|"handle messages"| node_messages
node_main -->|"handle locations"| node_locations
node_main -->|"handle live location"| node_live_location
node_messages -->|"set venue"| node_venue
node_messages -->|"schedule event"| node_create_event
node_messages -->|"delete event"| node_delete_event
node_messages -->|"query event"| node_event_query
node_messages -->|"register email"| node_email_registration
node_messages -->|"request ranking"| node_ranking
node_messages -->|"cancel check-in"| node_fraud
node_create_event -->|"check conflicts"| node_overlap
node_create_event -->|"generate invitation"| node_calendar
node_create_event -->|"notify subscribers"| node_email_notifications
node_live_location -->|"validate attendance"| node_checkin
node_checkin -->|"check distance"| node_distance
node_checkin -->|"remove location message"| node_telegram
node_fraud -->|"adjust score"| node_ranking
node_reminder -->|"send reminder"| node_telegram
node_email_notifications -.->|"send email"| node_smtp
node_messages -->|"send responses"| node_telegram
node_create_event -->|"announce and pin"| node_telegram

click node_bot "https://github.com/atcasanova/churrasbot/blob/main/bot.sh"
click node_main "https://github.com/atcasanova/churrasbot/blob/main/src/main.sh"
click node_messages "https://github.com/atcasanova/churrasbot/blob/main/src/handleMessage.sh"
click node_locations "https://github.com/atcasanova/churrasbot/blob/main/src/handleLocation.sh"
click node_live_location "https://github.com/atcasanova/churrasbot/blob/main/src/handleLiveLocation.sh"
click node_venue "https://github.com/atcasanova/churrasbot/blob/main/src/newplace.sh"
click node_create_event "https://github.com/atcasanova/churrasbot/blob/main/src/newchurras.sh"
click node_overlap "https://github.com/atcasanova/churrasbot/blob/main/src/checkOverlap.sh"
click node_delete_event "https://github.com/atcasanova/churrasbot/blob/main/src/delchurras.sh"
click node_event_query "https://github.com/atcasanova/churrasbot/blob/main/src/qualchurras.sh"
click node_calendar "https://github.com/atcasanova/churrasbot/blob/main/src/geraIcs.sh"
click node_checkin "https://github.com/atcasanova/churrasbot/blob/main/src/achaChurras.sh"
click node_distance "https://github.com/atcasanova/churrasbot/blob/main/src/distance.sh"
click node_ranking "https://github.com/atcasanova/churrasbot/blob/main/src/ranking.sh"
click node_fraud "https://github.com/atcasanova/churrasbot/blob/main/src/fake.sh"
click node_reminder "https://github.com/atcasanova/churrasbot/blob/main/src/lembrete.sh"
click node_email_registration "https://github.com/atcasanova/churrasbot/blob/main/src/cadastraEmail.sh"
click node_email_notifications "https://github.com/atcasanova/churrasbot/blob/main/src/notificaUsers.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_bot,node_main,node_messages,node_locations,node_live_location,node_users toneBlue
class node_venue,node_create_event,node_overlap,node_delete_event,node_event_query,node_calendar toneAmber
class node_checkin,node_distance,node_ranking,node_fraud,node_telegram toneMint
class node_reminder,node_email_registration,node_email_notifications toneRose
class node_smtp toneIndigo
```

## Components

### Bot runtime

- [Bot launcher](https://github.com/atcasanova/churrasbot/blob/main/bot.sh): `bot.sh`
- [Main loop](https://github.com/atcasanova/churrasbot/blob/main/src/main.sh): `src/main.sh`
- [Message handler](https://github.com/atcasanova/churrasbot/blob/main/src/handleMessage.sh): `src/handleMessage.sh`
- [Location handler](https://github.com/atcasanova/churrasbot/blob/main/src/handleLocation.sh): `src/handleLocation.sh`
- [Live-location handler](https://github.com/atcasanova/churrasbot/blob/main/src/handleLiveLocation.sh): `src/handleLiveLocation.sh`

### Event management

- [Venue setup](https://github.com/atcasanova/churrasbot/blob/main/src/newplace.sh): `src/newplace.sh`
- [Event scheduling](https://github.com/atcasanova/churrasbot/blob/main/src/newchurras.sh): `src/newchurras.sh`
- [Schedule conflict check](https://github.com/atcasanova/churrasbot/blob/main/src/checkOverlap.sh): `src/checkOverlap.sh`
- [Event deletion](https://github.com/atcasanova/churrasbot/blob/main/src/delchurras.sh): `src/delchurras.sh`
- [Next event query](https://github.com/atcasanova/churrasbot/blob/main/src/qualchurras.sh): `src/qualchurras.sh`
- [Calendar invitation](https://github.com/atcasanova/churrasbot/blob/main/src/geraIcs.sh): `src/geraIcs.sh`

### Attendance

- [Check-in validation](https://github.com/atcasanova/churrasbot/blob/main/src/achaChurras.sh): `src/achaChurras.sh`
- [Distance check](https://github.com/atcasanova/churrasbot/blob/main/src/distance.sh): `src/distance.sh`
- [Attendance ranking](https://github.com/atcasanova/churrasbot/blob/main/src/ranking.sh): `src/ranking.sh`
- [Fraud cancellation](https://github.com/atcasanova/churrasbot/blob/main/src/fake.sh): `src/fake.sh`

### Communications

- [Check-in reminder](https://github.com/atcasanova/churrasbot/blob/main/src/lembrete.sh): `src/lembrete.sh`
- [Email registration](https://github.com/atcasanova/churrasbot/blob/main/src/cadastraEmail.sh): `src/cadastraEmail.sh`
- [Email notifications](https://github.com/atcasanova/churrasbot/blob/main/src/notificaUsers.sh): `src/notificaUsers.sh`

### Other components

- **Telegram users**
- **Telegram API**
- **SMTP mail service**

## Connections

- Telegram users → Telegram API: send commands
- Telegram users → Telegram API: send live location
- Telegram API → Bot launcher: deliver updates
- Bot launcher → Main loop: start
- Main loop → Telegram API: poll updates
- Main loop → Message handler: handle messages
- Main loop → Location handler: handle locations
- Main loop → Live-location handler: handle live location
- Message handler → Venue setup: set venue
- Message handler → Event scheduling: schedule event
- Message handler → Event deletion: delete event
- Message handler → Next event query: query event
- Message handler → Email registration: register email
- Message handler → Attendance ranking: request ranking
- Message handler → Fraud cancellation: cancel check-in
- Event scheduling → Schedule conflict check: check conflicts
- Event scheduling → Calendar invitation: generate invitation
- Event scheduling → Email notifications: notify subscribers
- Live-location handler → Check-in validation: validate attendance
- Check-in validation → Distance check: check distance
- Check-in validation → Telegram API: remove location message
- Fraud cancellation → Attendance ranking: adjust score
- Check-in reminder → Telegram API: send reminder
- Email notifications → SMTP mail service: send email
- Message handler → Telegram API: send responses
- Event scheduling → Telegram API: announce and pin
