# receitafederal/calculadora-rtc-regime-regular architecture

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

- Interactive diagram: https://gitdiagram.com/receitafederal/calculadora-rtc-regime-regular
- Repository: https://github.com/receitafederal/calculadora-rtc-regime-regular

## Overview

Calculadora de Tributos is a Spring REST API for calculating CBS, IBS and Imposto Seletivo, looking up official tax tables, and generating or validating fiscal-document XML. The main request flow accepts an operation, processes and validates its items, calculates taxes, and returns a consolidated result. Separate API branches provide unified tax bases, NFS-e services, open-data lookups, toll calculations, and offline-version/download functions. The graph reflects README capabilities and sampled/indexed source; unsampled controller wiring and several auxiliary branches are shown only as unverified dashed links.

Main entry points: [`src/main/java/br/gov/serpro/rtc/domain/service/calculotributo/CalculoCbsIbsService.java`](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/calculotributo/CalculoCbsIbsService.java) (CBS IBS calculation), [`src/main/java/br/gov/serpro/rtc/api/controller/BaseCalculoController.java`](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/controller/BaseCalculoController.java) (Base controllers), [`src/main/java/br/gov/serpro/rtc/api/controller`](https://github.com/receitafederal/calculadora-rtc-regime-regular/tree/main/src/main/java/br/gov/serpro/rtc/api/controller) (Auxiliary controllers), [`src/main/java/br/gov/serpro/rtc/api/controller/CalculadoraTributoController.java`](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/controller/CalculadoraTributoController.java) (Tax controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_application["Application"]
  node_calc_controller["Tax controller"]
  node_base_controller["Base controllers"]
  node_open_controller["Open-data controller"]
  node_xml_controller["XML controller<br/>[XMLController.java]"]
  node_nfse_controller["NFS-e controller"]
  node_other_controllers["Auxiliary controllers"]
  node_operation_input["Operation input"]
end

subgraph group_calculation["Tax Calculation"]
  node_item_processing["Item validation"]
  node_tax_calculation["CBS IBS calculation"]
  node_tax_orchestration["Tax orchestration"]
  node_roc_result["Tax result model<br/>[ObjetoDomain.java]"]
  node_base_calculation["Unified tax base"]
  node_nfse_base["NFS-e tax base"]
  node_rounding["Precision utilities"]
end

subgraph group_fiscal["Fiscal Services"]
  node_nfse_service["NFS-e services<br/>[NfseService.java]"]
  node_xml_services["Document XML<br/>[XmlService.java]"]
  node_pedagio_service["Toll calculation"]
  node_offline_service["Offline version"]
end

subgraph group_data["Tax Data"]
  node_open_data["Open-data queries"]
  node_tax_repository["Tax repositories"]
  node_redutor_service["Government reducer"]
  node_redutor_repository["Reducer repository"]
  node_database[("SQLite database")]
end

node_caller(("API caller"))

node_caller -->|"submits operation"| node_calc_controller
node_calc_controller -.->|"dispatches items"| node_item_processing
node_item_processing -.->|"validates for"| node_tax_calculation
node_tax_orchestration -->|"runs calculations"| node_tax_calculation
node_tax_calculation -->|"builds tax data"| node_roc_result
node_tax_calculation -->|"uses precision"| node_rounding
node_caller -->|"requests tax base"| node_base_controller
node_base_controller -.->|"dispatches request"| node_base_calculation
node_base_controller -.->|"dispatches NFS-e"| node_nfse_base
node_nfse_base -->|"rounds amounts"| node_rounding
node_caller -->|"queries tax tables"| node_open_controller
node_open_controller -.->|"dispatches query"| node_open_data
node_open_data -.->|"queries classifications"| node_tax_repository
node_redutor_service -->|"fetches reducer"| node_redutor_repository
node_redutor_repository -.->|"reads tax data"| node_database
node_caller -->|"generates or validates XML"| node_xml_controller
node_xml_controller -.->|"dispatches document"| node_xml_services
node_caller -.->|"requests NFS-e service"| node_nfse_controller
node_nfse_controller -.->|"dispatches request"| node_nfse_service
node_caller -.->|"uses auxiliary endpoints"| node_other_controllers
node_other_controllers -.->|"dispatches toll request"| node_pedagio_service
node_other_controllers -.->|"dispatches version request"| node_offline_service

click node_application "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/CalculadoraTributoApplication.java"
click node_calc_controller "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/controller/CalculadoraTributoController.java"
click node_base_controller "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/controller/BaseCalculoController.java"
click node_open_controller "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/controller/DadosAbertosController.java"
click node_xml_controller "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/controller/XMLController.java"
click node_nfse_controller "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/controller/NfseController.java"
click node_other_controllers "https://github.com/receitafederal/calculadora-rtc-regime-regular/tree/main/src/main/java/br/gov/serpro/rtc/api/controller"
click node_operation_input "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/model/input/ItemOperacaoInput.java"
click node_item_processing "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/ProcessamentoItemService.java"
click node_tax_calculation "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/calculotributo/CalculoCbsIbsService.java"
click node_tax_orchestration "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/calculotributo/CalculoTributoService.java"
click node_roc_result "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/model/roc/ObjetoDomain.java"
click node_base_calculation "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/basecalculo/BaseCalculoService.java"
click node_nfse_base "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/basecalculo/BaseCalculoUnificadaNfseService.java"
click node_rounding "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/core/util/ArredondamentoUtils.java"
click node_open_data "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/dadosabertos/DadosAbertosService.java"
click node_tax_repository "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/repository/ClassificacaoTributariaRepository.java"
click node_redutor_service "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/RedutorCompraGovernamentalService.java"
click node_redutor_repository "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/repository/RedutorCompraGovernamentalRepository.java"
click node_nfse_service "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/nfse/NfseService.java"
click node_xml_services "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/xml/XmlService.java"
click node_pedagio_service "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/pedagio/PedagioService.java"
click node_offline_service "https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/offline/VersaoOfflineService.java"

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_application,node_calc_controller,node_base_controller,node_open_controller,node_xml_controller,node_nfse_controller,node_other_controllers,node_operation_input toneBlue
class node_item_processing,node_tax_calculation,node_tax_orchestration,node_roc_result,node_base_calculation,node_nfse_base,node_rounding toneAmber
class node_nfse_service,node_xml_services,node_pedagio_service,node_offline_service,node_caller toneMint
class node_open_data,node_tax_repository,node_redutor_service,node_redutor_repository,node_database toneRose
```

## Components

### REST API

- [Application](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/CalculadoraTributoApplication.java): `src/main/java/br/gov/serpro/rtc/CalculadoraTributoApplication.java`
- [Tax controller](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/controller/CalculadoraTributoController.java): `src/main/java/br/gov/serpro/rtc/api/controller/CalculadoraTributoController.java`
- [Base controllers](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/controller/BaseCalculoController.java): `src/main/java/br/gov/serpro/rtc/api/controller/BaseCalculoController.java`
- [Open-data controller](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/controller/DadosAbertosController.java): `src/main/java/br/gov/serpro/rtc/api/controller/DadosAbertosController.java`
- [XML controller](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/controller/XMLController.java): `src/main/java/br/gov/serpro/rtc/api/controller/XMLController.java`
- [NFS-e controller](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/controller/NfseController.java): `src/main/java/br/gov/serpro/rtc/api/controller/NfseController.java`
- [Auxiliary controllers](https://github.com/receitafederal/calculadora-rtc-regime-regular/tree/main/src/main/java/br/gov/serpro/rtc/api/controller): `src/main/java/br/gov/serpro/rtc/api/controller`
- [Operation input](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/model/input/ItemOperacaoInput.java): `src/main/java/br/gov/serpro/rtc/api/model/input/ItemOperacaoInput.java`

### Tax Calculation

- [Item validation](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/ProcessamentoItemService.java): `src/main/java/br/gov/serpro/rtc/domain/service/ProcessamentoItemService.java`
- [CBS IBS calculation](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/calculotributo/CalculoCbsIbsService.java): `src/main/java/br/gov/serpro/rtc/domain/service/calculotributo/CalculoCbsIbsService.java`
- [Tax orchestration](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/calculotributo/CalculoTributoService.java): `src/main/java/br/gov/serpro/rtc/domain/service/calculotributo/CalculoTributoService.java`
- [Tax result model](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/api/model/roc/ObjetoDomain.java): `src/main/java/br/gov/serpro/rtc/api/model/roc/ObjetoDomain.java`
- [Unified tax base](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/basecalculo/BaseCalculoService.java): `src/main/java/br/gov/serpro/rtc/domain/service/basecalculo/BaseCalculoService.java`
- [NFS-e tax base](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/basecalculo/BaseCalculoUnificadaNfseService.java): `src/main/java/br/gov/serpro/rtc/domain/service/basecalculo/BaseCalculoUnificadaNfseService.java`
- [Precision utilities](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/core/util/ArredondamentoUtils.java): `src/main/java/br/gov/serpro/rtc/core/util/ArredondamentoUtils.java`

### Fiscal Services

- [NFS-e services](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/nfse/NfseService.java): `src/main/java/br/gov/serpro/rtc/domain/service/nfse/NfseService.java`
- [Document XML](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/xml/XmlService.java): `src/main/java/br/gov/serpro/rtc/domain/service/xml/XmlService.java`
- [Toll calculation](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/pedagio/PedagioService.java): `src/main/java/br/gov/serpro/rtc/domain/service/pedagio/PedagioService.java`
- [Offline version](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/offline/VersaoOfflineService.java): `src/main/java/br/gov/serpro/rtc/domain/service/offline/VersaoOfflineService.java`

### Tax Data

- [Open-data queries](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/dadosabertos/DadosAbertosService.java): `src/main/java/br/gov/serpro/rtc/domain/service/dadosabertos/DadosAbertosService.java`
- [Tax repositories](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/repository/ClassificacaoTributariaRepository.java): `src/main/java/br/gov/serpro/rtc/domain/repository/ClassificacaoTributariaRepository.java`
- [Government reducer](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/RedutorCompraGovernamentalService.java): `src/main/java/br/gov/serpro/rtc/domain/service/RedutorCompraGovernamentalService.java`
- [Reducer repository](https://github.com/receitafederal/calculadora-rtc-regime-regular/blob/main/src/main/java/br/gov/serpro/rtc/domain/repository/RedutorCompraGovernamentalRepository.java): `src/main/java/br/gov/serpro/rtc/domain/repository/RedutorCompraGovernamentalRepository.java`
- **SQLite database**

### Other components

- **API caller**

## Connections

- API caller → Tax controller: submits operation (evidence: `README.md`)
- Tax controller → Item validation: dispatches items
- Item validation → CBS IBS calculation: validates for
- Tax orchestration → CBS IBS calculation: runs calculations (evidence: `src/main/java/br/gov/serpro/rtc/domain/service/calculotributo/CalculoTributoService.java`)
- CBS IBS calculation → Tax result model: builds tax data (evidence: `src/main/java/br/gov/serpro/rtc/domain/service/calculotributo/CalculoCbsIbsService.java`)
- CBS IBS calculation → Precision utilities: uses precision (evidence: `src/main/java/br/gov/serpro/rtc/domain/service/calculotributo/CalculoCbsIbsService.java`)
- API caller → Base controllers: requests tax base (evidence: `README.md`)
- Base controllers → Unified tax base: dispatches request
- Base controllers → NFS-e tax base: dispatches NFS-e
- NFS-e tax base → Precision utilities: rounds amounts (evidence: `src/main/java/br/gov/serpro/rtc/domain/service/basecalculo/BaseCalculoUnificadaNfseService.java`)
- API caller → Open-data controller: queries tax tables (evidence: `README.md`)
- Open-data controller → Open-data queries: dispatches query (evidence: `src/main/java/br/gov/serpro/rtc/api/controller/DadosAbertosController.java`)
- Open-data queries → Tax repositories: queries classifications (evidence: `src/main/java/br/gov/serpro/rtc/domain/service/dadosabertos/DadosAbertosService.java`)
- Government reducer → Reducer repository: fetches reducer (evidence: `src/main/java/br/gov/serpro/rtc/domain/service/RedutorCompraGovernamentalService.java`)
- Reducer repository → SQLite database: reads tax data
- API caller → XML controller: generates or validates XML (evidence: `README.md`)
- XML controller → Document XML: dispatches document
- API caller → NFS-e controller: requests NFS-e service
- NFS-e controller → NFS-e services: dispatches request (evidence: `src/main/java/br/gov/serpro/rtc/api/controller/NfseController.java`)
- API caller → Auxiliary controllers: uses auxiliary endpoints
- Auxiliary controllers → Toll calculation: dispatches toll request
- Auxiliary controllers → Offline version: dispatches version request
