Github

Warning

Once you have access to the github repository, you can follow the steps below to get started. If you don’t have access, refer to Getting Started to request access.

Open a terminal and navigate to where you want to clone the repository.

cd ~/Documents/Projects ## or any location you prefer
git clone https://github.com/chavezMac/toast.git

Note

Github will have you sign in with your Github account and enter your token to access the repository. There are tutorials online on how to create a token if you are not familiar with the process.

Once you have the repository cloned, you should see the following directories:

toast/
    - annual_sales/
    - stock_checker/
    - report/
    - terraform/
    - ansible/

Create your own branch to work on your changes. This will allow you to make changes to the code without affecting the main branch as all changes are merged into the main branch via pull requests.

git checkout -b your-name-branch
#Make your changes, then commit them
git add .
git status
git commit -m "Your commit message"

git push -u origin your-name-branch

Now you can create a pull request to merge your changes into the main branch. This will allow you to review your changes and the repo admin will merge them into the main branch if they are approved.

Terraform & Ansible

Warning

Only run this if you are setting up the infrastructure for the first time or for your own personal project.

See Documentation link below for detailed instructions.

Stock Checker

Microservice for checking “out of stock” items for each store via the Toast API and updating a MySQL database. Deployed as a Cloud Run Job that runs on a pre-determined schedule.

Configuration: Required environment variables:

Environment Variable(s)

Description

CLIENT_ID

Toast API client ID

CLIENT_SECRET

Toast API client secret

TOAST_ACCESS_TOKEN

Toast API access token. Generated in a function call(Requires: Client_ID and Client_Secret)

DB_HOST

GCP VM IP address or hostname where MySQL is running

DB_PORT

Database port (default: 3306 for MySQL)

DB_NAME

Database name

DB_USER

Database user

DB_PASSWORD

Database password

TOAST_RESTAURANT_IDS

Comma-separated or individual line item environment variables for each store.(Retrieved from Toast Integrations Settings)

STORE_CODE_MAPPING

Comma-separated store name to code mappings (Reach out to project owner to get the mapping for your store)

TRACKED_ITEM_GUIDS

Comma-separated list of tracked item GUIDs

Local Development:

##1.) Install Dependencies
cd stock_checker
pip install -r requirements.txt
python app.py

##2.) Set Environment Variables
cp stock_checker/env.example ../.env
# Then edit .env with your actual values
vi .env

##3.) Run the Service
uvicorn app:app --reload --port 8080
# Or
python app.py

##Test the Service
curl http://localhost:8080/health
curl -X POST http://localhost:8080/check

Deploy to Cloud Run using the deployment script:

# Make sure to set JOB_NAME in the .env file
# JOB_NAME=stock-checker-job
cd stock_checker
chmod +x deploy_job.sh
./deploy_job.sh

Manually run the service:

gcloud run jobs execute stock-checker-job --region us-central1

Schedule the Service for regular checks using Cloud Scheduler. See the README file for detailed instructions for CLI commands. Or visit Cloud Run Jobs page in the Google Cloud Console and edit the “Trigger” to run the service on a regular schedule.

Report

report/
├── backend/          # Node.js/Express API server
├── frontend/         # React application
├── README.md         # This file
└── .gitignore        # Git ignore rules

BackendAPI Reference: API Reference

Prerequisites:

  • Node.js 18+ and npm

  • MySQL database (already set up on your GCP VM)

  • Access to the MySQL database

Backend Environment Variables:

Environment Variable(s)

Description

DB_HOST

GCP VM IP address or hostname where MySQL is running

DB_PORT

Database port (default: 3306 for MySQL)

DB_NAME

Database name

DB_USER

Database user(Created by admin)

DB_PASSWORD

Database password(Created by admin)

PORT

3001

CORS_ORIGIN

localhost:3000

Frontend Environment Variables:

Environment Variable(s)

Description

REACT_APP_API_URL

localhost:3001

Manual Set Up:

cd report/backend
npm install
# Edit .env with your MySQL credentials
npm start

cd report/frontend
npm install
# Edit .env with your API URL
npm start

Development:

cd report/backend
npm run dev

cd report/frontend
npm start

Annual Sales

Overview:

The annual_sales/ directory stores weekly and yearly sales data CSV files organized by restaurant location and year. These files are used for:

  • Business Intelligence Analysis: Import into BI tools (e.g., Tableau, Power BI, Looker) for yearly sales reporting

  • Historical Reporting: Track sales trends across multiple years

  • Store Performance Analysis: Compare performance across locations

Directory Structure:

annual_sales/
├── {store_name}/          # One directory per restaurant location
│   ├── 2024/             # Weekly CSVs and yearly combined CSV
│   └── 2025/             # Weekly CSVs and yearly combined CSV
├── sales_scripts/        # Processing and ETL scripts
└── visualizations/       # Generated charts and reports

Store Locations: Aptos St, BBQ 152, The Barbeque Pit, Canyons BBQ, Crossroads BBQ, Mission St, Redwood City BBQ, Salinas, Trail Dust, Wagon Wheel, South Winchester

Note

Annual Sales is excluded from version control (gitignored) due to the large volume of sales data files. Data is stored locally or in secure storage.

Documentation

Each directory contains its own README with detailed setup, configuration, and usage instructions: