# vilelacc/telecep architecture

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

- Interactive diagram: https://gitdiagram.com/vilelacc/telecep
- Repository: https://github.com/vilelacc/telecep

## Overview

TeleCEP is a Telegram chatbot for Brazilian postal-code lookups. Users start /cep to enter a CEP and receive its address, or /addr to choose a state, enter a city and street, and receive one or more matching CEPs. The bot also provides start, about, and bug-support replies. The address flow validates its inputs before searching; both lookup helpers query ViaCEP, with cached HTTP clients. The sampled source supports these calls and dispatches; broader runtime wiring is not inferred.

Main entry points: [`src/bot.js`](https://github.com/vilelacc/telecep/blob/main/src/bot.js) (Bot commands), [`src/wizards/addr.wizard.scene.js`](https://github.com/vilelacc/telecep/blob/main/src/wizards/addr.wizard.scene.js) (Address lookup flow), [`src/helpers/messages.default.js`](https://github.com/vilelacc/telecep/blob/main/src/helpers/messages.default.js) (About and support text), [`src/wizards/zip.code.wizard.scene.js`](https://github.com/vilelacc/telecep/blob/main/src/wizards/zip.code.wizard.scene.js) (CEP lookup flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Telegram interface"]
  node_bot["Bot commands<br/>[bot.js]"]
  node_messages["About and support text"]
end

subgraph group_flows["Lookup flows"]
  node_zip["CEP lookup flow"]
  node_address["Address lookup flow"]
  node_states["Federative units"]
end

subgraph group_lookup["Lookup services"]
  node_validation["Address validation<br/>[data.validation.js]"]
  node_zipsearch["Search by CEP"]
  node_addresssearch["Search by address"]
end

node_user(("Telegram user"))
node_viacep{{"ViaCEP API"}}
node_metadata["Project metadata<br/>[package.json]"]

node_user -->|"sends commands"| node_bot
node_bot -->|"replies"| node_user
node_bot -->|"enters /cep"| node_zip
node_bot -->|"enters /addr"| node_address
node_bot -->|"uses replies"| node_messages
node_messages -->|"reads version and author"| node_metadata
node_address -->|"offers states"| node_states
node_address -->|"validates input"| node_validation
node_address -->|"searches address"| node_addresssearch
node_zip -->|"searches CEP"| node_zipsearch
node_zipsearch -->|"requests CEP data"| node_viacep
node_addresssearch -->|"requests address data"| node_viacep

click node_bot "https://github.com/vilelacc/telecep/blob/main/src/bot.js"
click node_messages "https://github.com/vilelacc/telecep/blob/main/src/helpers/messages.default.js"
click node_zip "https://github.com/vilelacc/telecep/blob/main/src/wizards/zip.code.wizard.scene.js"
click node_address "https://github.com/vilelacc/telecep/blob/main/src/wizards/addr.wizard.scene.js"
click node_states "https://github.com/vilelacc/telecep/blob/main/src/helpers/federative.units.js"
click node_validation "https://github.com/vilelacc/telecep/blob/main/src/helpers/data.validation.js"
click node_zipsearch "https://github.com/vilelacc/telecep/blob/main/src/helpers/search.by.zip.code.js"
click node_addresssearch "https://github.com/vilelacc/telecep/blob/main/src/helpers/search.by.address.js"
click node_metadata "https://github.com/vilelacc/telecep/blob/main/package.json"

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_messages,node_user toneBlue
class node_zip,node_address,node_states toneAmber
class node_validation,node_zipsearch,node_addresssearch,node_viacep toneMint
class node_metadata toneTeal
```

## Components

### Telegram interface

- [Bot commands](https://github.com/vilelacc/telecep/blob/main/src/bot.js): `src/bot.js`
- [About and support text](https://github.com/vilelacc/telecep/blob/main/src/helpers/messages.default.js): `src/helpers/messages.default.js`

### Lookup flows

- [CEP lookup flow](https://github.com/vilelacc/telecep/blob/main/src/wizards/zip.code.wizard.scene.js): `src/wizards/zip.code.wizard.scene.js`
- [Address lookup flow](https://github.com/vilelacc/telecep/blob/main/src/wizards/addr.wizard.scene.js): `src/wizards/addr.wizard.scene.js`
- [Federative units](https://github.com/vilelacc/telecep/blob/main/src/helpers/federative.units.js): `src/helpers/federative.units.js`

### Lookup services

- [Address validation](https://github.com/vilelacc/telecep/blob/main/src/helpers/data.validation.js): `src/helpers/data.validation.js`
- [Search by CEP](https://github.com/vilelacc/telecep/blob/main/src/helpers/search.by.zip.code.js): `src/helpers/search.by.zip.code.js`
- [Search by address](https://github.com/vilelacc/telecep/blob/main/src/helpers/search.by.address.js): `src/helpers/search.by.address.js`

### Other components

- **Telegram user**
- **ViaCEP API**
- [Project metadata](https://github.com/vilelacc/telecep/blob/main/package.json): `package.json`

## Connections

- Telegram user → Bot commands: sends commands
- Bot commands → Telegram user: replies
- Bot commands → CEP lookup flow: enters /cep
- Bot commands → Address lookup flow: enters /addr
- Bot commands → About and support text: uses replies
- About and support text → Project metadata: reads version and author
- Address lookup flow → Federative units: offers states
- Address lookup flow → Address validation: validates input
- Address lookup flow → Search by address: searches address
- CEP lookup flow → Search by CEP: searches CEP
- Search by CEP → ViaCEP API: requests CEP data
- Search by address → ViaCEP API: requests address data