🚀 Delivery App

A monolithic delivery platform built with Spring Boot.

🛠️ Tech Stack

Layer	Technology
Backend	Spring Boot 3.5, Java 21
Frontend	Nuxt 4, Vue 3, TypeScript
Database	PostgreSQL 17
Cache	Redis 7
Messaging	RabbitMQ 3.13
Auth	JWT + Google OAuth2
Real-time	WebSocket (STOMP)
Maps	Mapbox
Push notif	Firebase (FCM)

---

💡 Engineering Challenges

The questions I explored and the lessons I learned while building this project.

• How can map API costs be reduced in a delivery platform?

  • Caching routes, minimizing external API calls, and using efficient location update strategies.

• What challenges arise when finding nearby couriers for a new delivery request?

  • Efficient geospatial search, online/offline detection, progressive search radius, and preventing duplicate notifications.

• Should pricing be a simple calculation or a business-driven pricing engine?

  • Dynamic pricing based on distance, delivery zones, demand, weather conditions, courier availability, and business rules.

• How can RabbitMQ and Redis work together effectively?

  • Combining asynchronous messaging with fast in-memory data for reliable event processing, real-time matching, and distributed coordination.

• What should be prioritized when integrating bank APIs and accounting systems?

  • Transaction consistency, idempotency, audit logs, reconciliation, and financial reporting.

• Which parts of a monolithic application become bottlenecks under heavy traffic?

  • Database contention, synchronous communication, external API latency, WebSocket scalability, message processing, and background jobs.

• How is authorization implemented in Spring Boot WebSocket (STOMP)?

  • Authenticating WebSocket connections with JWT, securing STOMP destinations, and enforcing role-based access control for subscriptions and messaging.

---

🏗️ Architecture Diagrams

Before running the application, I recommend reviewing the architecture diagrams to better understand the system design and component interactions.

The diagrams are available at:

delivery-app/diagrams/delivery-app.drawio

Open the file with draw.io (diagrams.net) to explore the complete system architecture.

---

⚡ Quick Start

Prerequisites

• Docker Desktop (v24+)
• Docker Compose (v2.20+)

1. Clone the repository

git clone https://github.com/your-username/delivery-app.git
cd delivery-app

2. Create your .env file

cp .env-example .env

Open .env and fill in the required values:

Variable	Description
GOOGLE_CLIENT_ID	From Google Cloud Console
GOOGLE_CLIENT_SECRET	From Google Cloud Console
MAIL_USERNAME	Your Gmail address
MAIL_PASSWORD	Gmail App Password (requires 2FA)
MAPBOX_SECRET_TOKEN	From Mapbox Account
NUXT_PUBLIC_MAPBOX_TOKEN	Your Mapbox public token

3. Add Firebase Service Account Key

Go to Firebase Console → Project Settings → Service Accounts → Generate new private key

Place the downloaded JSON file at:

api-backend/src/main/resources/firebase/service-account-key.json

4. Start the application

docker compose up --build

Note: The first build takes ~3–5 minutes as Maven and npm dependencies are downloaded and cached.

---

👤 Demo Accounts

When running the application with the dev profile, the following demo users are automatically seeded.

Role	Email	Password
Admin	admin@local.dev	secret12
Courier	courier@local.dev	secret12
User	user@local.dev	secret12

These accounts are intended for local development and testing only.

---

🌐 Services

Service	URL
🖥️ Frontend	http://localhost:3000
⚙️ Backend API	http://localhost:8084/api/v1
💚 Health Check	http://localhost:8084/actuator/health
🐰 RabbitMQ UI	http://localhost:15672 (guest / guest)
🗄️ PostgreSQL	localhost:5432
🔴 Redis	localhost:6379

---

🔧 Useful Commands

# Follow logs for a specific service
docker compose logs -f backend
docker compose logs -f frontend

# Start only infrastructure (for local development)
docker compose up postgres rabbitmq redis -d

# Stop all services (data is preserved)
docker compose down

# Remove everything including volumes (data is lost!)
docker compose down -v --remove-orphans

# Force rebuild and restart
docker compose up --build --force-recreate

---

🏗️ Architecture

docker-compose.yml
├── postgres        (5432)        — Database
├── rabbitmq        (5672, 15672) — Message broker
├── redis           (6379)        — Cache & session store
├── backend         (8084)        — Spring Boot API
└── frontend        (3000)        — Nuxt 3 SSR

Service startup order (dependency chain):

postgres ─┐
rabbitmq  ├──► backend ──► frontend
redis    ─┘

---

⚙️ Local Development (without Docker for app services)

If you want to run only the infrastructure in Docker and the app locally:

# 1. Start infrastructure services
docker compose up postgres rabbitmq redis -d

# 2. Run the backend (Spring Boot)
cd api-backend
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

# 3. Run the frontend (Nuxt)
cd frontend
npm run dev

---

📁 Project Structure

delivery-app/
├── api-backend/          # Spring Boot backend
│   ├── Dockerfile
│   └── src/
├── frontend/             # Nuxt 3 frontend
│   ├── Dockerfile
│   └── app/
├── diagrams/             # Architecture diagrams
├── docker-compose.yml    # Full container configuration
├── .env-example          # Environment variables template
└── README.md

---

📈 Future Improvements

The following improvements are planned but have not yet been implemented:

• Migrate to a microservices architecture with horizontally scalable WebSocket instances and load balancing to support thousands of concurrent couriers and customers.

• Integrate with a real banking API to enable secure wallet top-ups and real payment processing.

• Implement real-time security monitoring by logging suspicious requests and tracking potential threats using Kafka-based event streaming.

• Introduce an AI-powered Support Service to assist customer support agents by analyzing incoming messages, automatically categorizing issues, and providing insights through an analytics dashboard.

• Enhance the pricing engine by incorporating additional business factors such as:

  • Cargo Weight
  • Estimated Delivery Time
  • Demand vs. Supply
  • Courier Density
  • Traffic Conditions
  • Transport Type
  • Zone-Based Pricing
  • Peak Hours

• Introduce ClickHouse and Kafka for analytics to collect and analyze order history, delivery zones, pricing trends, courier activity, cargo statistics, the most active and least active zones, and historical pricing data.

• Redesign the frontend UI/UX to improve usability, accessibility, and the overall user experience.