# sinavarasina/sas-bot architecture

> Architecture diagram of the GitHub repository sinavarasina/sas-bot, 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/sinavarasina/sas-bot
- Repository: https://github.com/sinavarasina/sas-bot

## Overview

SAS-BOT is a WhatsApp public-service bot for village administration. Residents message the bot, pass NIK-based identification, choose a service, complete its stateful workflow, and receive a response or tracking ID. The main service branches cover resident registration/editing, letter requests and PDF generation, and photo-backed complaints; service reviews and status tracking are additional capabilities. PostgreSQL holds operational data, while Google Sheets supports synchronization and reporting. The excerpts show runtime routing and several service integrations; some documented capabilities have unsampled implementation details, so those links are omitted or marked unverified.

Main entry points: [`internal/bot/router/router.go`](https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/router/router.go) (Conversation router), [`internal/bot/menu/surat/service.go`](https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/surat/service.go) (Letter processing), [`internal/bot/menu/pengaduan/service.go`](https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/pengaduan/service.go) (Complaint processing), [`internal/db`](https://github.com/sinavarasina/sas-bot/tree/main/internal/db) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_app["Bot startup<br/>[main.go]"]
  node_transport["WhatsApp client<br/>[client.go]"]
  node_events["Message events<br/>[event-handler.go]"]
  node_router["Conversation router<br/>[router.go]"]
  node_gemini["AI responses<br/>[service.go]"]
end

subgraph group_identity["Resident data"]
  node_datadiri["Registration and editing<br/>[handler.go]"]
  node_identity_service["Identity validation and save<br/>[service.go]"]
end

subgraph group_letters["Letter service"]
  node_surat["Letter request flow<br/>[handler.go]"]
  node_letter_service["Letter processing<br/>[service.go]"]
  node_letter_state["Letter workflow state<br/>[state.go]"]
  node_pdf["PDF generation<br/>[generator.go]"]
end

subgraph group_complaints["Complaints"]
  node_pengaduan["Complaint flow<br/>[handler.go]"]
  node_complaint_service["Complaint processing<br/>[service.go]"]
  node_reviews["Service reviews"]
end

subgraph group_integrations["Persistence and integrations"]
  node_postgres[("PostgreSQL")]
  node_sheets["Google Sheets<br/>[sheets.go]"]
  node_imgbb["ImgBB<br/>[imgbb.go]"]
  node_r2["R2 storage<br/>[r2.go]"]
end

node_resident(("Resident"))
node_whatsapp_platform(("WhatsApp"))

node_resident -->|"sends messages"| node_whatsapp_platform
node_whatsapp_platform -->|"delivers events"| node_transport
node_app -->|"starts client"| node_transport
node_app -->|"configures"| node_router
node_transport -->|"registers handler"| node_events
node_events -->|"routes messages"| node_router
node_router -->|"dispatches"| node_datadiri
node_router -->|"dispatches"| node_surat
node_router -->|"dispatches"| node_pengaduan
node_router -->|"reads and updates sessions"| node_postgres
node_app -->|"configures"| node_gemini
node_datadiri -->|"delegates validation"| node_identity_service
node_identity_service -->|"checks and saves residents"| node_postgres
node_identity_service -->|"synchronizes resident data"| node_sheets
node_surat -->|"requests generation"| node_letter_service
node_surat -->|"reads resident data"| node_postgres
node_letter_service -->|"loads session data"| node_postgres
node_letter_service -->|"starts generation"| node_pdf
node_letter_service -.->|"uses workflow state"| node_letter_state
node_pdf -->|"logs letter status"| node_sheets
node_pdf -->|"uploads generated files"| node_r2
node_pengaduan -->|"delegates image handling"| node_complaint_service
node_complaint_service -->|"uploads evidence"| node_imgbb
node_complaint_service -->|"saves complaint"| node_postgres
node_complaint_service -->|"records complaint"| node_sheets
node_datadiri -.->|"offers rating"| node_reviews
node_letter_service -->|"offers rating"| node_reviews
node_complaint_service -->|"offers rating"| node_reviews
node_reviews -.->|"records ratings"| node_sheets

click node_app "https://github.com/sinavarasina/sas-bot/blob/main/cmd/sas-bot/main.go"
click node_transport "https://github.com/sinavarasina/sas-bot/blob/main/internal/whatsapp/client.go"
click node_events "https://github.com/sinavarasina/sas-bot/blob/main/internal/whatsapp/event-handler.go"
click node_router "https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/router/router.go"
click node_gemini "https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/gemini/service.go"
click node_datadiri "https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/datadiri/handler.go"
click node_identity_service "https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/datadiri/service.go"
click node_surat "https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/surat/handler.go"
click node_letter_service "https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/surat/service.go"
click node_letter_state "https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/surat/state.go"
click node_pdf "https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/surat/generator.go"
click node_pengaduan "https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/pengaduan/handler.go"
click node_complaint_service "https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/pengaduan/service.go"
click node_reviews "https://github.com/sinavarasina/sas-bot/tree/main/internal/bot/menu"
click node_postgres "https://github.com/sinavarasina/sas-bot/tree/main/internal/db"
click node_sheets "https://github.com/sinavarasina/sas-bot/blob/main/internal/sheets/sheets.go"
click node_imgbb "https://github.com/sinavarasina/sas-bot/blob/main/internal/uploader/imgbb.go"
click node_r2 "https://github.com/sinavarasina/sas-bot/blob/main/internal/uploader/r2.go"

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_app,node_transport,node_events,node_router,node_gemini toneBlue
class node_datadiri,node_identity_service toneAmber
class node_surat,node_letter_service,node_letter_state,node_pdf toneMint
class node_pengaduan,node_complaint_service,node_reviews toneRose
class node_postgres,node_sheets,node_imgbb,node_r2,node_resident,node_whatsapp_platform toneIndigo
```

## Components

### Bot runtime

- [Bot startup](https://github.com/sinavarasina/sas-bot/blob/main/cmd/sas-bot/main.go): `cmd/sas-bot/main.go`
- [WhatsApp client](https://github.com/sinavarasina/sas-bot/blob/main/internal/whatsapp/client.go): `internal/whatsapp/client.go`
- [Message events](https://github.com/sinavarasina/sas-bot/blob/main/internal/whatsapp/event-handler.go): `internal/whatsapp/event-handler.go`
- [Conversation router](https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/router/router.go): `internal/bot/router/router.go`
- [AI responses](https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/gemini/service.go): `internal/bot/gemini/service.go`

### Resident data

- [Registration and editing](https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/datadiri/handler.go): `internal/bot/menu/datadiri/handler.go`
- [Identity validation and save](https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/datadiri/service.go): `internal/bot/menu/datadiri/service.go`

### Letter service

- [Letter request flow](https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/surat/handler.go): `internal/bot/menu/surat/handler.go`
- [Letter processing](https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/surat/service.go): `internal/bot/menu/surat/service.go`
- [Letter workflow state](https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/surat/state.go): `internal/bot/menu/surat/state.go`
- [PDF generation](https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/surat/generator.go): `internal/bot/menu/surat/generator.go`

### Complaints

- [Complaint flow](https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/pengaduan/handler.go): `internal/bot/menu/pengaduan/handler.go`
- [Complaint processing](https://github.com/sinavarasina/sas-bot/blob/main/internal/bot/menu/pengaduan/service.go): `internal/bot/menu/pengaduan/service.go`
- [Service reviews](https://github.com/sinavarasina/sas-bot/tree/main/internal/bot/menu): `internal/bot/menu`

### Persistence and integrations

- [PostgreSQL](https://github.com/sinavarasina/sas-bot/tree/main/internal/db): `internal/db`
- [Google Sheets](https://github.com/sinavarasina/sas-bot/blob/main/internal/sheets/sheets.go): `internal/sheets/sheets.go`
- [ImgBB](https://github.com/sinavarasina/sas-bot/blob/main/internal/uploader/imgbb.go): `internal/uploader/imgbb.go`
- [R2 storage](https://github.com/sinavarasina/sas-bot/blob/main/internal/uploader/r2.go): `internal/uploader/r2.go`

### Other components

- **Resident**
- **WhatsApp**

## Connections

- Resident → WhatsApp: sends messages (evidence: `README.md`)
- WhatsApp → WhatsApp client: delivers events (evidence: `internal/whatsapp/client.go`)
- Bot startup → WhatsApp client: starts client (evidence: `cmd/sas-bot/main.go`)
- Bot startup → Conversation router: configures (evidence: `cmd/sas-bot/main.go`)
- WhatsApp client → Message events: registers handler (evidence: `internal/whatsapp/client.go`)
- Message events → Conversation router: routes messages (evidence: `internal/whatsapp/event-handler.go`)
- Conversation router → Registration and editing: dispatches (evidence: `internal/bot/router/router.go`)
- Conversation router → Letter request flow: dispatches (evidence: `internal/bot/router/router.go`)
- Conversation router → Complaint flow: dispatches (evidence: `internal/bot/router/router.go`)
- Conversation router → PostgreSQL: reads and updates sessions (evidence: `internal/bot/router/router.go`)
- Bot startup → AI responses: configures (evidence: `cmd/sas-bot/main.go`)
- Registration and editing → Identity validation and save: delegates validation (evidence: `internal/bot/menu/datadiri/handler.go`)
- Identity validation and save → PostgreSQL: checks and saves residents (evidence: `internal/bot/menu/datadiri/service.go`)
- Identity validation and save → Google Sheets: synchronizes resident data (evidence: `internal/bot/menu/datadiri/service.go`)
- Letter request flow → Letter processing: requests generation (evidence: `internal/bot/menu/surat/handler.go`)
- Letter request flow → PostgreSQL: reads resident data (evidence: `internal/bot/menu/surat/handler.go`)
- Letter processing → PostgreSQL: loads session data (evidence: `internal/bot/menu/surat/service.go`)
- Letter processing → PDF generation: starts generation (evidence: `internal/bot/menu/surat/service.go`)
- Letter processing → Letter workflow state: uses workflow state
- PDF generation → Google Sheets: logs letter status (evidence: `internal/bot/menu/surat/generator.go`)
- PDF generation → R2 storage: uploads generated files (evidence: `internal/bot/menu/surat/generator.go`)
- Complaint flow → Complaint processing: delegates image handling (evidence: `internal/bot/menu/pengaduan/service.go`)
- Complaint processing → ImgBB: uploads evidence (evidence: `internal/bot/menu/pengaduan/service.go`)
- Complaint processing → PostgreSQL: saves complaint (evidence: `internal/bot/menu/pengaduan/service.go`)
- Complaint processing → Google Sheets: records complaint (evidence: `internal/bot/menu/pengaduan/service.go`)
- Registration and editing → Service reviews: offers rating (evidence: `README.md`)
- Letter processing → Service reviews: offers rating (evidence: `internal/bot/menu/surat/service.go`)
- Complaint processing → Service reviews: offers rating (evidence: `internal/bot/menu/pengaduan/service.go`)
- Service reviews → Google Sheets: records ratings (evidence: `README.md`)
