245 lines
5.9 KiB
Markdown
245 lines
5.9 KiB
Markdown
# 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
|
|
|
|
```sh
|
|
cd backend
|
|
docker compose -f docker-compose.dev.yml up -d
|
|
```
|
|
|
|
### 2. Configure the backend
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
cd desktop
|
|
cp connectionpetstore.properties.example connectionpetstore.properties
|
|
mvn javafx:run
|
|
```
|
|
|
|
### 6. Run the Android app
|
|
|
|
Open `android/` in Android Studio and run on an emulator or device.
|
|
|
|
## Switching Between Azure and Local Backend
|
|
|
|
Each client reads the backend URL from a config file. To point a client at the
|
|
hosted Azure backend versus a local one, flip the commented lines.
|
|
|
|
### Web
|
|
|
|
Edit `web/.env.local`:
|
|
|
|
```
|
|
# Local
|
|
BACKEND_URL=http://localhost:8080
|
|
#BACKEND_URL=https://petshop-backend.nicepond-c7280126.westus2.azurecontainerapps.io
|
|
|
|
# Azure
|
|
#BACKEND_URL=http://localhost:8080
|
|
BACKEND_URL=https://petshop-backend.nicepond-c7280126.westus2.azurecontainerapps.io
|
|
```
|
|
|
|
Restart the dev server after changing.
|
|
|
|
### Desktop
|
|
|
|
Edit `desktop/src/main/resources/connectionpetstore.properties`:
|
|
|
|
```
|
|
# Local
|
|
api.baseUrl=http://localhost:8080
|
|
#api.baseUrl=https://petshop-backend.nicepond-c7280126.westus2.azurecontainerapps.io
|
|
|
|
# Azure
|
|
#api.baseUrl=http://localhost:8080
|
|
api.baseUrl=https://petshop-backend.nicepond-c7280126.westus2.azurecontainerapps.io
|
|
```
|
|
|
|
### Android
|
|
|
|
Edit `android/local.properties`:
|
|
|
|
```properties
|
|
# Local (emulator — 10.0.2.2 maps to host's localhost)
|
|
petstore.backend.emulatorUrl=http\://10.0.2.2\:8080/
|
|
petstore.backend.deviceUrl=http\://192.168.x.x\:8080/
|
|
|
|
# Azure
|
|
petstore.backend.emulatorUrl=https\://petshop-backend.nicepond-c7280126.westus2.azurecontainerapps.io/
|
|
petstore.backend.deviceUrl=https\://petshop-backend.nicepond-c7280126.westus2.azurecontainerapps.io/
|
|
```
|
|
|
|
Sync Gradle and re-run the app.
|
|
|
|
## 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)
|
|
|
|
```sh
|
|
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+.
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
npm run build
|
|
npm run start
|
|
```
|
|
|
|
## Running the Desktop App (JavaFX)
|
|
|
|
Requires IntelliJ IDEA and Java 25+.
|
|
|
|
1. Open the `desktop/` directory in IntelliJ.
|
|
2. 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
|
|
```
|
|
|
|
3. Open **View > Tool Windows > Maven** and click **Reload All Maven Projects**.
|
|
4. 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).
|
|
|
|
1. Copy `local.properties.template` to `local.properties` and set `sdk.dir` to your Android SDK path.
|
|
2. Configure the backend URLs in `local.properties`:
|
|
|
|
```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/
|
|
```
|
|
|
|
3. Open the `android/` directory in Android Studio.
|
|
4. Sync Gradle, then run on an emulator or connected device.
|
|
|
|
## Running the Backend
|
|
|
|
Requires IntelliJ IDEA and Java 25+.
|
|
|
|
1. Open the `backend/` directory in IntelliJ.
|
|
2. Copy `.env.example` to `.env` and fill in your API keys.
|
|
3. Start the database using Docker from IntelliJ's **Services** panel, or from a terminal:
|
|
|
|
```sh
|
|
cd backend
|
|
docker compose -f docker-compose.dev.yml up -d
|
|
```
|
|
|
|
4. Run the `BackendApplication` main class from IntelliJ.
|
|
|
|
The API starts at `http://localhost:8080`. Flyway runs migrations and seeds data automatically on first boot.
|