Sobre o projeto

# Nebula Cafe — Sistema de Harmonia entre Previsão de Fluxo e Estoque Nebula Cafe é um painel analítico de código aberto construído com Streamlit, projetado para proprietários e gerentes de cafeterias que desejam ir além de relatórios históricos e adotar decisões preditivas. O projeto se posiciona como um "motor de decisão" que prevê o fluxo de clientes, otimiza a reposição de ingredientes e equilibra eficiência operacional com uma interface acolhedora. ## Propósito Central Diferente de ferramentas tradicionais de análise para cafeterias que apenas relatam vendas passadas, o Nebula Cafe usa previsão de séries temporais (especificamente modelos LSTM) para prever o tráfego de clientes com até 7 dias de antecedência. Isso permite aos usuários: - Dimensionar a equipe de forma inteligente com base nos períodos de maior movimento previstos - Encomendar estoque no momento certo para reduzir o desperdício de perecíveis (redução alegada de até 30%) - Identificar períodos lentos para agendar eventos ou promoções - Comparar padrões entre várias unidades (para gerentes regionais) ## Principais Recursos ### Mapeamento Preditivo de Fluxo - Modelo de série temporal baseado em LSTM para previsões de contagem de clientes em 7 dias - Linha do tempo visual com intervalos de confiança (visualizados como "faixas nubladas") - Ajustes dinâmicos com base em feriados e dados meteorológicos (integração opcional via API) ### Consultor Inteligente de Estoque - Cruza vendas previstas com níveis atuais de estoque - Gera listas de reposição com código de cores: verde (em estoque), âmbar (encomendar em 2 dias), vermelho (encomendar agora) - Aprende com erros passados de excesso de estoque para melhorar recomendações futuras ### Experiência do Usuário - Layout de widgets com arrastar e soltar que se adapta a telas de tablet ou celular - Interface multilíngue com suporte a inglês, espanhol, mandarim e árabe - Bot de FAQ/suporte integrado (baseado em regras, sem necessidade de chaves de API externas) - Editor de temas sem código para personalizar cores e fontes - Modo offline para funcionalidade completa sem internet ### Privacidade e Tratamento de Dados - Todos os dados processados localmente por padrão; zero uploads para a nuvem - Nenhuma chave de autenticação necessária - Agregação anonimizada garante que nenhum dado pessoal identificável de clientes seja armazenado - Gerador opcional de dados sintéticos para testes e experimentação ## Stack Tecnológico - **Frontend:** Streamlit com CSS personalizado (sem bibliotecas JavaScript) - **Backend:** Python 3.10+ com Pandas, NumPy e Prophet para previsão - **Armazenamento de Dados:** Arquivos CSV/JSON locais (suporte opcional a SQLite) - **Visualização:** Plotly para gráficos interativos, Matplotlib para exportações estáticas - **Testes:** PyTest para testes unitários e de integração ## Casos de Uso - **Proprietário de Cafeteria Individual:** Planejar eventos durante períodos lentos previstos - **Gerente Regional:** Comparar fluxo entre unidades para redistribuir equipe - **Parceiro Torrefador:** Usar o consultor de estoque para determinar remessas semanais de grãos - **Investidor:** Exportar relatórios semanais com métricas de ROI e tendências de densidade de clientes ## Roadmap (2026) - **Q1 2026:** Lançamento da v1.0 com módulos centrais de previsão e estoque - **Q2 2026:** Rastreamento opcional de preços de concorrentes via screenscraper de menus públicos - **Q3 2026:** Integração com Square/Toast POS via API aberta - **Q4 2026:** Aplicativo complementar para celular (Flutter) para alertas instantâneos de fluxo ## Instalação e Uso Os usuários podem baixar o repositório como arquivo ZIP na página do GitHub ou cloná-lo usando um cliente git. O projeto requer Python 3.10+ e dependências listadas no repositório. Não são necessários assistentes de instalação — apenas código Python puro. ## Comunidade e Contribuição Contribuições são bem-vindas, incluindo: - Adicionar novos modelos de previsão (ex.: ARIMA, Facebook Prophet) - Traduzir a interface para idiomas adicionais - Projetar novos widgets para métricas ambientais (ruído ambiente, temperatura) O projeto inclui documentação em uma pasta `docs/` e usa issues e discussões do GitHub para suporte da comunidade. ## Licença Licenciado sob a Licença MIT, permitindo uso, modificação e distribuição gratuitos para fins comerciais ou não comerciais. ## Aviso Legal O software é fornecido "como está", sem garantia. Os modelos preditivos dependem de dados de treinamento sintéticos para demonstração e podem não refletir a precisão do mundo real sem calibração. O desenvolvedor não assume responsabilidade por decisões de negócios tomadas com base nas saídas do painel. O bot de suporte é um assistente de FAQ programado, não um agente humano ao vivo. Os usuários devem sempre validar as recomendações de estoque com contagens físicas.