Melon Wallet — Documentação Oficial

Visão Geral do Sistema

Propósito e Proposta de Valor

O Melon Wallet é uma plataforma unificada de gestão financeira pessoal, projetada para funcionar como aplicativo nativo em dispositivos móveis e desktop. Sua proposta de valor combina simulação de patrimônio, acompanhamento de investimentos, categorização inteligente de gastos e assistência por inteligência artificial em uma experiência contínua, com foco em privacidade, performance offline e usabilidade mobile.

Arquitetura Funcional

O sistema organiza-se em camadas desacopladas:

Interface do usuário (Front-end): Responsável por toda a interação visual, entrada de dados, renderização de gráficos e orquestração local dos estados da aplicação.
Serviços em nuvem (Backend): Gerencia autenticação, persistência de dados financeiros e sincronização em tempo real entre dispositivos.
Motor de Inteligência Artificial: Atua como assistente financeiro especializado, recebendo contexto do usuário e retornando respostas orientadas a finanças pessoais.
Camada PWA (Progressive Web App): Envolve a aplicação com capacidades de instalação, cache inteligente e funcionamento offline, eliminando dependência de conectividade contínua.

A comunicação entre essas camadas segue o princípio de menor privilégio: o front-end consome apenas os endpoints estritamente necessários, enquanto o motor de IA opera com regras de contenção que impedem vazamento de contexto para assuntos externos ao domínio financeiro.

Stack Tecnológica

Front-end: Aplicação web modular baseada em JavaScript puro, sem frameworks pesados, priorizando performance e controle granular do DOM.
Estilização: CSS puro com arquitetura de design system própria, utilizando variáveis CSS, grid, flexbox e media queries para responsividade.
Backend: Ambiente de execução JavaScript server-side, responsável por serviços auxiliares como gerenciamento de notificações push.
Funções serverless: Rotas de API executadas em ambiente serverless para integração com serviços de IA, OCR e Open Finance.
Banco de dados: PostgreSQL gerenciado, com sincronização em tempo real via mecanismos nativos da plataforma.
PWA: Service Worker com estratégias de cache híbrido, manifestos de instalação e suporte a notificações push.
Inteligência Artificial: Modelo de linguagem especializado em finanças, operando via proxy server-side para proteção de credenciais.
Gráficos: Biblioteca de visualização adaptativa com plugins de rótulos, otimizada para dashboards financeiros.

PWA & Funcionamento Offline

Service Worker e Ciclo de Vida

O aplicativo utiliza um service worker para interceptar requisições de rede e gerenciar o ciclo de vida da aplicação fora do navegador. Esse componente roda em background independente da interface e é responsável por:

Registrar-se automaticamente na primeira visita e nas atualizações de versão;
Controlar a transição entre versões sem intervenção do usuário;
Garantir que ativos essenciais permaneçam disponíveis mesmo após fechamento completo do navegador (modo standalone);
Gerenciar a transição entre estados online e offline com mínimo impacto na experiência.

Estratégia de Cache Híbrido

A estratégia de cache distingue três categorias de conteúdo:

Navegação e shell da aplicação: A estrutura visual principal (layout, componentes estruturais, telas-base) é cacheada com atualização em background, garantindo que o usuário sempre abra a interface mesmo sem internet.
Dados estáticos: Imagens, ícones, fontes e recursos do design system seguem política de cache com validade estendida e invalidação por hash, evitando downloads repetidos.
Estados e dados dinâmicos: As informações financeiras do usuário são armazenadas localmente com sincronização diferida. Quando o dispositivo detecta perda de conectividade, o app transiciona silenciosamente para leitura e escrita no armazenamento local, e reconcilia alterações com a nuvem assim que a conexão é restaurada.

Notificações Push e Rastreamento de Assinaturas

O sistema implementa notificações push como canal proativo de engajamento, com duas modalidades principais:

