# matheuscfs/legislacao-tributaria architecture

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

- Interactive diagram: https://gitdiagram.com/matheuscfs/legislacao-tributaria
- Repository: https://github.com/matheuscfs/legislacao-tributaria

## Overview

This repository is a public, versioned catalog of Brazilian tax laws and product-tax tables, refreshed from official sources. Its principal workflow is the capture runner downloading source material, delegating format-specific conversion, and writing changed Markdown, CSV, JSON, and metadata into the catalog; Git history then exposes the changes. Separate branches cover federal norms, CONFAZ acts, product classification tables, and discovery of new complementary laws. The sampled files show the runner and several converters; relationships for some unsampled table branches are supported only by the source index or README.

Main entry points: [`scripts/capturar.ts`](https://github.com/matheuscfs/legislacao-tributaria/blob/main/scripts/capturar.ts) (Capture runner), [`src/gravar.ts`](https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/gravar.ts) (Change-aware writer), [`src/fonte.ts`](https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/fonte.ts) (Official-source download), [`src/planalto.ts`](https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/planalto.ts) (Planalto converter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and conversion"]
  node_runner["Capture runner<br/>[capturar.ts]"]
  node_download["Official-source download<br/>[fonte.ts]"]
  node_writer["Change-aware writer<br/>[gravar.ts]"]
  node_planalto["Planalto converter<br/>[planalto.ts]"]
  node_confazconv["CONFAZ converter<br/>[confaz.ts]"]
  node_ncmconv["NCM converter<br/>[ncm.ts]"]
  node_ibscbsconv["IBS/CBS converter<br/>[ibs-cbs.ts]"]
  node_cestconv["CEST converter<br/>[cest.ts]"]
  node_tipiconv["TIPI converter<br/>[tipi.ts]"]
  node_discoveryconv["Complementary-law discovery<br/>[descoberta.ts]"]
end

subgraph group_laws["Legislation catalog"]
  node_federal[("Federal norms")]
  node_confazacts[("CONFAZ acts")]
end

subgraph group_product["Product tables"]
  node_ncmdata[("NCM table")]
  node_ibscbsdata[("IBS/CBS tables")]
  node_cestdata[("CEST tables")]
  node_tipidata[("TIPI table")]
end

subgraph group_discovery["Law discovery"]
  node_discoverydata[("New-law index")]
end

node_user(("Maintainer"))
node_confazsource(("CONFAZ source"))
node_officialsources(("Official sources"))
node_proxy["Brazil proxy endpoint<br/>[buscar.js]"]

node_user -->|"starts capture"| node_runner
node_runner -->|"downloads sources"| node_download
node_download -->|"fetches from"| node_officialsources
node_download -.->|"optionally proxies"| node_proxy
node_runner -->|"converts norms"| node_planalto
node_runner -->|"converts acts"| node_confazconv
node_runner -->|"converts NCM"| node_ncmconv
node_runner -->|"converts classifications"| node_ibscbsconv
node_runner -->|"converts CEST"| node_cestconv
node_runner -->|"converts TIPI"| node_tipiconv
node_runner -->|"discovers laws"| node_discoveryconv
node_runner -->|"writes changed data"| node_writer
node_planalto -->|"produces Markdown"| node_federal
node_confazconv -->|"produces Markdown"| node_confazacts
node_runner -->|"stores converted norms"| node_federal
node_runner -->|"stores converted acts"| node_confazacts
node_runner -->|"writes table"| node_ncmdata
node_runner -->|"writes tables"| node_ibscbsdata
node_runner -->|"writes tables"| node_cestdata
node_runner -->|"writes table"| node_tipidata
node_runner -->|"writes index"| node_discoverydata
node_ncmconv -->|"formats CSV"| node_writer
node_ibscbsconv -->|"formats tables"| node_writer
node_cestconv -->|"formats CSV"| node_writer
node_tipiconv -->|"formats CSV"| node_writer
node_discoveryconv -->|"formats CSV"| node_writer
node_confazsource -.->|"provides acts"| node_download

click node_runner "https://github.com/matheuscfs/legislacao-tributaria/blob/main/scripts/capturar.ts"
click node_download "https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/fonte.ts"
click node_writer "https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/gravar.ts"
click node_planalto "https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/planalto.ts"
click node_confazconv "https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/confaz.ts"
click node_federal "https://github.com/matheuscfs/legislacao-tributaria/tree/main/normas/federal"
click node_confazacts "https://github.com/matheuscfs/legislacao-tributaria/tree/main/normas/confaz"
click node_ncmconv "https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/ncm.ts"
click node_ibscbsconv "https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/ibs-cbs.ts"
click node_cestconv "https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/cest.ts"
click node_tipiconv "https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/tipi.ts"
click node_ncmdata "https://github.com/matheuscfs/legislacao-tributaria/tree/main/tabelas/ncm"
click node_ibscbsdata "https://github.com/matheuscfs/legislacao-tributaria/tree/main/tabelas/ibs-cbs"
click node_cestdata "https://github.com/matheuscfs/legislacao-tributaria/tree/main/tabelas/cest"
click node_tipidata "https://github.com/matheuscfs/legislacao-tributaria/tree/main/tabelas/tipi"
click node_discoveryconv "https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/descoberta.ts"
click node_discoverydata "https://github.com/matheuscfs/legislacao-tributaria/tree/main/novidades"
click node_proxy "https://github.com/matheuscfs/legislacao-tributaria/blob/main/proxy/api/buscar.js"

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_runner,node_download,node_writer,node_planalto,node_confazconv,node_ncmconv,node_ibscbsconv,node_cestconv,node_tipiconv,node_discoveryconv toneBlue
class node_federal,node_confazacts toneAmber
class node_ncmdata,node_ibscbsdata,node_cestdata,node_tipidata toneMint
class node_discoverydata toneRose
class node_user,node_confazsource,node_officialsources toneIndigo
class node_proxy toneTeal
```

## Components

### Capture and conversion

- [Capture runner](https://github.com/matheuscfs/legislacao-tributaria/blob/main/scripts/capturar.ts): `scripts/capturar.ts`
- [Official-source download](https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/fonte.ts): `src/fonte.ts`
- [Change-aware writer](https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/gravar.ts): `src/gravar.ts`
- [Planalto converter](https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/planalto.ts): `src/planalto.ts`
- [CONFAZ converter](https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/confaz.ts): `src/confaz.ts`
- [NCM converter](https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/ncm.ts): `src/ncm.ts`
- [IBS/CBS converter](https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/ibs-cbs.ts): `src/ibs-cbs.ts`
- [CEST converter](https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/cest.ts): `src/cest.ts`
- [TIPI converter](https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/tipi.ts): `src/tipi.ts`
- [Complementary-law discovery](https://github.com/matheuscfs/legislacao-tributaria/blob/main/src/descoberta.ts): `src/descoberta.ts`

### Legislation catalog

- [Federal norms](https://github.com/matheuscfs/legislacao-tributaria/tree/main/normas/federal): `normas/federal`
- [CONFAZ acts](https://github.com/matheuscfs/legislacao-tributaria/tree/main/normas/confaz): `normas/confaz`

### Product tables

- [NCM table](https://github.com/matheuscfs/legislacao-tributaria/tree/main/tabelas/ncm): `tabelas/ncm`
- [IBS/CBS tables](https://github.com/matheuscfs/legislacao-tributaria/tree/main/tabelas/ibs-cbs): `tabelas/ibs-cbs`
- [CEST tables](https://github.com/matheuscfs/legislacao-tributaria/tree/main/tabelas/cest): `tabelas/cest`
- [TIPI table](https://github.com/matheuscfs/legislacao-tributaria/tree/main/tabelas/tipi): `tabelas/tipi`

### Law discovery

- [New-law index](https://github.com/matheuscfs/legislacao-tributaria/tree/main/novidades): `novidades`

### Other components

- **Maintainer**
- **CONFAZ source**
- **Official sources**
- [Brazil proxy endpoint](https://github.com/matheuscfs/legislacao-tributaria/blob/main/proxy/api/buscar.js): `proxy/api/buscar.js`

## Connections

- Maintainer → Capture runner: starts capture (evidence: `scripts/capturar.ts`)
- Capture runner → Official-source download: downloads sources (evidence: `scripts/capturar.ts`)
- Official-source download → Official sources: fetches from (evidence: `src/fonte.ts`)
- Official-source download → Brazil proxy endpoint: optionally proxies (evidence: `src/fonte.ts`)
- Capture runner → Planalto converter: converts norms (evidence: `scripts/capturar.ts`)
- Capture runner → CONFAZ converter: converts acts (evidence: `scripts/capturar.ts`)
- Capture runner → NCM converter: converts NCM (evidence: `scripts/capturar.ts`)
- Capture runner → IBS/CBS converter: converts classifications (evidence: `scripts/capturar.ts`)
- Capture runner → CEST converter: converts CEST (evidence: `scripts/capturar.ts`)
- Capture runner → TIPI converter: converts TIPI (evidence: `scripts/capturar.ts`)
- Capture runner → Complementary-law discovery: discovers laws (evidence: `scripts/capturar.ts`)
- Capture runner → Change-aware writer: writes changed data (evidence: `scripts/capturar.ts`)
- Planalto converter → Federal norms: produces Markdown (evidence: `README.md`)
- CONFAZ converter → CONFAZ acts: produces Markdown (evidence: `README.md`)
- Capture runner → Federal norms: stores converted norms (evidence: `scripts/capturar.ts`)
- Capture runner → CONFAZ acts: stores converted acts (evidence: `scripts/capturar.ts`)
- Capture runner → NCM table: writes table (evidence: `scripts/capturar.ts`)
- Capture runner → IBS/CBS tables: writes tables (evidence: `scripts/capturar.ts`)
- Capture runner → CEST tables: writes tables (evidence: `scripts/capturar.ts`)
- Capture runner → TIPI table: writes table (evidence: `scripts/capturar.ts`)
- Capture runner → New-law index: writes index (evidence: `scripts/capturar.ts`)
- NCM converter → Change-aware writer: formats CSV (evidence: `src/ncm.ts`)
- IBS/CBS converter → Change-aware writer: formats tables (evidence: `src/ibs-cbs.ts`)
- CEST converter → Change-aware writer: formats CSV (evidence: `src/cest.ts`)
- TIPI converter → Change-aware writer: formats CSV (evidence: `src/tipi.ts`)
- Complementary-law discovery → Change-aware writer: formats CSV (evidence: `src/descoberta.ts`)
- CONFAZ source → Official-source download: provides acts
