Real-time pilgrimage tracking — Utrecht to Santiago de Compostela

Wanderer is the backend for a real-time pilgrimage tracking platform built for my walk from Utrecht to Santiago de Compostela — roughly 48 days and 50 km per day. It lets friends, family, and anyone following along see where I am, read updates, leave comments, and watch achievements unlock as the journey unfolds.

The system is built on a CQRS (Command Query Responsibility Segregation) architecture with three independently deployable Spring Boot services backed by PostgreSQL, connected to a companion frontend through REST APIs and WebSockets.

• Architecture
• Features
• Getting Started
• API Overview
• Real-Time Events
• Data Model
• Security
• Deployment
• Documentation
• Contributing
• License

The backend is a multi-module Maven project split by responsibility:

wanderer-backend/
├── commons/            Shared domain entities, DTOs, mappers, and constants
├── wanderer-auth/      Authentication & authorization          → Port 8083
├── wanderer-command/   Write operations (create, update, delete) → Port 8081
├── wanderer-query/     Read operations (queries & lists)        → Port 8082
├── docs/               Additional guides and documentation
└── docker-compose.yml  Full local stack with two Postgres instances

• Create trips with configurable visibility (Public, Private, Protected) and modality (Simple or Multi-Day)
• Post location updates with GPS coordinates, altitude, battery level, and messages
• Automatic polyline generation from location history
• Reverse geocoding of coordinates into city and country
• Day-by-day tracking for multi-day trips with start/end day toggling
• Trip status lifecycle: Created → In Progress → Paused / Resting → Finished

• Friend requests with accept/decline workflow
• Bidirectional friendships that unlock access to Protected trips
• User follows for one-directional social connections
• Public trip discovery and promoted/featured trips

• Threaded comments on trips with one level of nesting (replies)
• Five reaction types on comments: ❤️ Heart, 😊 Smiley, 😢 Sad, 😂 Laugh, 😠 Anger

• 25 predefined achievements across categories: distance milestones, update counts, trip duration, and social milestones (followers, friends)
• Automatic unlock when thresholds are reached during trip updates
• Per-user and per-trip achievement queries

• WebSocket endpoint at /ws with 24 event types
• Live broadcasting to topic channels (/topic/trips/{tripId}, /topic/users/{userId})
• Events for trip changes, comments, reactions, friend requests, follows, achievements, and polyline updates

• Admin role promotion and demotion
• Bootstrap admin mechanism for initial setup
• Trip polyline and geocoding recomputation
• Trip promotion with donation link support
• Trip maintenance statistics dashboard
• User and credential management

• Google Weather API integration for live weather conditions at the current location

• Email verification on registration
• Password reset with time-limited, one-time-use tokens
• Configurable SMTP provider

• Java 21 — required
• Maven 3.6+ — required
• Docker — optional, for running the full stack locally
• PostgreSQL 16 — required if running without Docker

# Build all modules
mvn clean install

# Build a single module
mvn clean install -pl wanderer-command

# Format code (run before committing)
mvn spotless:apply

# Run tests with coverage
mvn clean verify

Start each service individually:

# Auth (Port 8083)
mvn spring-boot:run -pl wanderer-auth

# Command (Port 8081)
mvn spring-boot:run -pl wanderer-command

# Query (Port 8082)
mvn spring-boot:run -pl wanderer-query

Or bring up the full stack with Docker Compose:

docker-compose up

This starts two PostgreSQL databases (one for auth, one for command/query), and all three services with sensible defaults.

Once running, interactive API docs are available at:

• Auth: http://localhost:8083/swagger-ui.html
• Command: http://localhost:8081/swagger-ui.html
• Query: http://localhost:8082/swagger-ui.html

All endpoints are under /api/1. Below is a summary grouped by domain. For detailed request/response examples, see the Wiki.

🔒 = Requires authentication (JWT Bearer token). Admin endpoints also require the ADMIN role.

The command service exposes a WebSocket endpoint at /ws. Clients subscribe to topic channels and receive JSON messages as events occur.

1. Register → email verification link sent → verify email → account activated
2. Login → returns a short-lived access token (15 min default) and a long-lived refresh token (7 days)
3. Refresh → exchange a valid refresh token for a new token pair (rotation policy — old refresh token is revoked)
4. Logout → access token blacklisted by JTI, all refresh tokens revoked

• Role-based access: USER and ADMIN roles enforced with Spring Security @PreAuthorize
• Protected trips visible only to friends of the owner
• Public endpoints: registration, login, token refresh, password reset, public trips, user profiles
• Admin endpoints: user promotion, trip maintenance, statistics

All tokens (refresh, password reset, blacklist) are hashed with SHA-256 before being stored in the database. Expired tokens are cleaned up automatically.

The included docker-compose.yml runs the full stack:

• postgres-cqrs — PostgreSQL for command and query services (port 5432)
• postgres-auth — PostgreSQL for the auth service (port 5433)
• wanderer-command — Command service (port 8081)
• wanderer-query — Query service (port 8082)
• wanderer-auth — Auth service (port 8083)

docker-compose up

mvn clean compile jib:dockerBuild -pl wanderer-command
mvn clean compile jib:dockerBuild -pl wanderer-query
mvn clean compile jib:dockerBuild -pl wanderer-auth

Images are also published to ghcr.io/tomassirio/ via CI.

The project is designed for Kubernetes deployment with Helm charts covering services, ConfigMaps, Secrets, Ingress, and health probes.

Swagger UI is available on each running service at /swagger-ui.html.

This is a personal project for my pilgrimage, but suggestions and improvements are welcome. Open an issue or submit a pull request.

Before submitting code, please run:

mvn spotless:apply   # Format code
mvn clean verify     # Run tests and check coverage (target: 80%+)

This project is licensed under the MIT License. You are free to use, modify, and distribute this software.

¡Buen Camino! 🥾⛪