# staroscky/pagamento-fatura-bff-poc architecture

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

- Interactive diagram: https://gitdiagram.com/staroscky/pagamento-fatura-bff-poc
- Repository: https://github.com/staroscky/pagamento-fatura-bff-poc

## Overview

This is a payment-invoice BFF whose documented focus is starting a payment journey. The request handler delegates to a service that obtains card details, concurrently fetches invoice and balance data, creates a journey context in Redis, and maps the result. Invoice status interpretation and the journey’s separated response-mapping concerns are also represented. The sampled code supports these main calls; several APIs and mapper details are present only in the tree or README, so uncertain wiring is omitted.

Main entry points: [`src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/service/IniciacaoService.kt`](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/service/IniciacaoService.kt) (Initiation service), [`src/main/kotlin/com/staroscky/pagamentofatura/fatura/service/FaturaService.kt`](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/fatura/service/FaturaService.kt) (Invoice service), [`src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/controller/IniciacaoController.kt`](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/controller/IniciacaoController.kt) (Initiation endpoint), [`src/main/kotlin/com/staroscky/pagamentofatura/jornada/core/cache/JornadaRepository.kt`](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/core/cache/JornadaRepository.kt) (Journey repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_journey["Journey initiation"]
  node_controller["Initiation endpoint"]
  node_init_service["Initiation service"]
  node_journey_context["Journey context<br/>[JornadaContext.kt]"]
  node_journey_repo["Journey repository"]
  node_journey_cache[("Redis cache")]
  node_init_mapper["Response mapper<br/>[IniciacaoMapper.kt]"]
  node_suggestion_mapper["Amount suggestions"]
  node_invoice_mapper["Invoice mapping"]
  node_debit_mapper["Auto-debit mapping"]
  node_response["Initiation response"]
end

subgraph group_domains["Payment data"]
  node_card_api["Card API<br/>[CartaoAPI.kt]"]
  node_card_service["Card service<br/>[CartaoService.kt]"]
  node_card_info["Card details<br/>[CartaoInfo.kt]"]
  node_invoice_api["Invoice API<br/>[FaturaAPI.kt]"]
  node_invoice_service["Invoice service<br/>[FaturaService.kt]"]
  node_invoice_info["Invoice details<br/>[FaturaInfo.kt]"]
  node_status_helper["Invoice status<br/>[StatusHelper.kt]"]
  node_payment_helper["Payment status"]
  node_balance_api["Balance API<br/>[SaldoAPI.kt]"]
  node_balance_service["Balance service<br/>[SaldoService.kt]"]
  node_balance_result["Balance result<br/>[SaldoResult.kt]"]
end

subgraph group_core["Shared context"]
  node_user_context["User context<br/>[UsuarioContext.kt]"]
end

node_caller(("Client"))

node_caller -->|"submits request"| node_controller
node_controller -->|"starts journey"| node_init_service
node_init_service -->|"consults card"| node_card_api
node_card_api -->|"implemented by"| node_card_service
node_card_service -->|"returns details"| node_card_info
node_init_service -->|"fetches invoice"| node_invoice_api
node_invoice_api -->|"implemented by"| node_invoice_service
node_invoice_service -->|"evaluates status"| node_status_helper
node_invoice_service -->|"evaluates payment"| node_payment_helper
node_invoice_service -->|"returns details"| node_invoice_info
node_init_service -->|"fetches balance"| node_balance_api
node_balance_api -->|"implemented by"| node_balance_service
node_balance_service -->|"returns result"| node_balance_result
node_init_service -->|"reads user ID"| node_user_context
node_init_service -->|"creates journey"| node_journey_repo
node_init_service -->|"builds context"| node_journey_context
node_journey_repo -->|"stores context"| node_journey_cache
node_init_service -->|"maps response"| node_init_mapper
node_init_mapper -->|"builds response"| node_response

click node_controller "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/controller/IniciacaoController.kt"
click node_init_service "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/service/IniciacaoService.kt"
click node_journey_context "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/core/domain/JornadaContext.kt"
click node_journey_repo "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/core/cache/JornadaRepository.kt"
click node_init_mapper "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/mapper/IniciacaoMapper.kt"
click node_suggestion_mapper "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/mapper/SugestaoValorMapper.kt"
click node_invoice_mapper "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/mapper/InformacoesFaturaMapper.kt"
click node_debit_mapper "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/mapper/AvisoDebitoAutomaticoMapper.kt"
click node_response "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/domain/IniciacaoResponse.kt"
click node_card_api "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/cartao/CartaoAPI.kt"
click node_card_service "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/cartao/service/CartaoService.kt"
click node_card_info "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/cartao/domain/CartaoInfo.kt"
click node_invoice_api "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/fatura/FaturaAPI.kt"
click node_invoice_service "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/fatura/service/FaturaService.kt"
click node_invoice_info "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/fatura/domain/FaturaInfo.kt"
click node_status_helper "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/fatura/helper/StatusHelper.kt"
click node_payment_helper "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/fatura/helper/StatusPagamentoHelper.kt"
click node_balance_api "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/saldo/SaldoAPI.kt"
click node_balance_service "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/saldo/service/SaldoService.kt"
click node_balance_result "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/saldo/domain/SaldoResult.kt"
click node_user_context "https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/core/UsuarioContext.kt"

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_controller,node_init_service,node_journey_context,node_journey_repo,node_journey_cache,node_init_mapper,node_suggestion_mapper,node_invoice_mapper,node_debit_mapper,node_response,node_caller toneBlue
class node_card_api,node_card_service,node_card_info,node_invoice_api,node_invoice_service,node_invoice_info,node_status_helper,node_payment_helper,node_balance_api,node_balance_service,node_balance_result toneAmber
class node_user_context toneMint
```

## Components

### Journey initiation

- [Initiation endpoint](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/controller/IniciacaoController.kt): `src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/controller/IniciacaoController.kt`
- [Initiation service](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/service/IniciacaoService.kt): `src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/service/IniciacaoService.kt`
- [Journey context](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/core/domain/JornadaContext.kt): `src/main/kotlin/com/staroscky/pagamentofatura/jornada/core/domain/JornadaContext.kt`
- [Journey repository](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/core/cache/JornadaRepository.kt): `src/main/kotlin/com/staroscky/pagamentofatura/jornada/core/cache/JornadaRepository.kt`
- **Redis cache**
- [Response mapper](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/mapper/IniciacaoMapper.kt): `src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/mapper/IniciacaoMapper.kt`
- [Amount suggestions](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/mapper/SugestaoValorMapper.kt): `src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/mapper/SugestaoValorMapper.kt`
- [Invoice mapping](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/mapper/InformacoesFaturaMapper.kt): `src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/mapper/InformacoesFaturaMapper.kt`
- [Auto-debit mapping](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/mapper/AvisoDebitoAutomaticoMapper.kt): `src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/mapper/AvisoDebitoAutomaticoMapper.kt`
- [Initiation response](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/domain/IniciacaoResponse.kt): `src/main/kotlin/com/staroscky/pagamentofatura/jornada/iniciacao/domain/IniciacaoResponse.kt`

### Payment data

- [Card API](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/cartao/CartaoAPI.kt): `src/main/kotlin/com/staroscky/pagamentofatura/cartao/CartaoAPI.kt`
- [Card service](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/cartao/service/CartaoService.kt): `src/main/kotlin/com/staroscky/pagamentofatura/cartao/service/CartaoService.kt`
- [Card details](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/cartao/domain/CartaoInfo.kt): `src/main/kotlin/com/staroscky/pagamentofatura/cartao/domain/CartaoInfo.kt`
- [Invoice API](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/fatura/FaturaAPI.kt): `src/main/kotlin/com/staroscky/pagamentofatura/fatura/FaturaAPI.kt`
- [Invoice service](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/fatura/service/FaturaService.kt): `src/main/kotlin/com/staroscky/pagamentofatura/fatura/service/FaturaService.kt`
- [Invoice details](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/fatura/domain/FaturaInfo.kt): `src/main/kotlin/com/staroscky/pagamentofatura/fatura/domain/FaturaInfo.kt`
- [Invoice status](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/fatura/helper/StatusHelper.kt): `src/main/kotlin/com/staroscky/pagamentofatura/fatura/helper/StatusHelper.kt`
- [Payment status](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/fatura/helper/StatusPagamentoHelper.kt): `src/main/kotlin/com/staroscky/pagamentofatura/fatura/helper/StatusPagamentoHelper.kt`
- [Balance API](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/saldo/SaldoAPI.kt): `src/main/kotlin/com/staroscky/pagamentofatura/saldo/SaldoAPI.kt`
- [Balance service](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/saldo/service/SaldoService.kt): `src/main/kotlin/com/staroscky/pagamentofatura/saldo/service/SaldoService.kt`
- [Balance result](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/saldo/domain/SaldoResult.kt): `src/main/kotlin/com/staroscky/pagamentofatura/saldo/domain/SaldoResult.kt`

### Shared context

- [User context](https://github.com/staroscky/pagamento-fatura-bff-poc/blob/main/src/main/kotlin/com/staroscky/pagamentofatura/core/UsuarioContext.kt): `src/main/kotlin/com/staroscky/pagamentofatura/core/UsuarioContext.kt`

### Other components

- **Client**

## Connections

- Client → Initiation endpoint: submits request
- Initiation endpoint → Initiation service: starts journey
- Initiation service → Card API: consults card
- Card API → Card service: implemented by
- Card service → Card details: returns details
- Initiation service → Invoice API: fetches invoice
- Invoice API → Invoice service: implemented by
- Invoice service → Invoice status: evaluates status
- Invoice service → Payment status: evaluates payment
- Invoice service → Invoice details: returns details
- Initiation service → Balance API: fetches balance
- Balance API → Balance service: implemented by
- Balance service → Balance result: returns result
- Initiation service → User context: reads user ID
- Initiation service → Journey repository: creates journey
- Initiation service → Journey context: builds context
- Journey repository → Redis cache: stores context
- Initiation service → Response mapper: maps response
- Response mapper → Initiation response: builds response