1. O Hub Orquestrador Multi-Modelos

O coração da arquitetura de IA do Academic Companion consiste em desacoplar a regra de negócio dos provedores de inferência por meio de um AI Gateway Centralizado. Em vez do backend chamar a API do Gemini ou da OpenAI diretamente, ele consome uma interface unificada que gerencia limites de taxa (rate limits), cotas gratuitas e transição transparente para o faturamento sob demanda (pay-as-you-go).

[Requisição do Backend]
           │
           ▼
┌──────────────────────────────────────────────┐
│        AI Gateway / Hub Orquestrador         │
│  (Padronização OpenAI-compatible / LiteLLM)  │
└──────┬──────────────┬──────────────┬─────────┘
       │ (1º Teto)    │ (2º Teto)    │ (Fallback Pago)
       ▼              ▼              ▼
┌──────────────┐┌──────────────┐┌────────────────┐
│GitHub Models ││ Gemini Free  ││ Gemini Pay-Go  │
│ (Llama/Phi)  ││ (AI Studio)  ││ (Cobre o resto)│
└──────────────┘└──────────────┘└────────────────┘

1. Topologia de Roteamento em Cascata (Fallback)

Para extrair o valor máximo das cotas gratuitas e garantir disponibilidade contínua sem que o usuário final receba erros de limite excedido (HTTP 429), o orquestrador opera em quatro camadas de execução:

Nível 1 (Cota Zero-Cost Rápida): Requisições simples de chat ou tarefas textuais básicas são direcionadas primariamente para o GitHub Models ou provedores de altíssima velocidade como o Groq (usando modelos como Llama 3.3 ou Mistral).
Nível 2 (Créditos Subsidiados): Esgotado o limite de requisições por minuto do nível 1, a fila redireciona para o Azure OpenAI utilizando os créditos do GitHub Student Pack.
Nível 3 (Google AI Studio Free Tier): Chamadas que exigem maior raciocínio ou contexto textual amplo são enviadas para o Gemini 1.5 Flash na cota gratuita de 15 RPM.
Nível 4 (Rede de Segurança Pay-as-you-go): Quando qualquer upstream retornar erro 429 Too Many Requests ou Resource Exhausted, o gateway intercepta a falha e despacha a chamada imediatamente para o Gemini com cartão vinculado, garantindo 100% de uptime gastando apenas frações de centavos.

2. Padronização da Camada de Integração

Integrar SDKs proprietários diferentes para cada provedor torna a manutenção inviável. A solução é adotar uma especificação unificada:

Padrão OpenAI-Compatible: Praticamente todas as plataformas (LiteLLM, Azure, Groq, GitHub Models e até o Gemini via adapter) aceitam o formato de payload de chat completions da OpenAI.
LiteLLM Core: Utilizar uma instância leve do LiteLLM (como proxy ou biblioteca) permite configurar roteamento dinâmico, rotação de chaves de API, controle de tentativas (retries) e orçamento diário (budget caps) através de um único arquivo de configuração.
Respostas Estruturadas Garantidas: O orquestrador injeta esquemas estritos (compatíveis com Zod no Node.js ou DTOs no Java) para assegurar que, independentemente do modelo que processou o texto no fallback, a resposta respeite o mesmo formato JSON.

title: 2. Pipeline RAG, Chunking Inteligente e Busca Vetorial com `pgvector`

Para que o Academic Companion consiga ler um edital de 50 páginas e responder com precisão cirúrgica sem estourar o limite de tokens, a aplicação não pode enviar o documento inteiro para a IA. É aqui que entra o RAG (Retrieval-Augmented Generation).

O RAG inverte a lógica: em vez de a IA ler tudo, o seu banco de dados faz o trabalho pesado de encontrar as três ou quatro regras relevantes do edital, e a IA atua apenas como uma “intérprete” final desses trechos.

Veja como estruturar isso no backend, aproveitando o ecossistema do PostgreSQL.

1. O Desafio do Chunking (Fragmentação de Texto)

Quando o bot extrai o texto do edital, esse bloco gigante precisa ser fatiado (chunked). Se você cortar o texto de forma bruta (ex: a cada 1000 caracteres), correrá o risco de cortar uma frase no meio, separando a pergunta da resposta.

