Documentação Técnica: Arquitetura e Implementação do MMPSearch & MMPCreator 1. Visão Geral da Arquitetura O sistema foi projetado para resolver o desafio de catalogar, processar e permitir a colaboração em projetos musicais (formato LMMS) na web. A solução adota uma Arquitetura Híbrida Dinâmica-Estática: Entrada (Dinâmica): Uma API em Flask gerencia uploads, autenticação e validação de arquivos. Processamento (Batch/Background): Scripts Python executam a renderização de áudio e extração de dados XML em segundo plano. Saída (Estática): Os dados processados alimentam um gerador Jekyll, resultando em uma interface leve, segura e de baixo custo computacional para o usuário final. Colaboração (Tempo Real): Um microsserviço Node.js independente gerencia a edição via WebSockets. 2. O Fluxo de Ingestão (Backend) O ponto de entrada é o script upload_server.py. Ele atua como o "porteiro" do sistema, garantindo que apenas dados válidos entrem no pipeline. Sanitização de Arquivos: Utiliza-se a função slugify para normalizar nomes de arquivos, removendo acentos e caracteres especiais para garantir compatibilidade com URLs (ex: Ação.mmp torna-se acao.mmp). Tratamento de Compressão (.mmpz): O sistema detecta nativamente arquivos comprimidos. Ao receber um .mmpz, ele aciona o binário do LMMS (lmms --dump) para descompactar o XML, permitindo a leitura dos dados internos sem corromper o projeto original. Banco de Dados: A persistência de usuários e metadados de propriedade é feita via SQLite e SQLAlchemy, mantendo uma relação leve entre o arquivo físico e seu proprietário (User <-> Project). 3. Motor de Processamento e Renderização Headless A funcionalidade mais crítica para a dissertação é a capacidade de gerar áudio em um servidor sem monitor (headless). Isso é gerenciado pelo script main.py. Ambiente Offscreen: O script configura a variável de ambiente QT_QPA_PLATFORM="offscreen". Isso engana o LMMS (que é uma aplicação gráfica Qt), permitindo que ele rode via linha de comando dentro do servidor Linux. Renderização CLI: O áudio é gerado invocando o comando: lmms -r -o -f wav. Paralelismo: Utiliza-se a biblioteca multiprocessing para criar um pool de workers, permitindo que múltiplos projetos sejam renderizados simultaneamente, otimizando o uso da CPU. 4. Geração de Manifestos e Dados Estáticos Para desacoplar o banco de dados da interface pública, o sistema utiliza o script generate_manifest.py. Indexação: O script varre os diretórios de mídia (samples, mmp, wav) e gera arquivos JSON e YAML. Integração com Jekyll: Estes arquivos YAML são salvos diretamente na pasta _data do Jekyll, servindo como fonte de verdade para a geração das páginas HTML estáticas. 5. Engenharia de Dados: Parsing XML A "inteligência" musical do sistema reside no file_parser.py, que traduz o XML do LMMS para objetos JSON manipuláveis. Tipagem de Trilhas: O parser identifica e separa trilhas baseando-se no atributo type: Type 0: Instrumentos e Sintetizadores. Type 1: Beat/Bassline Editor (extrai padrões rítmicos). Type 2: Samples de Áudio. Type 5/6: Automação. Fallback Genérico: Implementa um padrão de projeto Strategy com fallback. Se não houver um parser específico para um plugin (ex: tripleoscillator), a função extract_generic_attributes varre o XML e converte todos os atributos encontrados, garantindo compatibilidade futura. 6. Integridade e Verificação de Dependências Para evitar a "tela azul" de arquivos faltando, o dependency_checker.py executa uma auditoria antes da publicação. Inventário do Servidor: Cria um índice de todos os arquivos de áudio existentes no disco. Heurística de Recuperação: HEALTHY: O caminho no XML bate com o servidor. RECOVERED: O caminho original (ex: C:/Users/...) não existe, mas o sistema encontrou o arquivo pelo nome e remapeou o link automaticamente. BROKEN: Arquivo inexistente; o sistema marca para alerta. 7. Frontend: Visualização e Sequenciador A interface (projetos.html) demonstra como dados complexos podem ser visualizados sem JavaScript pesado. Sequenciador CSS: A grade de bateria (Step Sequencer) é renderizada usando lógica de template Liquid e CSS puro. O template itera sobre o array de steps ({% for step in patterns %}) e aplica classes de cor condicionalmente. Interatividade Híbrida: Web Audio API: Scripts JS (InstrumentFactory) leem os dados extraídos pelo parser para tocar prévias dos sintetizadores no navegador. Modais: Uso de iframe para carregar o editor completo (MMPCreator) em uma camada sobreposta. 8. Orquestração de Serviços (Systemd) A estabilidade em produção é garantida pelo gerenciador de serviços do Linux. Serviço de Processamento (mmpsearch.service): Gerencia o Gunicorn/Flask. Timeout: Configurado para 300 segundos (5 minutos) para suportar o tempo de renderização de áudio pesado sem derrubar a conexão. Workers: 3 processos simultâneos. Serviço de Colaboração (backend-MMPCreator.service): Gerencia o Node.js. Reinício Automático: Diretiva Restart=always garante alta disponibilidade para sessões em tempo real. 9. Segurança e Permissões A infraestrutura segue o princípio de menor privilégio necessário para operação web. Usuário www-data: Ambos os serviços rodam sob este usuário, padrão para servidores web. Gestão de SSL: O serviço Node.js consome diretamente os certificados do Let's Encrypt (fullchain.pem, privkey.pem) via variáveis de ambiente, permitindo conexões seguras (WSS - WebSockets Secure). Permissões de Escrita: O sistema possui permissão explícita para escrever nas pastas de assets e src_mmpSearch, essencial para o funcionamento do gerador estático Jekyll. 10. Fluxo de Implantação (Resumo) Para fins de documentação na dissertação, o ciclo de vida de um projeto na plataforma é: Upload: Usuário envia .mmpz via API Flask (Porta 33002). Trigger: Flask salva o arquivo e dispara a thread de processamento. Processamento: Python descompacta o projeto, renderiza o .wav (Headless LMMS) e extrai o .json. Build: Python invoca bundle exec jekyll build para regenerar o HTML. Serviço: Nginx serve o novo HTML estático; Node.js aguarda conexões para edição colaborativa.