RecentRunner/group-2-threaded-project-petshop

Files

Harkamal Randhawa ebb9b77025 add client run instructions

2026-04-19 19:04:13 -06:00

4.6 KiB

Raw Blame History

PetShop

A pet store management application with a Spring Boot API serving three clients: a Next.js web app, a JavaFX desktop app, and an Android app.

Handles product sales, pet adoption, appointment booking, real-time chat, AI assistance, payments (Stripe), email notifications (Resend), and file storage (Azure Blob).

Tech Stack

Layer	Technology
API	Java 25, Spring Boot 4, Spring Security (JWT), Hibernate
Database	MySQL 8.0, Flyway migrations
Web	Next.js 16, React 19, Tailwind CSS 4
Desktop	JavaFX, Maven
Android	Kotlin, Hilt, Retrofit, CameraX
Infra	Docker, Azure Container Apps

Project Structure

main/
  backend/      Spring Boot REST API
  web/          Next.js frontend
  desktop/      JavaFX desktop client
  android/      Android mobile app

Prerequisites

Java 25
Node.js 18+
Docker
Maven
Android Studio (for mobile)

Getting Started

1. Start the database

cd backend
docker compose -f docker-compose.dev.yml up -d

2. Configure the backend

cd backend
cp .env.example .env

Fill in .env with your keys:

JWT_SECRET=<openssl rand -base64 32>
STRIPE_SECRET_KEY=sk_test_...
OPENROUTER_API_KEY=sk-or-v1-...
RESEND_API_KEY=re_...
RESEND_FROM=PetShop <no-reply@yourdomain.com>

3. Run the backend

cd backend
mvn spring-boot:run

The API starts at http://localhost:8080. Flyway runs migrations and seeds data automatically on first boot.

4. Run the web frontend

cd web
cp .env.example .env.local
npm install
npm run dev

The web app starts at http://localhost:3000.

5. Run the desktop client (optional)

cd desktop
cp connectionpetstore.properties.example connectionpetstore.properties
mvn javafx:run

6. Run the Android app (optional)

Open android/ in Android Studio and run on an emulator or device.

API

A Postman collection is available at backend/postman/. Key endpoint groups:

/api/auth -- registration, login, password reset
/api/products -- catalog and inventory
/api/pets -- listings and adoption
/api/appointments -- booking
/api/cart, /api/sales, /api/refunds -- transactions
/api/chat -- messaging and AI assistant
/ws -- WebSocket (STOMP) for real-time updates

Docker (full stack)

cd backend
docker compose up --build -d

Starts the API and MySQL together. The web frontend has its own Dockerfile for independent deployment.

Running the Web App

Requires Node.js 18+.

cd web
cp .env.example .env.local
npm install
npm run dev

Open http://localhost:3000. The app proxies API calls to the backend at http://localhost:8080 by default.

To point at a different backend, edit BACKEND_URL and NEXT_PUBLIC_BACKEND_URL in .env.local.

For a production build:

npm run build
npm run start

Running the Desktop App (JavaFX)

Requires IntelliJ IDEA and Java 25+.

Open the desktop/ directory in IntelliJ.
Copy connectionpetstore.properties.example to connectionpetstore.properties and edit it to match your database. The defaults expect the dev Docker database:

url=jdbc:mysql://127.0.0.1:3306/Petstoredb?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
user=petshop
password=petshop

Open View > Tool Windows > Maven and click Reload All Maven Projects.
Expand Plugins > javafx and double-click javafx:run.

Default accounts seeded on first run:

Role	Username	Password
Admin	`admin`	`admin123`
Staff	`staff`	`staff123`

Running the Android App

Requires Android Studio and the Android SDK (min API 24).

Copy local.properties.template to local.properties and set sdk.dir to your Android SDK path.
Configure the backend URLs in local.properties:

# Emulator — 10.0.2.2 maps to the host machine's localhost
petstore.backend.emulatorUrl=http\://10.0.2.2\:8080/

# Physical device — use the host machine's LAN IP
petstore.backend.deviceUrl=http\://192.168.x.x\:8080/

Open the android/ directory in Android Studio.
Sync Gradle, then run on an emulator or connected device.

Running the Backend