# receitafederal/calculadora-rtc-simples-nacional architecture

> Architecture diagram of the GitHub repository receitafederal/calculadora-rtc-simples-nacional, 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-simples-nacional
- Repository: https://github.com/receitafederal/calculadora-rtc-simples-nacional

## Overview

This is a REST API for calculating CBS/IBS tax on Simples Nacional operations, alongside activity-catalog and version endpoints. The primary workflow accepts an operation, processes items with per-item observability, and returns calculation results and errors; the README documents the calculation capabilities, while excerpts show the controller dispatch and portions of processing. The graph also preserves activity lookup and version/status branches. Some service and repository wiring is supported by the source index rather than full excerpts; uncertain calculation-service wiring is marked dashed.

Main entry points: [`src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalObservabilidadeService.java`](https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalObservabilidadeService.java) (Item processing), [`src/main/java/br/gov/serpro/rtc/api/atividadesimples/service/AtividadeSimplesService.java`](https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/atividadesimples/service/AtividadeSimplesService.java) (Activity lookup), [`src/main/java/br/gov/serpro/rtc/api/simplesnacional/controller/SimplesNacionalController.java`](https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/controller/SimplesNacionalController.java) (Calculation API), [`src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoOfflineService.java`](https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoOfflineService.java) (Offline comparison)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_calculation["Tax calculation"]
  node_calc_api["Calculation API"]
  node_operation["Operation input"]
  node_observability["Item processing"]
  node_collector["Item collector"]
  node_calculator["Tax calculation"]
  node_calc_result["Calculation result"]
  node_error_lookup["Error descriptions"]
end

subgraph group_catalog["Activity catalog"]
  node_activity_api["Activity API"]
  node_activity_service["Activity lookup"]
  node_activity_domain["Activity records"]
  node_activity_repo["Activity repository"]
end

subgraph group_parameters["Tax parameters"]
  node_parameter_service["Parameter lookup"]
  node_parameter_repos["Parameter repositories"]
  node_tax_database[("Tax database")]
end

subgraph group_version["Version status"]
  node_version_api["Version API"]
  node_version_service["Version service<br/>[VersaoService.java]"]
  node_db_version_service["Database version"]
  node_offline_service["Offline comparison"]
end

node_client(("API client"))
node_remote_api["Online installation"]

node_client -->|"submits operation"| node_calc_api
node_calc_api -->|"processes operation"| node_observability
node_calc_api -->|"accepts input"| node_operation
node_observability -->|"collects item results"| node_collector
node_observability -.->|"delegates calculation"| node_calculator
node_observability -.->|"resolves parameters"| node_parameter_service
node_observability -->|"returns results"| node_calc_result
node_client -->|"requests activities"| node_activity_api
node_activity_api -->|"queries activities"| node_activity_service
node_activity_service -->|"queries records"| node_activity_repo
node_activity_service -->|"maps activities"| node_activity_domain
node_activity_service -->|"checks parameters"| node_parameter_service
node_parameter_service -->|"queries parameters"| node_parameter_repos
node_parameter_repos -.->|"reads tax data"| node_tax_database
node_client -->|"requests version"| node_version_api
node_version_api -.->|"gets version"| node_version_service
node_version_service -->|"gets database version"| node_db_version_service
node_client -->|"checks offline status"| node_offline_service
node_offline_service -->|"gets local version"| node_version_service
node_offline_service -->|"compares online version"| node_remote_api

click node_calc_api "https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/controller/SimplesNacionalController.java"
click node_operation "https://github.com/receitafederal/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/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalObservabilidadeService.java"
click node_collector "https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/collector/ItemCollectorSimples.java"
click node_calculator "https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalCalculoService.java"
click node_calc_result "https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/model/output/ObservabilidadeSimplesDomain.java"
click node_error_lookup "https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalErroService.java"
click node_activity_api "https://github.com/receitafederal/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/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/atividadesimples/service/AtividadeSimplesService.java"
click node_activity_domain "https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/atividadesimples/entity/AtividadeSimplesNacional.java"
click node_activity_repo "https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/atividadesimples/repository/AtividadeSimplesRepository.java"
click node_parameter_service "https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/ParametroCalculoSimplesService.java"
click node_parameter_repos "https://github.com/receitafederal/calculadora-rtc-simples-nacional/tree/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/repository"
click node_version_api "https://github.com/receitafederal/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/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoService.java"
click node_db_version_service "https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoBaseDadosService.java"
click node_offline_service "https://github.com/receitafederal/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_calc_api,node_operation,node_observability,node_collector,node_calculator,node_calc_result,node_error_lookup,node_client toneBlue
class node_activity_api,node_activity_service,node_activity_domain,node_activity_repo toneAmber
class node_parameter_service,node_parameter_repos,node_tax_database toneMint
class node_version_api,node_version_service,node_db_version_service,node_offline_service toneRose
class node_remote_api toneIndigo
```

## Components

### Tax calculation

- [Calculation API](https://github.com/receitafederal/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/receitafederal/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`
- [Item processing](https://github.com/receitafederal/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`
- [Item collector](https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/collector/ItemCollectorSimples.java): `src/main/java/br/gov/serpro/rtc/api/simplesnacional/collector/ItemCollectorSimples.java`
- [Tax calculation](https://github.com/receitafederal/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`
- [Calculation result](https://github.com/receitafederal/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/receitafederal/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`

### Activity catalog

- [Activity API](https://github.com/receitafederal/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/receitafederal/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/receitafederal/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/receitafederal/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 parameters

- [Parameter lookup](https://github.com/receitafederal/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`
- [Parameter repositories](https://github.com/receitafederal/calculadora-rtc-simples-nacional/tree/main/src/main/java/br/gov/serpro/rtc/api/simplesnacional/repository): `src/main/java/br/gov/serpro/rtc/api/simplesnacional/repository`
- **Tax database**

### Version status

- [Version API](https://github.com/receitafederal/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 service](https://github.com/receitafederal/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`
- [Database version](https://github.com/receitafederal/calculadora-rtc-simples-nacional/blob/main/src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoBaseDadosService.java): `src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoBaseDadosService.java`
- [Offline comparison](https://github.com/receitafederal/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 installation**

## Connections

- API client → Calculation API: submits operation (evidence: `README.md`)
- Calculation API → Item processing: processes operation (evidence: `src/main/java/br/gov/serpro/rtc/api/simplesnacional/controller/SimplesNacionalController.java`)
- Calculation API → Operation input: accepts input (evidence: `src/main/java/br/gov/serpro/rtc/api/simplesnacional/controller/SimplesNacionalController.java`)
- Item processing → Item collector: collects item results (evidence: `src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalObservabilidadeService.java`)
- Item processing → Tax calculation: delegates calculation (evidence: `src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalObservabilidadeService.java`)
- Item processing → Parameter lookup: resolves parameters (evidence: `src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/SimplesNacionalObservabilidadeService.java`)
- Item processing → Calculation result: returns results (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: queries activities (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 lookup → Activity records: maps activities (evidence: `src/main/java/br/gov/serpro/rtc/api/atividadesimples/service/AtividadeSimplesService.java`)
- Activity lookup → Parameter lookup: checks parameters (evidence: `src/main/java/br/gov/serpro/rtc/api/atividadesimples/service/AtividadeSimplesService.java`)
- Parameter lookup → Parameter repositories: queries parameters (evidence: `src/main/java/br/gov/serpro/rtc/api/simplesnacional/service/ParametroCalculoSimplesService.java`)
- Parameter repositories → Tax database: reads tax data
- API client → Version API: requests version (evidence: `README.md`)
- Version API → Version service: gets version
- Version service → Database version: gets database version (evidence: `src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoService.java`)
- API client → Offline comparison: checks offline status (evidence: `README.md`)
- Offline comparison → Version service: gets local version (evidence: `src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoOfflineService.java`)
- Offline comparison → Online installation: compares online version (evidence: `src/main/java/br/gov/serpro/rtc/api/versao/service/VersaoOfflineService.java`)
