The Enterprise Architecture of Local Charity: Unpacking hgayan7/PickItUp

How a solo developer used Spring Boot, Redis caching, and strict statelessness to build a highly decoupled volunteer logistics engine.

6 min read • View on GitHub • More from hgayan7

An illustration of an architectural blueprint on a clipboard next to a lantern. — A meticulously drafted blueprint for a logistics engine, built quietly in the open.

Key Takeaways

PickItUp implements a production-ready, highly normalized logistics engine using Spring Boot, MySQL, and Redis.
The system solves the routing problem using a Strategy pattern and Fan-out notifications to push tasks to volunteers.
Redis caching is used strategically to handle geographic reads, bypassing MySQL for common user queries.
A polymorphic approach to managing physical addresses ensures data integrity across different entity types.

The Anti-Hype Masterclass

While the developer world obsesses over AI agents and Rust rewrites, a quiet Java project implements a masterclass in enterprise-grade backend architecture. PickItUp is a logistics-oriented social good platform designed to bridge the gap between charitable donors and organizations through a coordinated volunteer-driven pickup service.

The surprise isn't what it does, but how it's built. Instead of a messy prototype, the codebase reveals a flawlessly layered Spring Boot architecture (Controller-Service-Repository). It is a textbook blueprint for how to build a modern API using "boring" technology to solve real-world problems.

The Fan-Out Engine: Pushing the Logistics

The most critical business logic resides in the PickupService.createPickup method. When a donor requests a pickup, the system doesn't just save a record; it triggers a "fan-out" notification.

Instead of volunteers constantly polling the server for new tasks, the system proactively pushes Notification entities into the database for every volunteer the moment a request is created. This shifts the computational burden from 'Read' to 'Write'.

The fan-out strategy shifts the computational burden from reads to writes.

The implementation relies on a Strategy-like pattern via the VolunteerPicker interface. The fanOutNotification method takes a VolunteerPicker, allowing the system to swap logic—from notifying all volunteers to notifying only the closest ones—without changing the core service code.

Caching the Physical World

Event discovery is a read-heavy operation. To optimize performance, the developer prioritized caching geographic data.

An illustration of a filing cabinet drawer containing miniature cityscapes separated by index cards. — Caching event lists by city ID bypasses the primary database for the most common user queries.

The EventService uses @Cacheable with custom keys (e.g., events_city). By caching event lists by cityId in Redis, the system reduces MySQL load for the most common user action: browsing local charity events.

Decoupling Geography

The project uses a normalized geographic schema (Country -> State -> City). To prevent data anomalies, the system employs an AddressUpdate interface.

This polymorphic approach means that Users, Events, and Organizations all handle location updates through a unified contract, despite having different underlying tables. This ensures high data quality, preventing a city from accidentally belonging to the wrong state.

The Verdict: A Blueprint for Backend Builders

PickItUp is a "Functional Prototype" with a complete end-to-end flow. While it lacks a frontend, the backend is a template for robust API design. It features strict statelessness using JWT and Refresh Tokens, and clean separation of Entities and DTOs using ModelMapper.

For developers looking to understand how to build a scalable, decoupled backend, PickItUp serves as a quiet, zero-star masterclass in enterprise architecture.