Image Processor Service

A lightweight image upload and delivery API built with Spring Boot.

This service was created to centralize image handling for future projects. It provides a simple flow for uploading user profile pictures, processing them, storing them in a RustFS bucket, and retrieving them later through a download endpoint.

Tech Stack

• Spring Boot — API framework
• RustFS — S3-compatible object storage
• ImageKit — image processing and optimization
• PostgreSQL — metadata storage

---

How it works

The service exposes two main endpoints:

• POST /api/v1/upload/profile-picture?username={username}
• GET /api/v1/download/profile-picture/{username}

---

Upload flow

When a client uploads a profile picture:

1. The API receives the file and the username
2. The image is read from the multipart request
3. A unique filename is generated using a UUID
4. The image is processed (resize, crop, face focus, etc.)
5. The processed image is stored in RustFS
6. The database is updated with the storage key
7. A download URL is returned

If a profile picture already exists, the old image is deleted before saving the new one.

---

Download flow

When a client requests a profile picture:

1. The API looks up the username in the database
2. Retrieves the storage key
3. Fetches the image from RustFS
4. Returns the image as image/jpeg

If not found → 404 Not Found

---

API Endpoints

Upload profile picture

POST /api/v1/upload/profile-picture?username={username}

Request

• Content-Type: multipart/form-data
• Query param: username
• Form-data:
  • file → image file

Example

curl -X POST "http://localhost:8088/api/v1/upload/profile-picture?username=john" \
  -F "file=@profile.jpg"

Response

{
  "downloadUrl": "http://localhost:8088/api/v1/download/profile-picture/john",
  "message": "Uploaded successfully"
}

---

Download profile picture

GET /api/v1/download/profile-picture/{username}

Example

curl -L "http://localhost:8088/api/v1/download/profile-picture/john" --output profile.jpg

---

Configuration

The application is configured via environment variables.

RustFS

• RUSTFS_BASE_URL
• RUSTFS_ACCESS_KEY
• RUSTFS_SECRET_KEY
• RUSTFS_BUCKET

ImageKit

• IMAGEKIT_PUBLIC_KEY
• IMAGEKIT_PRIVATE_KEY
• IMAGEKIT_URL_ENDPOINT

Database

• DB_URL
• DB_USERNAME
• DB_PASSWORD

Server

• SERVER_PORT (default: 8088)

---

Running the project

1. Start dependencies (PostgreSQL)

docker compose up -d

2. Run the application

./mvnw spring-boot:run

---

Health Check

GET /api/actuator/health

---

Project structure

features/
 ├── upload/
 │   ├── controller/
 │   ├── service/
 │   └── repository/
 ├── download/
 │   ├── controller/
 │   └── service/
 └── imagekit/
     └── strategy/

---

Database behavior

• Each user has one profile picture
• Upload replaces the previous image
• Old images are automatically deleted from storage

---

Notes

Package name was changed from:

ao.vanadio.image-processor-service

to:

ao.vanadio.image_processor_service

due to Java naming constraints.

---

Purpose

This service is designed to be reusable across multiple projects, providing a clean and scalable way to handle image uploads and delivery.