A Solução: Chunking Semântico com Overlap

Em Node.js (usando bibliotecas como LangChain.js ou LlamaIndex.js) ou no Spring Boot (com Spring AI), você implementa um Recursive Character Text Splitter.

Tamanho do Chunk: Cerca de 500 a 1000 tokens (tamanho ideal para manter o contexto sem diluir o significado).
Overlap (Sobreposição): Você configura um overlap de 10% a 20%. Isso significa que o final do Chunk 1 se repete no início do Chunk 2. Isso impede que regras ou artigos do edital percam o sentido caso o corte aconteça no meio da frase.
Injeção de Metadados: Antes de vetorizar, cada chunk deve receber um “carimbo”. Exemplo: [Edital PIBIC 2026 - Pág 4] {texto do chunk}. Isso ajuda a IA a citar a fonte corretamente na resposta final.

2. Geração de Embeddings (O Custo Zero Oculto)

Um embedding é a tradução de um pedaço de texto para um vetor (uma lista de números, ex: [0.12, -0.45, 0.89...]). Textos com significados semelhantes terão vetores próximos matematicamente.

Para economizar os tokens da sua conta Google ou Azure, a geração de embeddings não precisa ser paga:

Embeddings Locais (Custo Zero): Você pode rodar modelos de embedding diretamente no seu backend usando bibliotecas como Transformers.js (no ecossistema Node/TypeScript) ou ONNX (no ecossistema Java). Modelos pequenos e eficientes, como o BGE-m3 ou all-MiniLM-L6-v2, geram embeddings de altíssima qualidade consumindo apenas um pouco de RAM do servidor, sem fazer requisições externas.
Embeddings via API: Se preferir delegar, o text-embedding-004 do Gemini ou o modelo do Azure são extremamente baratos, mas consumiriam sua cota. Para bootstrapping, a via local é a mais indicada.

3. Armazenamento Vetorial: PostgreSQL + `pgvector`

Como você já lida com arquiteturas relacionais, não é necessário adicionar um banco de dados novo (como Pinecone ou Weaviate) e complicar a infraestrutura. A extensão pgvector permite armazenar vetores diretamente no PostgreSQL.

Estrutura no ORM (Prisma ou Sequelize):

A tabela de chunks do edital ficaria parecida com isso:

id (UUID)
edital_id (Chave Estrangeira para a tabela de Editais)
content (O texto real do chunk)
embedding (Coluna do tipo vector(768) ou vector(1536), dependendo do modelo)
metadata (JSONB com página, data, etc.)

Indexação Crucial: Para que a busca não fique lenta quando a plataforma tiver milhares de chunks, é mandatório criar um índice HNSW (Hierarchical Navigable Small World) na coluna do vetor. Ele permite buscas ultrarrápidas, calculando a similaridade de cosseno em milissegundos.

4. O Segredo da Precisão: Busca Híbrida (Hybrid Search)

Um erro comum em plataformas educacionais com IA é depender apenas da busca vetorial (semântica). A busca vetorial é ótima para conceitos (ex: “auxílio financeiro” acha “bolsa de manutenção”), mas é péssima para termos exatos (ex: siglas como “Edital PROGRAD 042/2026”).

A arquitetura de ponta exige uma Busca Híbrida:

Busca Vetorial (pgvector): Encontra o sentido da pergunta.
Busca Full-Text (FTS nativo do Postgres / BM25): Encontra as palavras-chave exatas.
Reranking: Um algoritmo simples junta os resultados das duas buscas, remove os duplicados e manda os 4 fragmentos mais relevantes (com maior pontuação combinada) para o orquestrador (Hub) que construímos no Doc 01.

Só então, o modelo final (Gemini Flash ou Azure) lê a pergunta do usuário, lê esses 4 fragmentos, e gera a resposta: “De acordo com a página 4 do edital, a carga horária exigida é…”

title: 3. Estratégias de Redução de Tokens e Caching Semântico

A maior armadilha financeira ao escalar uma plataforma educacional com IA é pagar para o modelo “pensar” na mesma resposta várias vezes. Em uma universidade, centenas de alunos vão fazer essencialmente a mesma pergunta sobre o mesmo edital ou oportunidade.

