Lemonade Map

A full-stack web application for managing lemonade stands and their products. This project allows users to create and manage their own lemonade stands, add products, and view other stands on an interactive map.

Table of Contents

• Features
• Live Site
• Technology Stack
• Architecture
• Getting Started
  • Prerequisites
  • Installation
  • Environment Setup
• Supabase Setup
  • Database Schema
  • Row Level Security
  • Setting Up Storage Buckets
• Known Issues and Fixes
  • Stand Deactivation Fix
• Usage
  • User Guide
  • Admin Guide
• Deployment
  • GitHub Pages
  • Custom Domain
• CI/CD Pipeline
• Performance Optimizations
• Testing
• Contributing
• License

Features

• User Authentication

  • Secure signup, login, and password reset
  • Social login options (Google, GitHub)
  • Protected routes for authenticated users

• Lemonade Stand Management

  • Create and manage multiple lemonade stands
  • Upload stand images
  • Set stand location with interactive map
  • Automatic stand expiration after 24 hours (with extension option)

• Product Management

  • Add, update, and remove products for each stand
  • Set product prices, descriptions, and availability
  • Upload product images

• Interactive Map

  • View all active stands on a map
  • Filter stands by proximity
  • Get directions to stands

• Real-time Updates

  • Live updates when data changes
  • Notifications for stand owners

• Responsive Design

  • Works on desktop, tablet, and mobile devices
  • Optimized user experience across all screen sizes

Live Site

Visit the live application: Lemonade Map App

Technology Stack

Frontend

• React 19 - UI library
• React Router 7 - Client-side routing
• Tailwind CSS - Utility-first CSS framework
• Leaflet/React-Leaflet - Interactive maps
• Vite - Build tool and development server

Backend

• Supabase - Backend-as-a-Service platform
  • PostgreSQL database
  • Authentication
  • Storage
  • Real-time subscriptions
  • Edge Functions

Architecture

The application follows a modern architecture pattern with a clear separation of concerns:

Frontend Architecture

The React application is structured as follows:

/lemonade-map
├── public/            # Static assets
├── src/
│   ├── api/           # API functions for Supabase
│   ├── components/    # Reusable UI components
│   ├── contexts/      # React context providers
│   ├── hooks/         # Custom React hooks
│   ├── pages/         # Page components
│   ├── services/      # Service modules
│   ├── styles/        # Global styles
│   ├── utils/         # Utility functions
│   ├── App.js         # Main application component
│   ├── index.js       # Application entry point
│   └── supabaseClient.js # Supabase client configuration

Backend Architecture

The Supabase backend includes:

/supabase
├── migrations/        # Database migration scripts
│   ├── 01_create_users_table.sql
│   ├── 02_create_stands_table.sql
│   ├── 03_create_products_table.sql
│   ├── 04_storage_policies.sql
│   └── 05_stand_expiration.sql
├── functions/         # Edge Functions
│   └── cleanup-expired-stands/
├── seed.sql           # Sample data for development
└── config.toml        # Supabase configuration

Getting Started

Prerequisites

• Node.js (v18 or higher)
• npm (v8 or higher)
• Git
• Supabase account

Installation

1. Clone the repository:

   git clone https://github.com/beaux-riel/Lemonade-map.git
   cd Lemonade-map

2. Install frontend dependencies:

   cd lemonade-map
   npm install

Environment Setup

1. Create a .env file in the lemonade-map directory:

   cp .env.example .env

2. Update the .env file with your Supabase credentials:

   VITE_SUPABASE_URL=https://your-project-id.supabase.co
   VITE_SUPABASE_ANON_KEY=your-anon-key
   

Supabase Setup

Creating a Supabase Project

1. Go to Supabase and sign up or log in
2. Create a new project
3. Give your project a name (e.g., "Lemonade Stand")
4. Set a secure database password
5. Choose a region close to your users
6. Click "Create new project"

Important: After setting up your Supabase project, make sure to create the required storage buckets as described in the Setting Up Storage Buckets section below. This is necessary for image uploads to work correctly.

Database Schema

The database consists of three main tables:

1. Users - Stores user information

   • Linked to Supabase Auth users
   • Stores profile information

2. Stands - Stores lemonade stand information

   • Name, description, location
   • Owner reference
   • Expiration time

3. Products - Stores product information for each stand

   • Name, description, price
   • Availability status
   • Stand reference

Row Level Security

All tables have Row Level Security policies configured to ensure data security:

• Users Table

  • Users can only read and update their own profiles

• Stands Table

  • Everyone can read active stands
  • Stand owners can read, insert, update, and delete their own stands

