📸 PhotoClassifier — AI-Powered Photo Management Backend

A Spring Boot backend for intelligent photo management, enabling users to upload images into shared rooms, automatically index them as vector embeddings, and perform semantic face search — finding all photos containing a specific person using vector similarity.

⚠️ This project depends on a companion Python ML microservice for face detection and embedding generation. 👉 facedetection_microservice — must be running locally (default: http://localhost:8000) before starting this service.

---

🏗️ Architecture Overview

Client
  │
  ▼
Spring Boot API  (this repo)
  ├── Cloudinary          → stores uploaded images
  ├── PostgreSQL          → persists user & room metadata
  ├── Pinecone            → stores & queries face vector embeddings
  └── Python Microservice → face detection & embedding generation
        └── 👉 https://github.com/coder2505/facedetection_microservice

---

✨ Features

• Multi-file image upload — Upload multiple photos at once into a room-scoped folder on Cloudinary
• Auto embedding pipeline — On every upload, the image is sent to the Python microservice to generate a vector embedding, which is then stored in Pinecone
• Semantic face search — Upload a face photo and find all matching images using nearest-neighbor vector search (≥ 50% similarity threshold)
• Room & user management — Create users and rooms; each room maintains its own isolated photo collection
• Async parallel processing — Multi-file uploads are processed concurrently using @Async + CompletableFuture
• OpenAPI / Swagger UI — Auto-generated interactive API docs via springdoc

---

🛠️ Tech Stack

Layer	Technology
Framework	Spring Boot 4 (Java 21)
Image Storage	Cloudinary
Vector Database	Pinecone
Relational DB	PostgreSQL + Spring Data JPA
Reactive HTTP	Spring WebFlux (WebClient)
ML Microservice	Python (separate repo — see below)
API Docs	springdoc OpenAPI / Swagger

---

🐍 Python ML Microservice

This service will not function without the microservice running.

The face detection and embedding logic lives in a separate Python service:

👉 https://github.com/coder2505/facedetection_microservice

It exposes the following endpoints consumed by this backend:

Endpoint	Method	Description
/has-faces	GET	Checks if an image URL contains faces
/embedding	POST	Returns a vector embedding for an image URL
/bytesToEmbedding	POST	Returns a vector embedding from raw image bytes

Run it on http://localhost:8000 before starting the Spring Boot app.

---

🚀 Getting Started

Prerequisites

• Java 21+
• Maven
• PostgreSQL instance
• Cloudinary account
• Pinecone account (index named first)
• Python microservice running on port 8000 → facedetection_microservice

1. Clone the repo

git clone https://github.com/coder2505/PhotoClassifierSpring.git
cd PhotoClassifierSpring

2. Configure environment variables

Copy the example env file and fill in your credentials:

cp env.example .env

CLOUDINARY_URL=
CLOUD_NAME=
API_KEY=
API_SECRET=

POSTGRES_URL=
POSTGRES_USERNAME=
POSTGRES_PASSWORD=

PINECONE_API_KEY=

3. Start the Python microservice

Follow the setup instructions at: 👉 https://github.com/coder2505/facedetection_microservice

Ensure it is running on http://localhost:8000.

4. Run the Spring Boot app

./mvnw spring-boot:run

The API will be available at http://localhost:8080. Swagger UI at http://localhost:8080/swagger-ui/index.html.

---

📡 API Endpoints

Images — /api/images

Method	Endpoint	Description
POST	/upload/{room_id}	Upload multiple images to a room; triggers embedding & Pinecone indexing
POST	/findFaces	Upload a face photo to find all matching images via vector search
POST	/userPhoto/{user_id}/{room_id}	Upload a profile photo for a user in a room

Create — /api/create

Method	Endpoint	Description
POST	/user/{username}	Create a new user
POST	/room/{admin_id}	Create a new room (creator is added as admin)

---

📁 Project Structure

src/main/java/com/example/demo/
├── configuration/
│   ├── CloudinaryConfig.java            # Cloudinary bean setup
│   ├── PineConeConfig.java              # Pinecone client & index bean
│   └── PythonMicroservice.java          # WebClient pointing to Python service
├── controllers/
│   ├── ImagesUpload.java                # Image upload & face search endpoints
│   └── CreateControllers.java           # User & room creation endpoints
├── service/
│   ├── CloudinaryServices.java          # Async upload to Cloudinary
│   ├── PhotoFaceService.java            # Orchestrates embedding + Pinecone save
│   ├── ImageVectorEmbedding.java        # Calls Python /embedding endpoint
│   ├── UploadToPythonMicroservice.java  # Calls Python /bytesToEmbedding
│   ├── SaveToPinecone.java              # Upserts vectors into Pinecone
│   └── QueryVectorService.java          # Queries Pinecone for similar vectors
├── entities/
│   └── postgres_tables/
│       ├── UserEntity.java
│       ├── RoomEntity.java
│       ├── RoomMember.java
│       └── RoomMemberKey.java
└── repository/
    ├── UserRepository.java
    ├── RoomRepository.java
    └── RoomMemberRepository.java

---

📄 License

MIT