Para que a operação do Academic Companion seja financeiramente sustentável e se mantenha dentro das cotas gratuitas e de baixo custo, precisamos blindar as requisições antes que elas cheguem às APIs (Gemini ou OpenAI).

Aqui estão as três táticas de defesa e otimização.

1. O Escudo Principal: Caching Semântico

O cache tradicional (como um Redis padrão) só funciona se a string for exatamente igual. Se o Aluno A perguntar “Qual o prazo de inscrição?” e o Aluno B perguntar “Até quando posso me inscrever?”, o cache tradicional não reconhece a semelhança e a sua plataforma paga por duas requisições à IA.

O Cache Semântico resolve isso comparando o significado da pergunta.

Como funciona na prática:

O Aluno A faz a pergunta.
O sistema gera o embedding (vetor) dessa pergunta.
Antes de ir para o banco buscar os fragmentos do RAG ou chamar o LLM, o backend faz uma busca rápida em uma tabela dedicada de semantic_cache no PostgreSQL (ou em um Redis turbinado com busca vetorial).
Se o vetor da nova pergunta tiver uma similaridade acima de 95% com uma pergunta já respondida, o sistema retorna a resposta salva instantaneamente. Custo de LLM = 0. Tempo de resposta = < 50ms.
Se não houver similaridade (um Cache Miss), o fluxo normal segue e a nova resposta é salva no cache para os próximos alunos.

2. A Arma Secreta para Documentos Gigantes: Context Caching

Mesmo usando a técnica de RAG (Documento 02), existem casos onde o bot precisa analisar o documento como um todo, cruzando regras complexas de diferentes páginas que o chunking fragmentou. Nesses cenários, a API do Gemini oferece uma funcionalidade nativa de Context Caching (Cache de Contexto).

Em vez de enviar o edital de 40 páginas a cada requisição e queimar sua cota de Tokens por Minuto (TPM):

Você envia o PDF para a API do Google uma única vez e diz: “Guarde isso no cache por 30 dias” (o tempo que o edital ficar aberto).
A API devolve um identificador (ID) desse cache.
Nas próximas perguntas dos alunos, o seu bot envia apenas a pergunta curta e o ID do cache.
O impacto: O processamento da IA fica quase instantâneo e o custo faturado dos tokens de entrada despenca drasticamente, pois o modelo não precisa reler o documento inteiro.

3. Compressão de Saída e System Prompts Rigorosos

Modelos de linguagem são programados para serem “educados” e verborrágicos. Responder “Olá! Tudo bem? De acordo com a minha análise do documento fornecido…” gasta tokens de saída desnecessários.

Técnicas de contenção:

Zero-shot Formatting: No prompt de sistema, instrua o orquestrador com regras absolutas: “Responda diretamente. Não inclua saudações, introduções ou justificativas. Seja estritamente conciso.”
Uso de Schemas (Structured Outputs): Tanto no ecossistema Node.js (usando Zod) quanto no Spring Boot, force a IA a responder em JSON estrito.

Se o bot precisa apenas validar se o aluno é elegível, não peça um texto. Peça um JSON: {"elegivel": true, "motivo": "cumpre os requisitos de renda"}. Isso corta o desperdício de tokens na raiz e facilita a integração dos dados na interface da plataforma.

4. Roteamento de Janela de Contexto (Context Window Routing)

Esta é uma técnica avançada para o Orquestrador (Hub) que definimos no Doc 01.

O backend calcula o tamanho do prompt antes de enviar para a IA.

Se a pergunta + os fragmentos recuperados do banco somarem menos de 8.000 tokens, a requisição é roteada para os modelos gratuitos e ultrarrápidos do GitHub Models (Llama 3, Phi).
Se o contexto ultrapassar esse limite, o roteador desvia automaticamente para o Gemini 1.5 Flash, que possui uma janela massiva. Assim, você preserva a cota do Gemini apenas para as tarefas que realmente exigem muito fôlego.

Se a estratégia de economia e cache estiver clara, o próximo passo é a validação de documentos visuais (que é fundamental para a análise de currículos e portfólio acadêmico).

title: 4. Motor Multimodal (Visão/Certificados) e Transcrição de Áudio