Alertas acionáveis: Notificações que exigem resposta do usuário (ex: confirmação de meta atingida, solicitação de revisão de categoria), apresentando ações diretas na própria notificação.
Resumos inteligentes: Agrupamento periódico de ocorrências financeiras relevantes, entregando um panorama consolidado sem poluição de notificações individuais.

O gerenciamento de inscrições é feito de forma transparente, permitindo que o usuário gerencie preferências de recebimento por tipo de evento diretamente no aplicativo.

Inteligência Artificial & Guardrails de Segurança

O Papel do Assistente Financeiro

O assistente de inteligência artificial funciona como um especialista em finanças pessoais integrado à experiência do usuário. Ele recebe contexto sobre os dados do aplicativo (histórico de transações, metas, saldo) e responde em linguagem natural, auxiliando em:

Interpretação de tendências de gastos e receitas;
Sugestões de categorização e organização financeira;
Explicações de termos e indicadores presentes na interface;
Alertas baseados no comportamento financeiro do usuário.

A inteligência artificial não executa ações financeiras automaticamente; seu papel é exclusivamente informativo e consultivo.

Política e Regras de Contenção (Guardrails)

Nível 1 — Foco Total

O assistente opera estritamente dentro do domínio de finanças pessoais e dados do aplicativo. Sua base de conhecimento e capacidade de interpretação estão limitadas a:

Perguntas sobre saldo, rendimentos, investimentos e metas;
Dúvidas sobre funcionalidades disponíveis na plataforma;
Análise de padrões de consumo e sugestões de planejamento.

Nível 2 — Bloqueio Absoluto

Qualquer solicitação fora do escopo financeiro é bloqueada de forma explícita e polida. Isso inclui, mas não se limita a, entretenimento, cultura pop, política, esportes, tecnologia geral e temas pessoais não relacionados à gestão financeira. O assistente não gera conteúdo fora desse domínio, mesmo que solicitado de forma indireta.

Nível 3 — Ponte de Contexto

Saudações genéricas, perguntas utilitárias sobre o aplicativo (ex: "que horas são?", "qual a previsão do tempo?") e cumprimentos são redirecionadas inteligentemente de volta ao contexto financeiro. O assistente reconhece a intenção do usuário, mas reapresenta a conversa dentro do universo do aplicativo, preservando a experiência focada sem ignorar a interação.

Autenticação & Banco de Dados (Segurança e Privacidade)

Camada de Persistência e Sincronização

Os dados financeiros dos usuários são armazenados em infraestrutura de nuvem com sincronização em tempo real. Essa camada garante que alterações feitas em um dispositivo (lançamentos, edições de meta, uploads de comprovantes) estejam disponíveis imediatamente em todos os dispositivos autenticados do mesmo usuário.

A sincronização segue modelo otimista com reconciliação eventual: alterações são aplicadas localmente antes de confirmadas na nuvem, e conflitos são resolvidos por regras de consistência configuradas no backend, sem exigir intervenção do usuário na maioria dos casos.

Padrões de Segurança Aplicados

Autenticação: O fluxo de autenticação utiliza protocolos seguros com troca de credenciais criptografadas, sem exposição de segredos no front-end.
Transporte: Toda comunicação entre cliente e servidor é realizada sobre conexão criptografada.
Autorização: O acesso a dados é isolado por usuário; o back-end valida permissões a cada requisição, impedindo que um usuário acesse dados de outro.
Privacidade de dados financeiros: Informações sensíveis (valores, categorias pessoais, documentos) são tratadas com políticas de retenção e criptografia em repouso, alinhadas às expectativas de um aplicativo de gestão financeira.
Open Banking: Integrações bancárias seguem fluxo de consentimento explícito do usuário, com credenciais nunca armazenadas em texto plano e uso limitado aos escopos autorizados.

Design System & Interface Humana (UI/UX)

Conceitos Estéticos

A interface adota um design system coeso baseado em:

