# santosadvo/artur-voz-publico architecture

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

- Interactive diagram: https://gitdiagram.com/santosadvo/artur-voz-publico
- Repository: https://github.com/santosadvo/artur-voz-publico

## Overview

Artur-Voz is a small Brazilian Portuguese text-to-speech example with free-tier quota protection. The user supplies text through either the Python or TypeScript server-side entry point; it reserves monthly character quota, synthesizes with the primary Google voice (then a WaveNet reserve), and writes or returns MP3 audio. The Python example uses a local file counter; the TypeScript example accepts a reservation callback, with SQL documenting an atomic Postgres/Supabase option. The README also describes operating-system or browser speech as the final fallback. That fallback is documented, not implemented in the sampled examples.

Main entry points: [`exemplos/falar.py`](https://github.com/santosadvo/artur-voz-publico/blob/main/exemplos/falar.py) (Python CLI), [`exemplos/falar.ts`](https://github.com/santosadvo/artur-voz-publico/blob/main/exemplos/falar.ts) (TypeScript API), [`contador/voz_uso.sql`](https://github.com/santosadvo/artur-voz-publico/blob/main/contador/voz_uso.sql) (Atomic reservation SQL), [`voz.json`](https://github.com/santosadvo/artur-voz-publico/blob/main/voz.json) (Voice configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_python["Python CLI<br/>[falar.py]"]
  node_typescript["TypeScript API<br/>[falar.ts]"]
end

subgraph group_quota["Quota management"]
  node_local_counter[("Local counter<br/>[falar.py]")]
  node_reservation_api["Reservation callback<br/>[falar.ts]"]
  node_postgres_reservation["Atomic reservation SQL<br/>[voz_uso.sql]"]
end

subgraph group_speech["Speech generation"]
  node_voice_config["Voice configuration<br/>[voz.json]"]
end

node_user(("Text user"))
node_postgres[("Postgres / Supabase")]
node_google_tts["Google Cloud TTS"]
node_audio["MP3 audio"]
node_system_speech["System or browser speech"]

node_user -->|"provides text"| node_python
node_user -->|"provides text"| node_typescript
node_python -->|"reads settings"| node_voice_config
node_python -->|"reserves quota"| node_local_counter
node_python -->|"requests synthesis"| node_google_tts
node_python -->|"writes MP3"| node_audio
node_typescript -->|"requests reservation"| node_reservation_api
node_reservation_api -.->|"may invoke RPC"| node_postgres_reservation
node_postgres_reservation -.->|"reserves atomically"| node_postgres
node_typescript -->|"requests synthesis"| node_google_tts
node_typescript -->|"returns MP3"| node_audio
node_user -->|"uses on exhaustion"| node_system_speech

click node_python "https://github.com/santosadvo/artur-voz-publico/blob/main/exemplos/falar.py"
click node_typescript "https://github.com/santosadvo/artur-voz-publico/blob/main/exemplos/falar.ts"
click node_voice_config "https://github.com/santosadvo/artur-voz-publico/blob/main/voz.json"
click node_local_counter "https://github.com/santosadvo/artur-voz-publico/blob/main/exemplos/falar.py"
click node_reservation_api "https://github.com/santosadvo/artur-voz-publico/blob/main/exemplos/falar.ts"
click node_postgres_reservation "https://github.com/santosadvo/artur-voz-publico/blob/main/contador/voz_uso.sql"

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_python,node_typescript,node_user,node_system_speech toneBlue
class node_local_counter,node_reservation_api,node_postgres_reservation,node_postgres toneAmber
class node_voice_config toneMint
class node_google_tts,node_audio toneIndigo
```

## Components

### User entry points

- [Python CLI](https://github.com/santosadvo/artur-voz-publico/blob/main/exemplos/falar.py): `exemplos/falar.py`
- [TypeScript API](https://github.com/santosadvo/artur-voz-publico/blob/main/exemplos/falar.ts): `exemplos/falar.ts`

### Quota management

- [Local counter](https://github.com/santosadvo/artur-voz-publico/blob/main/exemplos/falar.py): `exemplos/falar.py`
- [Reservation callback](https://github.com/santosadvo/artur-voz-publico/blob/main/exemplos/falar.ts): `exemplos/falar.ts`
- [Atomic reservation SQL](https://github.com/santosadvo/artur-voz-publico/blob/main/contador/voz_uso.sql): `contador/voz_uso.sql`

### Speech generation

- [Voice configuration](https://github.com/santosadvo/artur-voz-publico/blob/main/voz.json): `voz.json`

### Other components

- **Text user**
- **Postgres / Supabase**
- **Google Cloud TTS**
- **MP3 audio**
- **System or browser speech**

## Connections

- Text user → Python CLI: provides text (evidence: `README.md`)
- Text user → TypeScript API: provides text (evidence: `README.md`)
- Python CLI → Voice configuration: reads settings (evidence: `exemplos/falar.py`)
- Python CLI → Local counter: reserves quota (evidence: `exemplos/falar.py`)
- Python CLI → Google Cloud TTS: requests synthesis (evidence: `exemplos/falar.py`)
- Python CLI → MP3 audio: writes MP3 (evidence: `exemplos/falar.py`)
- TypeScript API → Reservation callback: requests reservation (evidence: `exemplos/falar.ts`)
- Reservation callback → Atomic reservation SQL: may invoke RPC (evidence: `exemplos/falar.ts`)
- Atomic reservation SQL → Postgres / Supabase: reserves atomically (evidence: `README.md`)
- TypeScript API → Google Cloud TTS: requests synthesis (evidence: `exemplos/falar.ts`)
- TypeScript API → MP3 audio: returns MP3 (evidence: `exemplos/falar.ts`)
- Text user → System or browser speech: uses on exhaustion (evidence: `README.md`)