Toast Operations Platform

A comprehensive restaurant operations platform for inventory monitoring, sales analytics, and automated reporting across multiple restaurant locations.

Project Overview

This repository contains a full-stack application suite for managing restaurant operations, including real-time inventory tracking, sales data processing, and automated reporting. The platform integrates with Toast POS API and is deployed on Google Cloud Platform.

Directory Structure

annual_sales/

Sales Data ETL Pipeline & Analytics

Contains sales data processing scripts and historical sales data for multiple restaurant locations. Includes:

  • Sales Data: CSV files organized by store location (aptos, bbq152, bbqpit, canyons, crossroads, mission, redwood, salinas, trail_dust, wagon, winchester) and year (2024, 2025)

  • Processing Scripts: Python scripts for converting, filtering, cleaning, and reformatting sales reports

  • Data Import: Automated bulk import system for loading processed sales data into MySQL

  • Visualizations: Automated chart generation for weekly sales trends and store performance analysis

Key Features:

  • Multi-stage ETL pipeline (convert → filter → fix → reformat → import)

  • Handles 100+ CSV files per year per store

  • Data validation and cleaning for malformed files

  • Automated visualization generation

stock_checker/

Real-Time Inventory Monitoring Service

A standalone service that checks OUT_OF_STOCK items for each store via the Toast API and updates a MySQL database. Can be deployed as a Cloud Run Job for scheduled execution.

Key Features:

  • Automated hourly stock status checks across 10+ restaurant locations

  • Toast API integration with OAuth2 authentication

  • MySQL database updates with complete history tracking

  • Configurable item filtering and store code mapping

  • Cloud Run deployment with Cloud Scheduler integration

Technologies: Python, FastAPI, MySQL, Google Cloud Run

report/

Full-Stack Reporting Dashboard

A comprehensive reporting dashboard with multiple microservices for visualizing and analyzing restaurant operations data.

Components:

  • backend/: Node.js/Express REST API server

    • RESTful API with 15+ endpoints

    • JWT-based authentication with role-based access control

    • MySQL database integration with connection pooling

    • Real-time stock status, analytics, and performance metrics

  • frontend/: React application

    • Real-time dashboard with data visualization

    • Recharts for trend analysis and charts

    • User authentication and role-based UI

    • Responsive design

  • daily_sales/: Daily Sales Data Collection Service

    • Automated daily sales data collection from Toast API

    • Separates catering vs non-catering orders

    • Stores aggregated results in MySQL

    • Scheduled execution via Cloud Scheduler

  • eod-email/: End of Day Email Reports

    • Automated daily email reports with HTML formatting

    • Time window stock status analysis (20 time windows per day)

    • Multi-store support in single email

    • Amazon SES integration

Technologies: React, Node.js/Express, Python, MySQL, Docker, Google Cloud Run

terraform/

Infrastructure as Code

Terraform configuration for provisioning and managing Google Cloud Platform infrastructure.

Key Features:

  • GCP VM instance provisioning for MySQL database

  • Firewall rule configuration for network security

  • Cloud Run Job deployment automation

  • Network tags and security group management

  • Output management for infrastructure details

Technologies: Terraform, Google Cloud Platform

ansible/

Configuration Management

Ansible playbooks for automated MySQL configuration and database setup on GCP VMs.

Key Features:

  • Automated MySQL installation and configuration

  • Database and table creation

  • User management and permissions

  • Security hardening

  • Idempotent playbooks for safe re-runs

Technologies: Ansible, MySQL

docs/

Technical Documentation System

A comprehensive Sphinx-based documentation system for the Toast Operations API with OpenAPI integration and CI/CD automation support.

Key Features:

  • Sphinx documentation framework with Read the Docs theme

  • OpenAPI integration for automatic API reference generation

  • Multi-section documentation (project overview, getting started, GitHub setup, API examples, annual sales)

  • Cross-platform build automation (Makefile, make.bat)

  • Local preview scripts for documentation testing

  • CI/CD ready architecture for GitHub Actions automation

Documentation Sections:

  • Project Overview: High-level architecture and system overview

  • Getting Started: Setup and installation instructions

  • GitHub Setup: Repository setup and development workflow

  • API Reference: Auto-generated from OpenAPI specifications

  • Toast API Examples: Integration examples and use cases

  • Annual Sales: Sales data documentation

Technologies: Sphinx, reStructuredText (RST), Python, OpenAPI, GitHub Actions (planned), Firebase Hosting

tmp/

Documentation & Setup Scripts

Various setup, deployment, and documentation files including:

  • Database setup and migration scripts

  • Deployment guides and troubleshooting documentation

  • Environment variable configuration examples

  • Local development setup instructions

  • Production deployment walkthroughs

Architecture

┌─────────────────┐
│  Toast POS API  │
└────────┬────────┘
         │
         ├─────────────────┐
         │                 │
    ┌────▼────┐      ┌─────▼─────┐
    │ Stock   │      │  Daily    │
    │ Checker │      │  Sales    │
    └────┬────┘      └─────┬─────┘
         │                 │
         └────────┬────────┘
                  │
         ┌────────▼────────┐
         │   MySQL DB      │
         │  (GCP VM)       │
         └────────┬────────┘
                  │
         ┌────────▼────────┐
         │  Report API     │
         │  (Node.js)      │
         └────────┬────────┘
                  │
         ┌────────▼────────┐
         │ React Frontend  │
         └─────────────────┘

Key Technologies

  • Frontend: React, Recharts, CSS

  • Backend: Node.js, Express, Python, FastAPI, Firebase

  • Database: MySQL

  • Cloud: Google Cloud Platform (Cloud Run, Cloud Scheduler, Compute Engine)

  • Infrastructure: Terraform, Ansible, Docker

  • Documentation: Sphinx, reStructuredText, OpenAPI

  • APIs: Toast POS API, Amazon SES

Features

  • ✅ Real-time inventory monitoring across 10+ restaurant locations

  • ✅ Automated daily sales data collection with catering/non-catering separation

  • ✅ Full-stack dashboard with analytics and visualization

  • ✅ Automated end-of-day email reports

  • ✅ Infrastructure as Code with Terraform and Ansible

  • ✅ Cloud-native deployment on Google Cloud Platform

  • ✅ JWT-based authentication with role-based access control

  • ✅ Comprehensive data processing and ETL pipelines

  • ✅ Professional technical documentation with Sphinx and OpenAPI integration