Para o Academic Companion, a capacidade de validar certificados de horas complementares (que frequentemente são imagens escaneadas ou fotos de celular) e processar áudio (caso você implemente comandos de voz ou transcrição de aulas) exige um fluxo diferente do RAG textual.

O objetivo aqui é manter o custo baixo e a latência mínima no seu backend Node.js.

1. Validação de Certificados (Visão Computacional de Baixo Custo)

O processo de OCR tradicional (tentar extrair o texto de uma foto e depois passar para a IA) ficou obsoleto com os modelos multimodais. A melhor abordagem no Node.js é enviar o buffer da imagem diretamente para a IA analisar a estrutura visual e os dados de uma vez só.

A Ferramenta Ideal: Gemini 1.5 Flash. Ele é imbatível em processamento multimodal de baixo custo e alta velocidade.

Como estruturar no Node.js (com Express ou Next.js):

Recepção do Arquivo: Use o middleware multer para interceptar o upload do certificado no seu endpoint. Em vez de salvar no disco, mantenha o arquivo em memória (multer.memoryStorage()) para processamento rápido.
Conversão e Envio: Converta o buffer do arquivo para uma string base64. Usando o Vercel AI SDK ou o SDK oficial do Google Gen AI (@google/genai), você anexa a imagem diretamente no array de mensagens.
Forçando a Saída Estruturada (Zod):

Este é o pulo do gato. Você não quer que a IA responda “Sim, este certificado parece válido”. Você precisa de dados para salvar no PostgreSQL (via Prisma). Você define um schema rigoroso usando zod:

TypeScript
```
import { z } from 'zod';

const CertificadoSchema = z.object({
  valido: z.boolean(),
  nome_aluno: z.string(),
  carga_horaria: z.number(),
  instituicao_emissora: z.string(),
  motivo_rejeicao: z.string().optional()
});
```
O backend envia a imagem e esse schema para o Gemini. A IA devolve um JSON perfeitamente tipado e pronto para ser inserido no banco de dados, ignorando formatações visuais bagunçadas do certificado original.

2. Transcrição de Áudio (Speech-to-Text)

Se o sistema precisar transcrever áudios de usuários (ex: interação por voz com o bot) ou arquivos maiores, modelos de texto não servem. Você precisa do Whisper (o modelo de transcrição open-source da OpenAI).

Rodar o Whisper localmente no Node.js consome muita CPU/GPU e pode travar a sua API. Como a meta é otimizar as cotas gratuitas e de startups, aqui estão as melhores rotas de arquitetura:

A Rota de Ultra Velocidade (Groq API):

A Groq fornece acesso ao modelo whisper-large-v3 rodando em hardware de altíssima performance (LPUs). A transcrição é praticamente instantânea.
Eles possuem um Free Tier muito generoso para desenvolvedores, o que é perfeito para o bootstrapping do projeto.
Implementação: Seu backend Node.js recebe o áudio via multer, repassa o buffer para o endpoint de áudio da Groq e recebe a string de texto transcrita em milissegundos. Esse texto então segue para o orquestrador (Hub) que desenhamos no Doc 01 para ser processado.

A Rota Subsidiada (Azure OpenAI):

Utilizando os créditos do GitHub Student Pack, você pode acessar a API do Whisper hospedada na Microsoft. A latência é um pouco maior que a da Groq, mas você não gasta dinheiro real e mantém tudo dentro do budget estudantil.

3. Segurança e Prevenção de Abuso Multimodal

Processar imagens e áudios custa mais tokens do que processar texto. Para evitar que usuários mal-intencionados ou bots de terceiros esgotem a sua cota do AI Studio / Groq enviando lixo, o backend Node.js precisa de duas barreiras:

Validação de Assinatura (Magic Bytes): Não confie na extensão .png ou .pdf do arquivo. Use bibliotecas como file-type no Node para ler os primeiros bytes do buffer e garantir que o upload é genuinamente uma imagem ou áudio antes de enviar para a IA.
Limitação de Tamanho Rígida: Corte arquivos de áudio muito longos ou imagens em altíssima resolução (4K) antes do envio. Redimensionar imagens usando o sharp no Node.js para uma resolução aceitável (ex: max 1024x1024) reduz drasticamente o peso do envio e o consumo de tokens na IA, sem perder a qualidade necessária para a leitura do certificado.