• Products Table

  • Everyone can read available products from active stands
  • Stand owners can read, insert, update, and delete products for their stands

Setting Up the Database

Option 1: Using the SQL Editor

1. Go to the SQL Editor in the Supabase Dashboard
2. Copy and paste the contents of each migration file in order:
   • 01_create_users_table.sql
   • 02_create_stands_table.sql
   • 03_create_products_table.sql
   • 04_storage_policies.sql
   • 05_stand_expiration.sql
3. Run the SQL commands

Option 2: Using the Supabase CLI

If you have the Supabase CLI installed:

supabase link --project-ref YOUR_PROJECT_REF
supabase db push

Setting Up Storage Buckets

The application requires the following storage buckets to be created in Supabase:

1. stand-images - For storing lemonade stand images
2. product-images - For storing product images
3. user-avatars - For storing user profile pictures

Option 1: Using the Supabase Dashboard

1. Go to the Storage section in the Supabase Dashboard
2. Click "Create a new bucket"
3. Enter the bucket name (e.g., "stand-images")
4. Check "Public bucket" to make the bucket publicly accessible
5. Click "Create bucket"
6. Repeat for the other required buckets

Option 2: Using the Provided Script

1. Get your Supabase URL and service role key from the Supabase Dashboard
2. Run the provided script:

# Set environment variables
export SUPABASE_URL=your-supabase-url
export SUPABASE_SERVICE_KEY=your-service-role-key

# Run the script
node create-buckets-with-service-key.js

For detailed instructions, see STORAGE_BUCKET_SETUP.md.

Usage

User Guide

Creating an Account

1. Visit the application and click "Sign Up"
2. Enter your email and password
3. Verify your email address

Creating a Lemonade Stand

1. Log in to your account
2. Navigate to the Seller Dashboard
3. Click "Create New Stand"
4. Fill in the stand details:
   • Name
   • Description
   • Location (using the map or address search)
   • Upload an image (optional)
5. Click "Create Stand"

Adding Products

1. Navigate to your stand's detail page
2. Click "Add Product"
3. Fill in the product details:
   • Name
   • Description
   • Price
   • Upload an image (optional)
4. Click "Add Product"

Managing Stand Expiration

Stands automatically expire after 24 hours to ensure the map only shows currently active stands.

1. Navigate to your stand's detail page
2. View the expiration countdown
3. Click "Extend" to add 24 hours to your stand's visibility

Admin Guide

For administrative tasks, use the Supabase Dashboard:

1. Log in to your Supabase account
2. Select your project
3. Use the following sections:
   • Authentication - Manage users
   • Table Editor - View and edit database records
   • Storage - Manage uploaded files
   • Edge Functions - Monitor and deploy serverless functions

Known Issues and Fixes

This section documents known issues and their fixes.

Stand Deactivation Error

Issue: Users were experiencing a "stack depth limit exceeded" error when attempting to deactivate a stand.

Fix: We've updated the database triggers to prevent recursive calls when deactivating stands. See Stand Deactivation Fix for details.

Deployment

GitHub Pages

The application is configured for deployment to GitHub Pages:

1. Update the homepage field in package.json with your GitHub Pages URL
2. Deploy using the provided script:

   npm run deploy

This will:

• Build the application
• Push the built files to the gh-pages branch
• Make the application available at your GitHub Pages URL

Custom Domain

To use a custom domain with GitHub Pages:

1. Update the CNAME file in the public directory with your domain name
2. Configure your domain's DNS settings as described in GITHUB_PAGES_SETUP.md
3. Update the homepage field in package.json with your custom domain

CI/CD Pipeline

The project includes a CI/CD pipeline using GitHub Actions:

Pull Request Workflow

• Runs on every pull request to the main branch
• Runs tests and verifies the build
• Provides feedback on the pull request

Deployment Workflow

• Runs on pushes to the main branch
• Builds and deploys the application to GitHub Pages

For detailed information, see CI_CD_SETUP.md.

Performance Optimizations

The application includes several performance optimizations:

• Code Splitting - Lazy loading of components and routes
• Bundle Optimization - Vendor chunk splitting
• Image Optimization - Responsive images and lazy loading
• Caching - Effective use of browser caching
• Compression - Gzip and Brotli compression

For detailed information, see PERFORMANCE_OPTIMIZATIONS.md.

Testing

The project includes a comprehensive testing suite:

• Unit Tests - Testing individual components and functions
• Integration Tests - Testing component interactions
• End-to-End Tests - Testing complete user flows

Run tests with:

cd lemonade-map
npm test

For detailed information, see TESTING.md.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.