# Documento de Escopo - Sistema de Contas do Mazdra
**Tempo estimado**: 6 Semana
---
## **Módulos do MAZDRA que serão desenvolvidos**
### **Contas**
O módulo de contas é a API que possui os métodos para fazer requisições relacionadas às contas bancárias, modificando suas informações e alterando os saldos através das múltiplas ações e serviços disponíveis no mazdra.
### **Core**
O módulo core é o cerne bancário da aplicação. Ele é responsável pelo registro em livro-caixa (Ledger) de todas as operações, auditoria das ações executadas sobre as contas no Mazdra, conciliação de caixa e fornece as informações necessárias para consolidação de saldo e formação de extrato.
---
## **Casos de Uso**
Foi modelado utilizando os conceitos contábeis algumas operações que consideramos ser as mais comuns e que englobem uma quantidade consideravel de transações.
Uma explicação mais detalhada dos conceitos contábeis pode ser vista na imagem abaixo:
### **1º Caso de Uso**
Para o primeiro caso de uso foi considerado um exemplo simples de transação bancária. Esse exemplo começa com o depósito e consolidação do Capital na conta "Caixa" da **Conta Corrente**. Em seguida, ocorre uma transferência interna, que é posteriormente consolidada em uma conta "Caixa" na **Conta de Investimento**. A próxima etapa envolve a compra de ações, seguida pela compra de um investimento de renda fixa.
Após essas transações, o pagamento da amortização na renda fixa é realizado e consolidado. Os juros da renda fixa são calculados considerando uma taxa de 10%. Em seguida, o imposto sobre o rendimento é pago, também considerando uma taxa de 10%.
Finalmente, ocorre a retirada de fundos da conta, que é então consolidada.
O fluxo dessas operações pode ser visualizado abaixo:
### **2º Caso de Uso**
Para o segundo caso de uso foi considerado uma transação que envolve, além da compra de ativos, a venda do mesmo e também uma operação utilizando o cartão de crédito. Esse modelo começa com o depósito e consolidação do Capital na conta "Caixa" da **Conta Corrente**. Em seguida, ocorre uma transferência interna, que é posteriormente consolidada em uma conta "Caixa" na **Conta de Investimento**. A próxima etapa envolve a compra de ações, seguido da venda desse mesmo ativo com um lucro de 10% sobre o valor inicialmente investido.
Após essas transações, é iniciada a transferência interna que é consolidada na conta "Caixa" da **Conta Corrente** e também uma compra de algum item não especificado utilizando um cartão de crédito.
Finalmente, ocorre a retirada de fundos da conta, que é então consolidada.
O fluxo dessas operações pode ser visualizado abaixo:
### **3º Caso de Uso**
Para o terceiro caso de uso foi considerado uma transação que envolve, além da compra de ativos, a venda do mesmo e também uma operação utilizando o cartão de crédito, uma compra À vista e um estorno de uma compra. Esse modelo começa com o depósito e consolidação do Capital na conta "Caixa" da **Conta Corrente**. Em seguida, ocorre uma transferência interna, que é posteriormente consolidada em uma conta "Caixa" na **Conta de Investimento**.
A próxima etapa envolve a compra de ações, seguido da venda desse mesmo ativo com um lucro de 50% sobre o valor inicialmente investido. Após essas transações, é iniciada a transferência interna que é consolidada na conta "Caixa" da **Conta Corrente** e também uma compra de algum item não especificado utilizando um cartão de crédito e o pagamento desse valor.
Por fim, ocorre uma compra à vista que por algum motivo é estornada, e logo em seguida há a retirada de fundos da conta, que é então consolidada.
O fluxo dessas operações pode ser visualizado abaixo:
---
## **Modelos de Dados**
### **Camada Core - Ledger**
#### **Entrada**
Uma entrada é um registro de movimentação em uma conta específica.
As entradas seguirão o modelo base a seguir:
```javascript
class Entrada {
id: string, // ID único
conta: string, // ID da conta alvo
tipo_conta: string, // Tipo da conta: "ativo" | "passivo"
fluxo: boolean, // Fluxo da entrada: true (credito) | false (debito)
valor: number,
data_emissao: datetime,
data_liquidacao: datetime,
quantidade: integer // Quantidade de estoque comprado/transferido
}
```
#### **Transação**
As entradas são partes de uma transação. Cada transação gera pelo menos duas entradas.
As transações seguirão o modelo base a seguir:
```javascript
class Transacao {
id: string,
opcode: string, // Opcode: string que identifica o tipo de transação
entradas: string[], // IDs das entradas da transação
transacao_futura: string, // ID da transação futura para o caso de uma operação em que parte é resolvida no futuro
data_emissao: datetime,
data_liquidacao: datetime,
futuro: boolean // Flag de operação futura ou não
}
```
### **Camada de Aplicação**
#### **Conta**
A entidade de Conta segura o saldo consolidado de um conjunto de subscontas. Ela seguirá o modelo base a seguir:
```javascript
class Conta {
id: string, // ID único
tags: {}, // Metadados de busca
saldo: number,
saldo_provisionado: number,
subcontas: string[], // IDs das subcontas normais
subcontas_provisoes: string[] // IDs das subcontas de provisões
}
```
#### **Subconta**
A entidade subconta segura um valor de uma natureza específica. Ela seguirá o modelo base a seguir:
```javascript
class Subconta {
id: string,
valor: number,
tipo_conta: string, // Tipo da conta: "ativo" | "passivo"
quantidade: integer // Quantidade caso seja subconta de estoque
}
```
#### **Transação Futura**
A entidade transação futura representa uma transação a ser efetuada com base no tempo. Ela pode ser a liquidação de uma transação futura ou uma transação agendada sem compromisso de sucesso. Segue o modelo a seguir:
```javascript
class Transacao_Futura {
id: string,
opcode: string, // Opcode: string que identifica o tipo de transação
id_ledger: string, // ID da transação relacionada no ledger (caso não seja apenas um agendamento) para auditoria
entradas: string[], // IDs das entradas da transação (apenas futuras)
data_emissao: datetime,
data_liquidacao: datetime
}
```
#### **Entrada Futura**
As entradas futuras são entradas de uma transação futura. Elas são geradas no momento de emissão de uma transação futura porém são incluídas no livro-caixa somente no momento da liquidação:
```javascript
class Entrada_Futura {
id: string, // ID único
conta: string, // ID da conta alvo
tipo_conta: string, // Tipo da conta: "ativo" | "passivo"
fluxo: boolean, // Fluxo da entrada: true (credito) | false (debito)
valor: number, // Valor da entrada
data_emissao: datetime,
data_liquidacao: datetime, // Data de liquidação
quantidade: integer // Quantidade de estoque comprado/transferido
}
```
### **Agendamentos Recorrentes**
Os agendamentos recorrentes são transações agendadas para serem executadas por um número de vezes num intervalo de tempo. São armazenadas de forma diferente das transações com partes futuras ou transações unitárias agendadas, é uma tabela dedicada para ter as informações necessárias para gerar as transações e as entradas conforme chega o momentos de executar a iteração da transferência.
```javascript
class Agendamento {
id: string, // ID único
conta: string, // ID da conta
conta_alvo: string, // ID da conta alvo da transação
tipo_conta: string, // Tipo da conta: "ativo" | "passivo"
valor: number,
data_emissao: datetime,
intervalo: number, // Intervalo em dias (e.g. 15, 30, 60)
id_efetivadas: string[] // IDs das transações já efetivadas no ledger
}
```
#### **Fluxo Contábil**
A seguir temos o fluxo contábil de uma transação de transferência interna:
---
## **Glossário de IDs e mapeamento de Conta Alvo**
Para facilitar a busca e manter um padrão entre as diferentes contas presentes em uma Conta de usuário criamos um glossário, de modo que dê pra consultar facilmente qual é a conta alvo da transação ao ter o ID da mesma.
Abaixo estão listadas as contas e seus sufixos:
### **Patrimonio Liquido**
| Conta | Tipo | Sufixo |
|:-------:|:-------:|:-------:|
| Capital | Passivo | PL-0000 |
### **Conta Corrente**
| Conta | Tipo | Sufixo |
|:-----------------------:|:------------:|:-------:|
| Caixa | Ativo | CC-0001 |
| Transferencia Interna | Movimentação | CC-0004 |
| Transferencia Externa | Movimentação | CC-0005 |
| Estorno | Movimentação | CC-0006 |
| Contas à receber | Ativo | CC-0009 |
| Contas à pagar | Passivo | CC-0011 |
| Cheque Especial | Ativo | CC-0013 |
| Juros - Cheque Especial | Passivo | CC-0014 |
| Lucro de Venda | Passivo | CC-0016 |
| Gastos | Ativo | CC-0034 |
| Emprestimo | Ativo | CC-0012 |
| Juros - Empréstimo | Passivo | CC-0040 |
### **Conta Investimento**
| Conta | Tipo | Sufixo |
|:---------------------------:|:------------:|:-------:|
| Caixa | Ativo | CI-0001 |
| Transferencia Interna | Movimentação | CI-0004 |
| Transferencia Externa | Movimentação | CI-0005 |
| Estorno | Movimentação | CI-0006 |
| Valor do Imposto de Renda | Passivo | CI-0008 |
| Contas à receber | Ativo | CI-0009 |
| Compras | Ativo | CI-0015 |
| Lucro de Venda | Passivo | CI-0016 |
| Valor do Ativo - Ação | Ativo | CI-0017 |
| Valor do Ativo - Renda Fixa | Ativo | CI-0018 |
| Valor do Ativo - Futuro | Ativo | CI-0019 |
| Valor do Ativo - Opção | Ativo | CI-0020 |
| Valor do Ativo - Swap | Ativo | CI-0021 |
| Estoque de Ação | Ativo | CI-0022 |
| Estoque de Renda Fixa | Ativo | CI-0023 |
| Estoque de Futuro | Ativo | CI-0024 |
| Estoque de Opção | Ativo | CI-0025 |
| Estoque de Swap | Ativo | CI-0026 |
| Dividendos | Ativo | CI-0027 |
| Prêmios | Ativo | CI-0028 |
| Amortização | Ativo | CI-0029 |
| Provisões | Passivo | CI-0030 |
| IOF | Passivo | CI-0031 |
| Tributações | Passivo | CI-0032 |
| Juros - Renda Fixa | Passivo | CI-0033 |
| Ações Disponíveis | Ativo | CI-0035 |
| Renda Fixa Disponível | Ativo | CI-0036 |
| Futuro Disponível | Ativo | CI-0037 |
| Opção Disponível | Ativo | CI-0038 |
| Swap Disponível | Ativo | CI-0039 |
### **Conta Poupança**
| Conta | Tipo | Sufixo |
|:-------------------------:|:------------:|:-------:|
| Caixa | Ativo | CP-0001 |
| Transferencia Interna | Movimentação | CP-0004 |
| Transferencia Externa | Movimentação | CP-0005 |
| Estorno | Movimentação | CP-0006 |
| Valor do Imposto de Renda | Passivo | CP-0008 |
| Rendimentos | Passivo | CP-0010 |
### **Valor Bloqueado**
| Conta | Tipo | Sufixo |
|:-------------------------:|:------------:|:-------:|
| Bloqueados | Ativo | VB-0007 |
---
## **Arquitetura**
A Arquitetura do Core Banking foi pensada para ser divida em duas camadas,a Core e a de Aplicação. Na Camada Core será utilizado o Apache Kafka como sistema de mensageria e sua funcionalidade de streaming para processamento de informações em tempo real, e o Apache Cassandra para como Banco de Dados, que será imutável através da logica de combinação de *hashs* onde caso haja inconsistencias entre as entradas subsequentes, o mesmo acusará erro.
Já na Camada de Aplicação estarão os serviços que irão consumir as informações que foram consolidadas no Ledger, como por exemplo o Extrato, Saldo, Precificação, Conciliação, Long Term Storage entre outros.
---
## **Tecnologias**
### **Apache Cassandra**
O Apache Cassandra é um banco de dados NoSQL distribuído de código aberto, confiável por milhares de empresas por sua escalabilidade e alta disponibilidade sem comprometer o desempenho. Ele é adequado para aplicações que não podem perder dados, mesmo quando um data center inteiro cai. O Cassandra é testado em clusters de até 1.000 nós e com centenas de casos de uso e esquemas do mundo real. Ele oferece suporte à replicação em vários data centers, fornecendo menor latência para seus usuários e a tranquilidade de saber que você pode sobreviver a interrupções regionais. A documentação oficial do Apache Cassandra cobre desde a instalação, a linguagem de consulta do Cassandra (CQL), a configuração, operação, ferramentas como cqlsh e nodetool, entre outros.
### **Apache Kafka**
O Apache Kafka atua como o canal de comunicação entre os diversos sistemas bancários. Ele permite que os diferentes componentes do sistema, como aplicativos de internet banking, caixas eletrônicos e sistemas de gerenciamento de contas, compartilhem dados em tempo real. Os produtores (como os sistemas de transações) enviam mensagens para tópicos específicos no Kafka, e os consumidores (como os sistemas de relatórios) se inscrevem nesses tópicos para receber as informações relevantes. As mensagens são armazenadas em partições, garantindo escalabilidade e alta disponibilidade.
### **Kafka Streaming**
O Kafka Streaming é o cliente de streaming do Kafka. Ele é uma ferramenta de streaming utilizada largamente no mercado, porém é conhecido pela complexidade de sustentação em produção. A grande vantagem é a facilidade de implementar operações em streaming com seus clientes JVM-based. As desvantagens são a complexidade de alterar, manter e fazer backup de seu motor implantado em produção e a falta de customização de suas funcionalidades, já que ele opera de forma autônoma seu cache de entradas (utiliza RocksDB para fazer sua memória KV).
---
## **Observabilidade**
Utilizaremos a stack **Prometheus** + **Grafana** para observabilidade. Boa parte dos serviços fornecem integração nativa com o Prometheus e existem boas dashboards prontas para o Grafana.
## **Implementação**
### **Imutabilidade**
No sistema de contas do Core Banking, o Ledger desempenha a função principal no sistema, onde o mesmo precisa garantir que as informações registradas nele estejam corretas e livres de ação humana.
O Apache Cassandra, banco de dados NoSQL escolhido para ser o Ledger do Core, não garante a imutabilidade nativamente. Por conta disso, essa imutabilidade será implementada por nós através da logica de *hashs* encadeados, onde cada entrada irá gerar um *hash* de si mesmo que irá ser usado para se ligar com a proxima entrada, que irá também gerar um *hash* de si mesma utilizando o *hash* anterior, contatenado com o seu conteúdo.
A logica pode ser melhor visualizada na imagem abaixo:
### **Disponibilidade**
As decisões tecnologicas quanto ao projeto do Core Banking foram feitas devido ao fato de que o mesmo precisa ser replicado em multiplas maquinas com zonas de disponibilidade, ja que ele será um sistema critico.
## **Elementos externos ao escopo**
* Não será feita a implementação de nenhum módulo do Mazdra fora ao modulo de Contas. Módulos de Emissão e Cadastro serão implementados por outros times.
Sign in with Wallet
Connect another wallet