title: ’5. Implementação Prática, Resiliência a Falhas e Gestão de Custos ## ’

1. Observabilidade e Rastreamento de Tokens

Você não pode gerenciar o que não pode medir. Se o sistema apenas chamar as APIs da OpenAI, Google e Groq às cegas, você não saberá qual bot está consumindo mais recursos.

A Solução no Node.js (LLMOps):

Em vez de logar o consumo manualmente no banco, utilize ferramentas de observabilidade de código aberto focadas em IA, como Langfuse ou Helicone.

Integração: Elas funcionam como um middleware no seu código Node.js ou como um proxy. Você troca a URL base da chamada da API pela URL do Helicone, por exemplo.
Painel Centralizado: Essas ferramentas interceptam a requisição e geram dashboards automáticos mostrando exatamente quantos tokens de entrada/saída foram gastos, a latência de cada modelo, o custo em centavos (mesmo no pay-as-you-go) e o histórico completo dos prompts gerados, facilitando o debug se a IA começar a responder de forma errada.

2. Processamento Assíncrono com Filas (BullMQ)

A leitura de um edital de fomento ou a extração e vetorização de 50 páginas não é uma tarefa instantânea. Se você fizer isso de forma síncrona no Express.js ou em funções Serverless, a requisição vai dar timeout e o usuário verá uma tela de erro.

Arquitetura Baseada em Eventos: Para tarefas pesadas, o backend deve apenas receber o arquivo, salvar no armazenamento e responder ao usuário: “Processando documento…”.
Mensageria (BullMQ + Redis): Utilize o BullMQ no Node.js para criar uma fila de processamento. Os workers pegam o documento em segundo plano, fazem o chunking, geram os embeddings e salvam no PostgreSQL via Prisma de forma isolada. Se a API do Gemini falhar por limite de taxa no meio do processo, o BullMQ tenta novamente (retry automático com backoff exponencial) sem quebrar o resto do sistema.

3. Padrão Circuit Breaker para Resiliência

Quando você orquestra múltiplas IAs, a queda de um provedor não pode derrubar o seu hub. Se os servidores do Azure OpenAI caírem ou se a sua chave do GitHub Student expirar, o sistema precisa reagir.

Implementação: Utilize bibliotecas como opossum no Node.js para criar um Circuit Breaker.
A Lógica: Se a IA primária (nível 1) falhar 3 vezes seguidas, o “circuito abre”. O sistema para de enviar requisições para a IA falha temporariamente (evitando acúmulo de tráfego) e desvia todo o fluxo imediatamente para o Gemini 1.5 Flash (nível 2) ou para o seu plano pay-as-you-go. Após alguns minutos, ele faz testes em background para ver se a IA primária voltou.

4. Estratégia de Deploy e Banco de Dados

Considerando que o seu ecossistema gira em torno de Node.js, Prisma e Docker, a infraestrutura inicial precisa equilibrar performance e custo zero.

API Node.js: Se você utiliza a Vercel para o frontend, pode hospedar a API lá, mas cuidado com os limites rigorosos de timeout (10 a 60 segundos no plano gratuito) das Serverless Functions. Para um orquestrador de IA operando via WebSockets ou filas pesadas, conteinerizar o backend com seu Dockerfile padrão e fazer o deploy via Cloudflare Tunnels em um servidor VPS barato (como Hetzner ou DigitalOcean) garante controle total do ambiente.
PostgreSQL + pgvector: Serviços como o Supabase oferecem instâncias gratuitas de PostgreSQL que já vêm com a extensão pgvector pré-instalada e pronta para o Prisma conectar, eliminando a dor de cabeça de configurar o banco vetorial do zero na fase de MVP.

title: 6. Políticas de Limites, Quotas e Prevenção de Abuso (AI Safeguards)

Este documento define a arquitetura de proteção do Academic Companion contra o esgotamento financeiro e estrutural da infraestrutura de IA. A implementação destas regras no backend em Node.js garantirá que o sistema se mantenha saudável, escalável e imune a abusos ou ataques de negação de serviço (DDoS) voltados ao consumo de tokens.

