.. _github: 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 :ref:`getting-started` to request access. Open a terminal and navigate to where you want to clone the repository. .. code-block:: bash 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: .. code-block:: bash 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. .. code-block:: bash 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: .. list-table:: :widths: 50 50 :header-rows: 1 * - 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: .. code-block:: bash ##1.) Install Dependencies cd stock_checker pip install -r requirements.txt python app.py .. code-block:: bash ##2.) Set Environment Variables cp stock_checker/env.example ../.env # Then edit .env with your actual values vi .env .. code-block:: bash ##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: .. code-block:: bash # 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: .. code-block:: bash 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 ------ .. code-block:: text report/ ├── backend/ # Node.js/Express API server ├── frontend/ # React application ├── README.md # This file └── .gitignore # Git ignore rules **BackendAPI Reference:** :ref:`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:** .. list-table:: :widths: 50 50 :header-rows: 1 * - 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:** .. list-table:: :widths: 50 50 :header-rows: 1 * - Environment Variable(s) - Description * - **REACT_APP_API_URL** - localhost:3001 **Manual Set Up:** .. code-block:: bash cd report/backend npm install # Edit .env with your MySQL credentials npm start .. code-block:: bash cd report/frontend npm install # Edit .env with your API URL npm start **Development:** .. code-block:: bash cd report/backend npm run dev .. code-block:: bash 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:** .. code-block:: text 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: - `terraform/README.md `_ - Infrastructure setup - `ansible/README.md `_ - Database configuration - `stock_checker/README.md `_ - Inventory monitoring service - `report/README.md `_ - Reporting dashboard,Backend API server,Frontend application - `report/daily_sales/README.md `_ - Daily sales service - `report/eod-email/README.md `_ - Email reporting service