# thiagoocms/taxify-service architecture

> Architecture diagram of the GitHub repository thiagoocms/taxify-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thiagoocms/taxify-service
- Repository: https://github.com/thiagoocms/taxify-service

## Overview

Taxify is a multi-tenant tax and fiscal-document backend for accounting firms and their companies. Users authenticate and manage firm, company, subscription, and product fiscal-rule data through REST APIs. The main fiscal workflow downloads or imports fiscal XML, parses and stores document metadata and files, then supports search/export, product-rule divergence analysis, and optional XML rectification with audit logging. SIEG is the external XML provider. The sampled excerpts establish the import, storage, access-control, divergence, rectification, and token paths; unsampled API and scheduler wiring is represented only where the tree identifies those components.

Main entry points: [`src/main/java/br/com/cshub/taxify/rest`](https://github.com/thiagoocms/taxify-service/tree/master/src/main/java/br/com/cshub/taxify/rest) (REST endpoints), [`src/main/java/br/com/cshub/taxify/service/FiscalXmlIntegrationService.java`](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/FiscalXmlIntegrationService.java) (XML workflow service), [`src/main/java/br/com/cshub/taxify/service/FiscalXmlRectificationService.java`](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/FiscalXmlRectificationService.java) (XML rectification), [`src/main/java/br/com/cshub/taxify/repository`](https://github.com/thiagoocms/taxify-service/tree/master/src/main/java/br/com/cshub/taxify/repository) (Fiscal records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST and identity"]
  node_rest["REST endpoints"]
  node_auth["Authentication<br/>[AuthService.java]"]
  node_token["JWT service<br/>[TokenService.java]"]
  node_security["Request security"]
  node_error["API error mapping"]
end

subgraph group_accounts["Tenant and plans"]
  node_accounts_api["Firm and company APIs"]
  node_plans_api["Plans and subscriptions"]
  node_tenant["Tenant access checks"]
  node_current_user["Current user lookup"]
  node_account_services["Account services"]
end

subgraph group_fiscal["Fiscal documents"]
  node_fiscal_api["Fiscal XML API"]
  node_fiscal_service["XML workflow service"]
  node_sync_control["Sync control"]
  node_sync_scheduler["XML sync scheduler"]
  node_xml_parse["XML parse and extract"]
  node_xml_store["XML file storage"]
  node_fiscal_db[("Fiscal records")]
  node_rules_api["Fiscal rule API"]
  node_rules["Product fiscal rules"]
  node_divergence["Divergence analysis"]
  node_rectification["XML rectification"]
  node_audit[("Invoice audit logs")]
end

subgraph group_integrations["External integration"]
  node_sieg_provider["SIEG XML provider"]
  node_sieg_token["SIEG token client"]
end

node_user(("Accounting user"))
node_sieg(("SIEG service"))

node_user -->|"calls API"| node_rest
node_rest -->|"authenticates"| node_auth
node_auth -->|"generates token"| node_token
node_user -->|"presents token"| node_security
node_security -->|"authorizes requests"| node_rest
node_rest -->|"formats failures"| node_error
node_rest -->|"routes account requests"| node_accounts_api
node_rest -->|"routes plan requests"| node_plans_api
node_accounts_api -->|"invokes services"| node_account_services
node_plans_api -->|"invokes services"| node_account_services
node_account_services -->|"checks firm boundary"| node_tenant
node_tenant -->|"resolves principal"| node_current_user
node_current_user -->|"reads user"| node_fiscal_db
node_rest -->|"routes XML requests"| node_fiscal_api
node_fiscal_api -->|"invokes workflow"| node_fiscal_service
node_sync_scheduler -->|"starts sync"| node_fiscal_service
node_fiscal_service -->|"downloads XML"| node_sieg_provider
node_sieg_provider -->|"requests XML"| node_sieg
node_sieg_provider -->|"obtains token"| node_sieg_token
node_sieg_token -->|"requests JWT"| node_sieg
node_fiscal_service -->|"updates sync state"| node_sync_control
node_fiscal_service -->|"extracts and parses"| node_xml_parse
node_fiscal_service -->|"writes XML files"| node_xml_store
node_fiscal_service -->|"stores document data"| node_fiscal_db
node_rest -->|"routes rule requests"| node_rules_api
node_rules_api -->|"invokes rules"| node_rules
node_rules -->|"persists rules"| node_fiscal_db
node_rest -->|"requests comparison"| node_divergence
node_divergence -->|"reads items and rules"| node_fiscal_db
node_rest -->|"requests correction"| node_rectification
node_rectification -->|"reads and updates document"| node_fiscal_db
node_rectification -->|"applies product rules"| node_rules
node_rectification -->|"writes corrected XML"| node_xml_store
node_rectification -->|"records correction"| node_audit

click node_rest "https://github.com/thiagoocms/taxify-service/tree/master/src/main/java/br/com/cshub/taxify/rest"
click node_auth "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/AuthService.java"
click node_token "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/TokenService.java"
click node_security "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/config/SecurityConfig.java"
click node_error "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/rest/exception/GlobalExceptionHandler.java"
click node_accounts_api "https://github.com/thiagoocms/taxify-service/tree/master/src/main/java/br/com/cshub/taxify/rest"
click node_plans_api "https://github.com/thiagoocms/taxify-service/tree/master/src/main/java/br/com/cshub/taxify/rest"
click node_tenant "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/common/TenantAccessService.java"
click node_current_user "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/common/CurrentUserService.java"
click node_account_services "https://github.com/thiagoocms/taxify-service/tree/master/src/main/java/br/com/cshub/taxify/service"
click node_fiscal_api "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/rest/FiscalXmlResource.java"
click node_fiscal_service "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/FiscalXmlIntegrationService.java"
click node_sync_control "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/FiscalXmlSyncControlService.java"
click node_sync_scheduler "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/FiscalXmlSyncScheduler.java"
click node_xml_parse "https://github.com/thiagoocms/taxify-service/tree/master/src/main/java/br/com/cshub/taxify/integration/fiscalxml"
click node_xml_store "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/integration/sieg/FiscalXmlFileStorage.java"
click node_fiscal_db "https://github.com/thiagoocms/taxify-service/tree/master/src/main/java/br/com/cshub/taxify/repository"
click node_rules_api "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/rest/ProductFiscalRuleResource.java"
click node_rules "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/ProductFiscalRuleService.java"
click node_divergence "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/ProductFiscalDivergenceService.java"
click node_rectification "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/FiscalXmlRectificationService.java"
click node_audit "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/repository/InvoiceAuditLogRepository.java"
click node_sieg_provider "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/integration/sieg/SiegFiscalXmlProvider.java"
click node_sieg_token "https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/integration/sieg/SiegTokenService.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_rest,node_auth,node_token,node_security,node_error,node_user toneBlue
class node_accounts_api,node_plans_api,node_tenant,node_current_user,node_account_services toneAmber
class node_fiscal_api,node_fiscal_service,node_sync_control,node_sync_scheduler,node_xml_parse,node_xml_store,node_fiscal_db,node_rules_api,node_rules,node_divergence,node_rectification,node_audit toneMint
class node_sieg_provider,node_sieg_token toneRose
class node_sieg toneIndigo
```

## Components

### REST and identity

- [REST endpoints](https://github.com/thiagoocms/taxify-service/tree/master/src/main/java/br/com/cshub/taxify/rest): `src/main/java/br/com/cshub/taxify/rest`
- [Authentication](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/AuthService.java): `src/main/java/br/com/cshub/taxify/service/AuthService.java`
- [JWT service](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/TokenService.java): `src/main/java/br/com/cshub/taxify/service/TokenService.java`
- [Request security](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/config/SecurityConfig.java): `src/main/java/br/com/cshub/taxify/config/SecurityConfig.java`
- [API error mapping](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/rest/exception/GlobalExceptionHandler.java): `src/main/java/br/com/cshub/taxify/rest/exception/GlobalExceptionHandler.java`

### Tenant and plans

- [Firm and company APIs](https://github.com/thiagoocms/taxify-service/tree/master/src/main/java/br/com/cshub/taxify/rest): `src/main/java/br/com/cshub/taxify/rest`
- [Plans and subscriptions](https://github.com/thiagoocms/taxify-service/tree/master/src/main/java/br/com/cshub/taxify/rest): `src/main/java/br/com/cshub/taxify/rest`
- [Tenant access checks](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/common/TenantAccessService.java): `src/main/java/br/com/cshub/taxify/common/TenantAccessService.java`
- [Current user lookup](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/common/CurrentUserService.java): `src/main/java/br/com/cshub/taxify/common/CurrentUserService.java`
- [Account services](https://github.com/thiagoocms/taxify-service/tree/master/src/main/java/br/com/cshub/taxify/service): `src/main/java/br/com/cshub/taxify/service`

### Fiscal documents

- [Fiscal XML API](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/rest/FiscalXmlResource.java): `src/main/java/br/com/cshub/taxify/rest/FiscalXmlResource.java`
- [XML workflow service](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/FiscalXmlIntegrationService.java): `src/main/java/br/com/cshub/taxify/service/FiscalXmlIntegrationService.java`
- [Sync control](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/FiscalXmlSyncControlService.java): `src/main/java/br/com/cshub/taxify/service/FiscalXmlSyncControlService.java`
- [XML sync scheduler](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/FiscalXmlSyncScheduler.java): `src/main/java/br/com/cshub/taxify/service/FiscalXmlSyncScheduler.java`
- [XML parse and extract](https://github.com/thiagoocms/taxify-service/tree/master/src/main/java/br/com/cshub/taxify/integration/fiscalxml): `src/main/java/br/com/cshub/taxify/integration/fiscalxml`
- [XML file storage](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/integration/sieg/FiscalXmlFileStorage.java): `src/main/java/br/com/cshub/taxify/integration/sieg/FiscalXmlFileStorage.java`
- [Fiscal records](https://github.com/thiagoocms/taxify-service/tree/master/src/main/java/br/com/cshub/taxify/repository): `src/main/java/br/com/cshub/taxify/repository`
- [Fiscal rule API](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/rest/ProductFiscalRuleResource.java): `src/main/java/br/com/cshub/taxify/rest/ProductFiscalRuleResource.java`
- [Product fiscal rules](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/ProductFiscalRuleService.java): `src/main/java/br/com/cshub/taxify/service/ProductFiscalRuleService.java`
- [Divergence analysis](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/ProductFiscalDivergenceService.java): `src/main/java/br/com/cshub/taxify/service/ProductFiscalDivergenceService.java`
- [XML rectification](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/service/FiscalXmlRectificationService.java): `src/main/java/br/com/cshub/taxify/service/FiscalXmlRectificationService.java`
- [Invoice audit logs](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/repository/InvoiceAuditLogRepository.java): `src/main/java/br/com/cshub/taxify/repository/InvoiceAuditLogRepository.java`

### External integration

- [SIEG XML provider](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/integration/sieg/SiegFiscalXmlProvider.java): `src/main/java/br/com/cshub/taxify/integration/sieg/SiegFiscalXmlProvider.java`
- [SIEG token client](https://github.com/thiagoocms/taxify-service/blob/master/src/main/java/br/com/cshub/taxify/integration/sieg/SiegTokenService.java): `src/main/java/br/com/cshub/taxify/integration/sieg/SiegTokenService.java`

### Other components

- **Accounting user**
- **SIEG service**

## Connections

- Accounting user → REST endpoints: calls API
- REST endpoints → Authentication: authenticates
- Authentication → JWT service: generates token
- Accounting user → Request security: presents token
- Request security → REST endpoints: authorizes requests
- REST endpoints → API error mapping: formats failures
- REST endpoints → Firm and company APIs: routes account requests
- REST endpoints → Plans and subscriptions: routes plan requests
- Firm and company APIs → Account services: invokes services
- Plans and subscriptions → Account services: invokes services
- Account services → Tenant access checks: checks firm boundary
- Tenant access checks → Current user lookup: resolves principal
- Current user lookup → Fiscal records: reads user
- REST endpoints → Fiscal XML API: routes XML requests
- Fiscal XML API → XML workflow service: invokes workflow
- XML sync scheduler → XML workflow service: starts sync
- XML workflow service → SIEG XML provider: downloads XML
- SIEG XML provider → SIEG service: requests XML
- SIEG XML provider → SIEG token client: obtains token
- SIEG token client → SIEG service: requests JWT
- XML workflow service → Sync control: updates sync state
- XML workflow service → XML parse and extract: extracts and parses
- XML workflow service → XML file storage: writes XML files
- XML workflow service → Fiscal records: stores document data
- REST endpoints → Fiscal rule API: routes rule requests
- Fiscal rule API → Product fiscal rules: invokes rules
- Product fiscal rules → Fiscal records: persists rules
- REST endpoints → Divergence analysis: requests comparison
- Divergence analysis → Fiscal records: reads items and rules
- REST endpoints → XML rectification: requests correction
- XML rectification → Fiscal records: reads and updates document
- XML rectification → Product fiscal rules: applies product rules
- XML rectification → XML file storage: writes corrected XML
- XML rectification → Invoice audit logs: records correction