# andreramosleite1982/calculadora-rtc-simples-nacional architecture

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

- Interactive diagram: https://gitdiagram.com/andreramosleite1982/calculadora-rtc-simples-nacional
- Repository: https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional

## Overview

This is a REST API for calculating CBS and IBS taxes on Simples Nacional operations, with activity lookup, item-level observability, error descriptions, and version reporting. The main workflow accepts an operation, validates its global and item data, resolves applicable parameters and rates, processes items, and returns calculation results and totals. The excerpts establish several calculation-layer relationships; controller wiring and some storage details are not shown, so those links are omitted or marked unverified.

Main entry points: [`src/main/java/br/gov/serpro/rtc/api/simplesnacional/controller/SimplesNacionalController.java`](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/controller/SimplesNacionalController.java) (Simples API), [`src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalObservabilidadeService.java`](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalObservabilidadeService.java) (Operation validation), [`src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoOfflineService.java`](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoOfflineService.java) (Offline status), [`src/main/java/br/gov/serpro/rtc/api/atividadesimples/controller/AtividadeSimplesController.java`](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/atividadesimples/controller/AtividadeSimplesController.java) (Activity API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Observability"]
  node_simples_controller["Simples API"]
  node_operation_input["Operation input"]
  node_observability["Operation validation"]
  node_result["Observable result"]
  node_error_catalog["Error descriptions"]
end

subgraph group_activities["Activities"]
  node_activity_controller["Activity API"]
  node_activity_service["Activity lookup"]
  node_activity_data["Activity records"]
  node_activity_repository["Activity repository"]
end

subgraph group_calculation["Tax Calculation"]
  node_item_processor["Item processing"]
  node_unified_calculation["Unified calculation"]
  node_parameter_service["Calculation parameters"]
  node_rate_choice["Rate selection"]
  node_tax_calculation["Tax computation"]
end

subgraph group_reference["Tax Reference Data"]
  node_nomenclature_validation["Nomenclature validation"]
  node_nomenclature_lookup["Nomenclature lookup"]
  node_reference_db[("Embedded database")]
end

subgraph group_version["Version Status"]
  node_version_controller["Version API"]
  node_version_service["Version reporting<br/>[VersaoService.java]"]
  node_offline_version["Offline status"]
end

node_client(("API client"))
node_remote_version(("Online version service"))

node_client -->|"submits operation"| node_simples_controller
node_simples_controller -.->|"accepts payload"| node_operation_input
node_simples_controller -.->|"dispatches calculation"| node_observability
node_observability -->|"processes items"| node_item_processor
node_item_processor -->|"delegates calculation"| node_tax_calculation
node_observability -->|"builds response"| node_result
node_client -->|"requests activities"| node_activity_controller
node_activity_controller -.->|"dispatches lookup"| node_activity_service
node_activity_service -->|"queries records"| node_activity_repository
node_activity_repository -.->|"reads"| node_activity_data
node_nomenclature_validation -->|"checks nomenclature"| node_nomenclature_lookup
node_nomenclature_lookup -.->|"reads reference data"| node_reference_db
node_client -->|"requests version"| node_version_controller
node_version_controller -.->|"dispatches lookup"| node_version_service
node_offline_version -->|"compares local version"| node_version_service
node_offline_version -->|"queries remotely"| node_remote_version

click node_simples_controller "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/controller/SimplesNacionalController.java"
click node_operation_input "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/model/input/OperacaoSimplesInput.java"
click node_observability "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalObservabilidadeService.java"
click node_item_processor "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/ProcessadorItemSimples.java"
click node_unified_calculation "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/CalculoSimplesUnificadoService.java"
click node_parameter_service "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/ParametroCalculoSimplesService.java"
click node_rate_choice "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/EscolhaParAliquotasService.java"
click node_tax_calculation "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalCalculoService.java"
click node_result "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/model/output/ObservabilidadeSimplesDomain.java"
click node_error_catalog "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalErroService.java"
click node_activity_controller "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/atividadesimples/controller/AtividadeSimplesController.java"
click node_activity_service "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/atividadesimples/service/AtividadeSimplesService.java"
click node_activity_data "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/atividadesimples/entity/AtividadeSimplesNacional.java"
click node_activity_repository "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/atividadesimples/repository/AtividadeSimplesRepository.java"
click node_nomenclature_validation "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/ValidacaoNomenclaturaService.java"
click node_nomenclature_lookup "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/NomenclaturaService.java"
click node_version_controller "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/versao/controller/VersaoController.java"
click node_version_service "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoService.java"
click node_offline_version "https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/versao/service/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_simples_controller,node_operation_input,node_observability,node_result,node_error_catalog,node_client toneBlue
class node_activity_controller,node_activity_service,node_activity_data,node_activity_repository toneAmber
class node_item_processor,node_unified_calculation,node_parameter_service,node_rate_choice,node_tax_calculation toneMint
class node_nomenclature_validation,node_nomenclature_lookup,node_reference_db toneRose
class node_version_controller,node_version_service,node_offline_version,node_remote_version toneIndigo
```

## Components

### API and Observability

- [Simples API](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/controller/SimplesNacionalController.java): `src/main/java/br/gov/serpro/rtc/api/simplesnacional/controller/SimplesNacionalController.java`
- [Operation input](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/model/input/OperacaoSimplesInput.java): `src/main/java/br/gov/serpro/rtc/api/simplesnacional/model/input/OperacaoSimplesInput.java`
- [Operation validation](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalObservabilidadeService.java): `src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalObservabilidadeService.java`
- [Observable result](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/model/output/ObservabilidadeSimplesDomain.java): `src/main/java/br/gov/serpro/rtc/api/simplesnacional/model/output/ObservabilidadeSimplesDomain.java`
- [Error descriptions](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalErroService.java): `src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalErroService.java`

### Activities

- [Activity API](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/atividadesimples/controller/AtividadeSimplesController.java): `src/main/java/br/gov/serpro/rtc/api/atividadesimples/controller/AtividadeSimplesController.java`
- [Activity lookup](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/atividadesimples/service/AtividadeSimplesService.java): `src/main/java/br/gov/serpro/rtc/api/atividadesimples/service/AtividadeSimplesService.java`
- [Activity records](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/atividadesimples/entity/AtividadeSimplesNacional.java): `src/main/java/br/gov/serpro/rtc/api/atividadesimples/entity/AtividadeSimplesNacional.java`
- [Activity repository](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/atividadesimples/repository/AtividadeSimplesRepository.java): `src/main/java/br/gov/serpro/rtc/api/atividadesimples/repository/AtividadeSimplesRepository.java`

### Tax Calculation

- [Item processing](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/ProcessadorItemSimples.java): `src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/ProcessadorItemSimples.java`
- [Unified calculation](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/CalculoSimplesUnificadoService.java): `src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/CalculoSimplesUnificadoService.java`
- [Calculation parameters](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/ParametroCalculoSimplesService.java): `src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/ParametroCalculoSimplesService.java`
- [Rate selection](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/EscolhaParAliquotasService.java): `src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/EscolhaParAliquotasService.java`
- [Tax computation](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalCalculoService.java): `src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalCalculoService.java`

### Tax Reference Data

- [Nomenclature validation](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/ValidacaoNomenclaturaService.java): `src/main/java/br/gov/serpro/rtc/domain/service/ValidacaoNomenclaturaService.java`
- [Nomenclature lookup](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/domain/service/NomenclaturaService.java): `src/main/java/br/gov/serpro/rtc/domain/service/NomenclaturaService.java`
- **Embedded database**

### Version Status

- [Version API](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/versao/controller/VersaoController.java): `src/main/java/br/gov/serpro/rtc/api/versao/controller/VersaoController.java`
- [Version reporting](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoService.java): `src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoService.java`
- [Offline status](https://github.com/andreramosleite1982/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoOfflineService.java): `src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoOfflineService.java`

### Other components

- **API client**
- **Online version service**

## Connections

- API client → Simples API: submits operation (evidence: `README.md`)
- Simples API → Operation input: accepts payload (evidence: `src/main/java/br/gov/serpro/rtc/api/simplesnacional/controller/SimplesNacionalController.java`)
- Simples API → Operation validation: dispatches calculation (evidence: `src/main/java/br/gov/serpro/rtc/api/simplesnacional/controller/SimplesNacionalController.java`)
- Operation validation → Item processing: processes items (evidence: `src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalObservabilidadeService.java`)
- Item processing → Tax computation: delegates calculation
- Operation validation → Observable result: builds response (evidence: `src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalObservabilidadeService.java`)
- API client → Activity API: requests activities (evidence: `README.md`)
- Activity API → Activity lookup: dispatches lookup (evidence: `src/main/java/br/gov/serpro/rtc/api/atividadesimples/controller/AtividadeSimplesController.java`)
- Activity lookup → Activity repository: queries records (evidence: `src/main/java/br/gov/serpro/rtc/api/atividadesimples/service/AtividadeSimplesService.java`)
- Activity repository → Activity records: reads (evidence: `src/main/java/br/gov/serpro/rtc/api/atividadesimples/repository/AtividadeSimplesRepository.java`)
- Nomenclature validation → Nomenclature lookup: checks nomenclature (evidence: `src/main/java/br/gov/serpro/rtc/domain/service/ValidacaoNomenclaturaService.java`)
- Nomenclature lookup → Embedded database: reads reference data
- API client → Version API: requests version (evidence: `README.md`)
- Version API → Version reporting: dispatches lookup
- Offline status → Version reporting: compares local version (evidence: `src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoOfflineService.java`)
- Offline status → Online version service: queries remotely (evidence: `src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoOfflineService.java`)
