SpiceRack

A full-stack grocery and meal planning application built with React and Spring Boot. SpiceRack helps users manage their grocery inventory, create recipes, plan meals, and streamline their shopping experience.

Table of Contents

• Features
• Tech Stack
• Project Structure
• Prerequisites
• Installation
  • Backend Setup
  • Frontend Setup
• Configuration
• Running the Application
• API Endpoints
• Deployment
• Performance Optimizations
• License

Features

• User Authentication: Secure login and registration system
• Inventory Management: Track and manage grocery items in your pantry
• Recipe Management: Create, view, and manage personal recipes
• Meal Planning: Plan meals with an interactive meal plan calendar
• Shopping Cart: Add items to cart and manage purchases
• Order History: View past orders and track purchases
• Grocery Upload: Bulk upload grocery items
• Responsive Design: Works seamlessly across desktop and mobile devices

Tech Stack

Frontend

• React 19.2
• React Router DOM 7.10
• Axios for HTTP requests
• Lucide React and React Icons for UI components
• CSS Modules for styling

Backend

• Java 17
• Spring Boot 3.4.3
• Spring Data JPA
• Spring WebFlux
• MySQL 8.0 (Production)
• H2 Database (Development)
• HikariCP Connection Pool
• Lombok
• Maven

DevOps

• Docker
• Multi-stage Docker builds

Project Structure

spicerack/
├── reactapp/                 # React frontend application
│   ├── public/              # Static assets
│   ├── src/
│   │   ├── context/         # React context providers
│   │   ├── css/             # Component stylesheets
│   │   ├── images/          # Image assets
│   │   └── pages/           # React page components
│   └── build/               # Production build output
│
├── springapp/               # Spring Boot backend application
│   ├── src/
│   │   └── main/
│   │       ├── java/com/example/springapp/
│   │       │   ├── config/       # Application configuration
│   │       │   ├── controller/   # REST API controllers
│   │       │   ├── dto/          # Data Transfer Objects
│   │       │   ├── entities/     # JPA entities
│   │       │   ├── repositories/ # Data repositories
│   │       │   └── services/     # Business logic services
│   │       └── resources/
│   │           └── application.properties
│   └── Dockerfile
│
├── logs/                    # Application logs
├── OPTIMIZATION_GUIDE.md    # Performance optimization documentation
└── README.md

Prerequisites

• Node.js 18.x or higher
• npm 9.x or higher
• Java 17 or higher
• Maven 3.8.x or higher
• MySQL 8.0 (for production)
• Docker (optional, for containerized deployment)

Installation

Backend Setup

1. Navigate to the Spring Boot application directory:

   cd springapp

2. Install dependencies and build the project:

   mvn clean install

3. Configure the database connection (see Configuration section)

Frontend Setup

1. Navigate to the React application directory:

   cd reactapp

2. Install dependencies:

   npm install

Configuration

Backend Configuration

Create environment variables or update springapp/src/main/resources/application.properties:

Variable	Description	Default
PORT	Server port	8080
DB_URL	MySQL connection URL	-
DB_USERNAME	Database username	-
DB_PASSWORD	Database password	-

Example environment variables:

export DB_URL=jdbc:mysql://localhost:3306/spicerack
export DB_USERNAME=your_username
export DB_PASSWORD=your_password

Frontend Configuration

The React application connects to the backend API. Update the API base URL in the Axios configuration if needed.

Running the Application

Development Mode

Backend:

cd springapp
mvn spring-boot:run

The backend server will start on http://localhost:8080

Frontend:

cd reactapp
npm start

The frontend development server will start on http://localhost:3000

Production Build

Frontend:

cd reactapp
npm run build

Backend:

cd springapp
mvn clean package -DskipTests
java -jar target/spicerack-0.0.1-SNAPSHOT.jar

API Endpoints

Authentication

• POST /api/auth/login - User login
• POST /api/auth/register - User registration

User Management

• GET /api/users/{id} - Get user details
• PUT /api/users/{id} - Update user details

Grocery Management

• GET /api/groceries - List all groceries
• POST /api/groceries - Add new grocery item
• PUT /api/groceries/{id} - Update grocery item
• DELETE /api/groceries/{id} - Delete grocery item

Inventory

• GET /api/inventory/{userId} - Get user inventory
• POST /api/inventory - Add item to inventory
• PUT /api/inventory/{id} - Update inventory item
• DELETE /api/inventory/{id} - Remove from inventory

Cart

• GET /api/cart/{userId} - Get user cart
• POST /api/cart - Add item to cart
• DELETE /api/cart/{id} - Remove from cart

Orders

• GET /api/orders/{userId} - Get user orders
• POST /api/orders - Create new order

Recipes

• GET /api/recipes - List all recipes
• GET /api/recipes/user/{userId} - Get user recipes
• POST /api/recipes - Create new recipe
• PUT /api/recipes/{id} - Update recipe
• DELETE /api/recipes/{id} - Delete recipe

Meal Plans

• GET /api/mealplan/{userId} - Get user meal plan
• POST /api/mealplan - Create/update meal plan

Deployment

Docker Deployment

Build and run using Docker:

cd springapp
docker build -t spicerack-backend .
docker run -p 8080:8080 \
  -e DB_URL=your_db_url \
  -e DB_USERNAME=your_username \
  -e DB_PASSWORD=your_password \
  spicerack-backend

Cloud Deployment

The application is optimized for deployment on cloud platforms like Render, AWS, or Heroku. The backend includes HikariCP connection pool optimizations for cross-region database connections.

Performance Optimizations

This application includes several performance optimizations for handling high-latency cross-region database connections:

• JOIN FETCH Pattern: Reduces N+1 query problems to single queries
• DTO Pattern: Lightweight data transfer objects minimize payload size
• HikariCP Tuning: Connection pool optimized for high-latency environments
• Hibernate Batching: Batch operations for improved database performance
• Optimistic UI Updates: Frontend updates immediately while syncing with backend

For detailed optimization documentation, see OPTIMIZATION_GUIDE.md.

Testing

Backend Tests

cd springapp
mvn test

Frontend Tests

cd reactapp
npm test

License

This project is licensed under the MIT License.