About this project

# Nebula Cafe — Predictive Footfall & Inventory Harmony System Nebula Cafe is an open-source analytical dashboard built with Streamlit, designed for coffee shop owners and managers who want to move beyond historical reporting into predictive decision-making. The project positions itself as a "decision engine" that forecasts customer footfall, optimizes ingredient restocking, and balances operational efficiency with a warm, inviting interface. ## Core Purpose Unlike traditional cafe analytics tools that simply report past sales, Nebula Cafe uses time-series forecasting (specifically LSTM models) to predict customer traffic up to 7 days ahead. This allows users to: - Staff intelligently based on predicted busy periods - Order inventory just-in-time to reduce perishable waste (claimed up to 30% reduction) - Identify slow periods for scheduling events or promotions - Compare patterns across multiple locations (for regional managers) ## Key Features ### Predictive Footfall Mapping - LSTM-based time series model for 7-day customer count forecasts - Visual timeline with confidence intervals (visualized as "cloudy bands") - Dynamic adjustments based on holiday and weather data (optional API integration) ### Intelligent Inventory Advisor - Cross-references predicted sales with current stock levels - Generates color-coded reorder lists: green (in stock), amber (order in 2 days), red (order now) - Learns from past overstock mistakes to improve future recommendations ### User Experience - Drag-and-drop widget layout that adapts to tablet or phone screens - Multilingual UI supporting English, Spanish, Mandarin, and Arabic - Built-in FAQ/support bot (rule-based, no external API keys required) - No-code theme editor for customizing colors and fonts - Offline mode for full functionality without internet ### Privacy & Data Handling - All data processed locally by default; zero cloud uploads - No authentication keys required - Anonymized aggregation ensures no customer PII is stored - Optional synthetic data generator for testing and experimentation ## Technology Stack - **Frontend:** Streamlit with custom CSS (no JavaScript libraries) - **Backend:** Python 3.10+ with Pandas, NumPy, and Prophet for forecasting - **Data Storage:** Local CSV/JSON files (optional SQLite support) - **Visualization:** Plotly for interactive charts, Matplotlib for static exports - **Testing:** PyTest for unit and integration tests ## Use Cases - **Solo Cafe Owner:** Plan events during predicted slow periods - **Regional Manager:** Compare footfall across locations to redistribute staff - **Roastery Partner:** Use inventory advisor to determine weekly bean shipments - **Investor:** Export weekly reports with ROI metrics and customer density trends ## Roadmap (2026) - **Q1 2026:** v1.0 release with core forecasting and inventory modules - **Q2 2026:** Optional competitor price tracking via public menu screenscraper - **Q3 2026:** Integration with Square/Toast POS via open API - **Q4 2026:** Mobile companion app (Flutter) for instant footfall alerts ## Installation & Usage Users can download the repository as a ZIP file from the GitHub page or clone it using a git client. The project requires Python 3.10+ and dependencies listed in the repository. No installation wizards are needed—just pure Python code. ## Community & Contribution Contributions are welcome, including: - Adding new forecasting models (e.g., ARIMA, Facebook Prophet) - Translating the UI into additional languages - Designing new widgets for environmental metrics (ambient noise, temperature) The project includes documentation in a `docs/` folder and uses GitHub issues and discussions for community support. ## License Licensed under the MIT License, allowing free use, modification, and distribution for commercial or non-commercial purposes. ## Disclaimer The software is provided "as is" without warranty. Predictive models rely on synthetic training data for demonstration and may not reflect real-world accuracy without calibration. The developer assumes no responsibility for business decisions made based on dashboard outputs. The support bot is a scripted FAQ assistant, not a live human agent. Users should always validate inventory recommendations with physical counts.