1. Limites de Ingestão e Multimodalidade (Uploads)

O processamento de arquivos é o maior vetor de custo. As seguintes regras devem ser aplicadas no middleware (ex: Multer) antes que o payload alcance o orquestrador de IA:

Tipo de Arquivo	Limite Rígido	Mecanismo de Defesa (Node.js)
Imagens (Certificados, etc)	Máximo 5 MB / 1080p	Validação de Magic Bytes (ignorar extensão falsa). Compressão forçada via sharp antes do envio para a IA.
Documentos Textuais (PDF/DOCX)	Máximo 10 Páginas (ou 500kb)	Arquivos maiores vão para uma fila de processamento assíncrono (BullMQ) para extração via RAG, e não para o chat ao vivo.
Áudio (Whisper/Transcrição)	Máximo 3 Minutos	Corte automático do buffer no backend. Áudios longos são rejeitados imediatamente com código HTTP 413.

2. Limites da Janela de Contexto (Tokens por Requisição)

Para evitar que um usuário mal-intencionado copie e cole um livro inteiro no chat para esgotar a cota diária do provedor, estabelece-se um limite estrito de tokens de entrada:

Chat Geral (Interações Rápidas): Limite de entrada truncado em 2.000 tokens (aprox. 1.500 palavras). O backend usará a biblioteca tiktoken (ou similar) para estimar os tokens. Se exceder, o prompt é cortado ou rejeitado antes da requisição.
Análise de Editais (RAG): O número máximo de fragmentos (chunks) injetados do PostgreSQL (pgvector) no contexto da IA será restrito a 5 fragmentos por pergunta (aprox. 4.000 tokens no total).
Limite de Saída (Max Tokens): Todas as requisições devem incluir o parâmetro max_tokens configurado para, no máximo, 500 a 800 tokens, impedindo que a IA gere respostas infinitas ou em loop.

3. Quotas Temporais por Usuário (Rate Limiting)

O consumo da IA será rastreado por usuário autenticado (ou por IP) utilizando o Redis para controle de estado. O modelo segue um formato de baldes d’água (Token Bucket).

Janela de Tempo	Quota Permitida	Objetivo e Comportamento
A cada 1 Minuto (Burst)	5 Mensagens	Bloqueia cliques duplos, scripts de spam e bots. O usuário recebe HTTP 429 (Too Many Requests).
A cada 5 Horas (Sessão)	50 Interações	Acomoda o ciclo de estudo intensivo do aluno. Ao atingir o limite, a interface avisa que a IA precisa “descansar”, fomentando pausas.
A cada Semana (Ciclo)	250 Interações	Garante a sustentabilidade de longo prazo do nível gratuito. Ao estourar, o usuário deve aguardar a renovação semanal.

4. Degradação Graciosa (Graceful Degradation)

O que acontece quando o sistema como um todo atinge os limites da infraestrutura global (mesmo que o usuário não tenha estourado sua cota pessoal)? O orquestrador aplica a degradação graciosa:

Redução de Modelos: O sistema realiza o fallback automático para modelos menores e mais rápidos para sustentar a demanda de chat.
Desativação de Recursos Multimídia: Em momentos de alta carga, a leitura de imagens e geração de embeddings pesados são temporariamente pausadas. O botão de upload na interface fica cinza (disabled).
Respostas Estáticas e Filas: O sistema prioriza 100% o cache semântico. Tarefas novas são enfileiradas no BullMQ e processadas em background quando a rede estabiliza.

5. Segurança e Prevenção de Abuso da Regra de Negócio

Proteção de Prompt (Jailbreak): Filtros aplicados no pipeline Node.js antes da requisição para bloquear termos conhecidos de tentativas de jailbreak (ex: “ignore todas as instruções anteriores”).
Zero-Trust para Assinaturas: Retornos assíncronos das filas deverão validar as requisições criptograficamente para garantir que usuários maliciosos não forjem cargas úteis diretamente para a base do Prisma.

title: 7. Arquitetura Financeira, Gateways e Monetização de IA