Dark mode nativo: Paleta escura como estado padrão, reduzindo fadiga visual e alinhando-se a aplicativos financeiros modernos.
Glassmorphism: Efeitos de vidro fosco translúcido em cartões, modais e barras de navegação, criando profundidade sem poluir a leitura.
Responsividade fluida: Layouts adaptativos que transitam naturalmente entre desktop e mobile, utilizando unidades relativas, grids flexíveis e breakpoints calibrados para telas de 360px a larguras estendidas.

Elementos Interativos

Cards com efeito 3D (Tilt): Cartões de funcionalidades respondem ao movimento do ponteiro com transformações tridimensionais suaves, mantendo desempenho via aceleração de hardware.
Gráficos dinâmicos: Componentes visuais adaptativos ajustam proporção, densidade de dados e legendas conforme a tela, preservando legibilidade tanto no celular quanto no desktop.
Modais customizados: Sistema de diálogos próprio com animações de entrada/saída, suporte a temas claro e escuro, e comportamentos distintos para alertas, confirmações e formulários.

Diretrizes de Acessibilidade e Experiência Mobile

Navegação contínua: Scroll vertical livre, sem bloqueios acidentais ou zonas mortas na viewport.
Prevenção de zoom indesejado: Configurações de viewport bloqueiam pinch-to-zoom acidental, preservando a sensação de app nativo sem comprometer a legibilidade.
Alvos de toque adequados: Botões e elementos interativos possuem áreas mínimas de toque calibradas para dedos.
Feedback visual: Estados de hover, active e focus são tratados com transições visuais claras; o sistema evita seleção acidental de texto em botões e cartões para não quebrar a imersão.
Suporte a telas notch: O layout respeita áreas seguras de dispositivos com recortes, utilizando insets e viewport-fit para garantir que conteúdo crítico não seja ocultado.

Componentes da Aplicação

Dashboard e Métricas

O painel principal organiza-se em seções hierárquicas:

Cabeçalho: Acesso rápido a ações principais, saudação do usuário e sincronização bancária.
Cards de métricas: Indicadores de saldo, rendimento previsto e volume de lançamentos, com tendências visuais.
Área de gráficos: Histórico patrimonial e distribuição por categorias, adaptativos ao tamanho da tela.
Tabela de movimentações: Listagem paginada de lançamentos com ações individuais e scroll otimizado para touch.
Seção de objetivos: Barra de progresso visual com marcadores animados, permitindo acompanhamento visual de metas de investimento.

Gestão de Dados Financeiros

Lançamentos manuais: Registro de entradas, saídas e investimentos com data, valor, categoria e descrição.
Categorização inteligente: Classificação automática de transações por nome do estabelecimento, com aprendizado baseado no histórico.
Open Banking: Integração com instituições financeiras via widget seguro, permitindo sincronização automática de transações.
Comprovantes: Upload e armazenamento de documentos financeiros, vinculados a lançamentos específicos.

Sistema de Temas

A aplicação oferece alternância entre tema escuro nativo e tema claro, com transições suaves em todos os elementos. O tema selecionado é persistido localmente e aplicado consistentemente em todos os componentes, incluindo gráficos, modais e elementos de vidro fosco.

Fluxos Principais

Autenticação e Onboarding

Usuário acessa a página inicial e pode criar conta ou fazer login.
Após autenticação, é redirecionado para o dashboard principal.
Sessão é mantida de forma segura, com validação de acesso a cada visita.

Registro e Categorização

Usuário adiciona lançamento manualmente ou via sincronização bancária.
Sistema aplica categorização automática quando disponível.
Dados são sincronizados em tempo real com a nuvem.

Análise e Inteligência Artificial

Usuário consulta o assistente financeiro sobre qualquer dado ou funcionalidade.
Assistente responde exclusivamente dentro do domínio de finanças pessoais.
Sugestões e alertas são gerados com base no comportamento financeiro detectado.

Instalação e Offline

Usuário instala o aplicativo na tela inicial via prompt nativo ou guia específico para dispositivos móveis.
Service Worker cacheia a aplicação para funcionamento offline completo.
Em caso de perda de conexão, interface continua operacional com dados locais.
Ao reconectar, alterações são sincronizadas automaticamente.