Engenharia & Algoritmo Genético do Monvix 🛠️

Bem-vindo à documentação técnica oficial da plataforma Monvix. Este espaço destina-se a engenheiros de software, cientistas de dados e mantenedores que necessitam compreender a arquitetura dos serviços, os contratos de integração e a modelagem matemática do motor de otimização orçamentária.

---

🏛️ Filosofia de Engenharia

O Monvix foi construído sob três pilares de engenharia essenciais:

1. Separação Rígida de Responsabilidades (SoC):
   • Interface do usuário desacoplada com renderização reativa e cache local offline (PWA).
   • Backend transacional ACID para integridade contábil estrita.
   • Microsserviço analítico/estatístico em Python dedicado exclusivamente à computação matemática vetorizada.
2. Determinismo e Estabilidade Financeira:
   • Alocações em centavos calculadas através do método do maior resto (Largest Remainder Method), evitando qualquer erro de arredondamento de ponto flutuante em balanços financeiros.
   • Sementes pseudoaleatórias criptograficamente derivadas do payload canônico (SHA-256), garantindo que o mesmo questionário gere recomendações reproduzíveis.
3. Restrições Rígidas de Simplex:
   • Garantia matemática de que todo orçamento satisfaça $\sum_{i=1}^8 w_i = 1.0$ e $w_i \ge 0$.

---

🗺️ Mapa da Documentação Técnica

• Arquitetura de Microsserviços: Topologia de rede, responsabilidades de cada componente e fluxo de dados.
• Motor Evolucionário: Estrutura do cromossomo, operadores genéticos (crossover aritmético e mutação gaussiana no simplex) e convergência.
• Função de Fitness & Matemática: Formulação analítica da função de perda quadrática com penalização de pisos ($K = 1500$).
• Pisos e Regras de Negócio: Proteção de despesas de moradia, dependentes residentes, pensão judicial e multiplicadores de vínculo (CLT, PJ, Servidor).
• Referência de API: Contratos OpenAPI e esquemas Pydantic do endpoint /api/ai/optimize-allocations.
• Setup de Ambiente & Docker: Como executar a suíte completa localmente e rodar testes de regressão.