Este documento define a estratégia de monetização e a arquitetura do módulo de pagamentos do Academic Companion. O foco central é viabilizar a venda de pacotes de créditos de IA com valores extremamente baixos (microtransações) mantendo atrito zero na interface do usuário e preservando a margem de lucro da operação.

1. Estratégia de Microtransações e Escolha do Gateway

Para um modelo de negócios que exige a venda contínua de pacotes de R$ 6,00, R$ 10,00 e R$ 15,00, a escolha do provedor de pagamentos dita a sobrevivência financeira do software.

O Problema das Taxas Fixas: Gateways como o Asaas cobram tarifas fixas (ex: R$ 1,99 por recebimento). Em um ticket de R$ 6,00, essa taxa consome 33% do faturamento, tornando a operação insustentável.
O Bloqueio de Acesso: A Stripe possui excelentes ferramentas e taxas percentuais, mas restringe o uso do Pix no Brasil a um sistema de convites e longas análises de compliance, o que trava o lançamento imediato.
A Solução de Gateway Percentual: A infraestrutura utilizará provedores com foco em Pix e taxas estritamente percentuais, como o Mercado Pago (ou alternativas como a Efi). Com uma taxa média de 0,99%, a margem de lucro é protegida independentemente de quão baixo seja o valor da recarga.

Projeção de Margem (Exemplo com Mercado Pago a 0,99%):

Pacote de IA	Valor Pago pelo Aluno	Taxa do Gateway	Saldo Líquido (Receita)
Básico	R$ 6,00	R$ 0,05	R$ 5,95
Intermediário	R$ 10,00	R$ 0,09	R$ 9,91
Avançado	R$ 15,00	R$ 0,14	R$ 14,86

2. Motor de Créditos (Wallet) e UX de Baixo Atrito

O processamento financeiro externo (Pix) ocorre exclusivamente para a recarga de saldo. Todo o consumo da IA é gerido internamente pelo sistema.

Faturamento Interno: O backend Node.js intercepta a pergunta do aluno, envia para a IA e debita o custo exato em tokens diretamente no saldo do usuário no banco de dados. Não há chamadas de faturamento para o gateway durante o uso.
Atrito Zero (Sem Redirecionamentos): Quando os créditos acabam, a API retorna um código 402 Payment Required. O frontend exibe um modal nativo e limpo (estilizado via .module.css) oferecendo os pacotes.
Geração Instantânea: O usuário seleciona o pacote, e o backend devolve imediatamente o Pix Copia e Cola e o QR Code na mesma tela.

3. Arquitetura Desacoplada no Backend (Node.js)

O módulo de pagamentos será construído utilizando o padrão de projeto Facade (ou Strategy). Isso garante que o código não fique engessado em um único provedor.

Interface de Pagamento: O Express.js chama uma interface genérica (ex: PaymentService.generatePix()), que por baixo dos panos aciona o SDK do Mercado Pago. Se amanhã a Stripe liberar o Pix, basta trocar a classe injetada.
Processamento via Webhook: Após o pagamento, o gateway envia um evento (POST) para a rota segura de webhooks do sistema. O servidor Node.js valida a assinatura criptográfica e credita os tokens no banco.
Liberação em Tempo Real: Assim que o webhook confirma o pagamento, o servidor dispara um evento via WebSocket para o cliente. A interface desbloqueia o chat automaticamente em 2 a 3 segundos, permitindo que o aluno continue o estudo imediatamente.

4. Estrutura de Banco de Dados (Prisma + PostgreSQL)

Para garantir rastreabilidade financeira e auditoria de consumo sem sobrecarregar as consultas, os dados são separados em três entidades distintas no schema.prisma:

Wallet (Carteira): Relacionada ao usuário (user_id). Contém uma coluna balance (Inteiro) que armazena a quantidade atual de tokens disponíveis.
Transaction (Histórico Financeiro): Registra exclusivamente as movimentações em Reais (R$). Armazena o transaction_id do provedor, valor em centavos, método (Pix), status e o pacote adquirido.
UsageLog (Auditoria de IA): Registra o custo das requisições ao longo do tempo. Armazena os tokens de entrada, tokens de saída, modelo utilizado (ex: Gemini Flash, Azure) e o timestamp. Esta tabela permite gerar gráficos de consumo para o painel do usuário e prever custos de infraestrutura.