# dev-macb/braz architecture

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

- Interactive diagram: https://gitdiagram.com/dev-macb/braz
- Repository: https://github.com/dev-macb/braz

## Overview

Braz is a Python library with a CLI for generating and validating Brazilian identifiers, classical ciphers, hashing/encoding, and string manipulation. In the principal CLI workflow, a user selects an operation and supplies its inputs; the CLI dispatches to the corresponding library capability and prints the result. Identifier generation and validation are distinct domain stages, with shared digit/checksum helpers as an internal layer. The README documents broader CLI and package usage; unsampled modules are represented by their exact directories, and edges are limited to relationships shown in the excerpts, source index, or README.

Main entry points: [`src/braz/cli/app.py`](https://github.com/dev-macb/braz/blob/main/src/braz/cli/app.py) (CLI dispatcher), [`src/braz/validar`](https://github.com/dev-macb/braz/tree/main/src/braz/validar) (Identifier validators), [`src/braz/gerar`](https://github.com/dev-macb/braz/tree/main/src/braz/gerar) (Identifier generators), [`src/braz/shared/digit.py`](https://github.com/dev-macb/braz/blob/main/src/braz/shared/digit.py) (Checksum algorithms)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry point"]
  node_cli["CLI dispatcher<br/>[app.py]"]
end

subgraph group_identifiers["Identifiers"]
  node_generate["Identifier generators"]
  node_validate["Identifier validators"]
end

subgraph group_transform["Text transforms"]
  node_ciphers["Classical ciphers"]
  node_crypto["Hashes and encoding"]
  node_strings["String operations"]
end

subgraph group_internals["Shared internals"]
  node_checksums["Checksum algorithms<br/>[digit.py]"]
  node_validation_helpers["Validation helpers<br/>[helpers.py]"]
end

node_user(("CLI user"))

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_generate
node_cli -->|"dispatches"| node_validate
node_cli -->|"dispatches"| node_ciphers
node_cli -->|"dispatches"| node_crypto
node_cli -->|"dispatches"| node_strings
node_generate -->|"uses"| node_checksums
node_validate -->|"uses"| node_checksums
node_validate -->|"uses"| node_validation_helpers

click node_cli "https://github.com/dev-macb/braz/blob/main/src/braz/cli/app.py"
click node_generate "https://github.com/dev-macb/braz/tree/main/src/braz/gerar"
click node_validate "https://github.com/dev-macb/braz/tree/main/src/braz/validar"
click node_checksums "https://github.com/dev-macb/braz/blob/main/src/braz/shared/digit.py"
click node_validation_helpers "https://github.com/dev-macb/braz/blob/main/src/braz/shared/helpers.py"
click node_ciphers "https://github.com/dev-macb/braz/tree/main/src/braz/cifras"
click node_crypto "https://github.com/dev-macb/braz/tree/main/src/braz/criptografia"
click node_strings "https://github.com/dev-macb/braz/tree/main/src/braz/strings"

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_cli,node_user toneBlue
class node_generate,node_validate toneAmber
class node_ciphers,node_crypto,node_strings toneMint
class node_checksums,node_validation_helpers toneRose
```

## Components

### Entry point

- [CLI dispatcher](https://github.com/dev-macb/braz/blob/main/src/braz/cli/app.py): `src/braz/cli/app.py`

### Identifiers

- [Identifier generators](https://github.com/dev-macb/braz/tree/main/src/braz/gerar): `src/braz/gerar`
- [Identifier validators](https://github.com/dev-macb/braz/tree/main/src/braz/validar): `src/braz/validar`

### Text transforms

- [Classical ciphers](https://github.com/dev-macb/braz/tree/main/src/braz/cifras): `src/braz/cifras`
- [Hashes and encoding](https://github.com/dev-macb/braz/tree/main/src/braz/criptografia): `src/braz/criptografia`
- [String operations](https://github.com/dev-macb/braz/tree/main/src/braz/strings): `src/braz/strings`

### Shared internals

- [Checksum algorithms](https://github.com/dev-macb/braz/blob/main/src/braz/shared/digit.py): `src/braz/shared/digit.py`
- [Validation helpers](https://github.com/dev-macb/braz/blob/main/src/braz/shared/helpers.py): `src/braz/shared/helpers.py`

### Other components

- **CLI user**

## Connections

- CLI user → CLI dispatcher: invokes (evidence: `README.md`)
- CLI dispatcher → Identifier generators: dispatches (evidence: `src/braz/cli/app.py`)
- CLI dispatcher → Identifier validators: dispatches (evidence: `src/braz/cli/app.py`)
- CLI dispatcher → Classical ciphers: dispatches (evidence: `src/braz/cli/app.py`)
- CLI dispatcher → Hashes and encoding: dispatches (evidence: `src/braz/cli/app.py`)
- CLI dispatcher → String operations: dispatches (evidence: `src/braz/cli/app.py`)
- Identifier generators → Checksum algorithms: uses (evidence: `src/braz/gerar/titulo.py`)
- Identifier validators → Checksum algorithms: uses (evidence: `src/braz/validar/cnpj.py`)
- Identifier validators → Validation helpers: uses (evidence: `src/braz/validar/cnpj.py`)