AdventureTube Java Backend — Complete Technical Documentation

By /

This page is the master technical reference for the AdventureTube backend platform — a Spring Cloud microservices system deployed on a 3-node Raspberry Pi cluster.

Tech Spec

CategoryTechnology
LanguageJava 21 (Virtual Threads)
FrameworkSpring Boot 3.4.0, Spring Cloud 2024.0.0
Reactive StackSpring WebFlux (Netty) — Auth Service
Blocking StackSpring MVC (Tomcat) — Member, Geospatial, Web Services
API GatewaySpring Cloud Gateway (Netty/Reactive)
Service DiscoveryNetflix Eureka
ConfigurationSpring Cloud Config (Git-backed)
Inter-Service HTTPWebClient (Reactive) via shared ServiceClient
Circuit BreakerResilience4j 2.2.0
AuthenticationJWT + Google OAuth2
Relational DBPostgreSQL 17 (JPA/Hibernate)
Document DBMongoDB 4.4 (Spring Data MongoDB)
Event StreamingApache Kafka (KRaft mode, 2-broker cluster)
Event Streaming Topics4 topics: adventuretube-data-create, adventuretube-data-delete, adventuretube-screenshots-create, adventuretube-screenshots-delete
Object StorageMinIO S3-compatible (chapter screenshots)
Async NotificationSSE (Server-Sent Events) via SseEmitter
Distributed TracingMicrometer + Brave + Zipkin
MonitoringGrafana + Prometheus + cAdvisor
CI/CDJenkins (Master/Agent) + GitHub Webhooks
ContainerizationDocker Compose
Infrastructure3-node Raspberry Pi cluster (ARM64)
Reverse ProxyNginx Proxy Manager + Let’s Encrypt SSL
API DocumentationSwagger/OpenAPI 3.1 via SpringDoc

1. Spring Microservice Architecture

AdventureTube Microservice Architecture

Architecture Overview

AdventureTube Spring Cloud Microservice Architecture Diagram
AdventureTube Microservice Architecture

Service Registry & Discovery

  • Eureka Server (PI2:8761) — all services register here
  • Config Service (PI2:9297) — centralized config backed by Git repo
  • Gateway Service (PI2:8030) — single entry point, routes to all business services

Swagger Open API

https://api.travel-tube.com/swagger-ui/index.html

Business Services

Currently deployed via Jenkins to PI2. In dev mode, run locally on Mac and register to Eureka on PI2.

ServicePortStackDatabase
Auth Service8010WebFlux (Netty)None — calls member-service
Member Service8070MVC (Tomcat)PostgreSQL (PI1)
Geospatial Service8060MVC (Tomcat)MongoDB (PI1)
Web Service8040MVC (Tomcat)None — calls geospatial-service

Data Layer

StoreHostPortUsed By
PostgreSQLPI15432Member Service (JPA/JDBC)
MongoDBPI127017Geospatial Service
Kafka (2-broker cluster)PI1 + PI229092Event streaming (geospatial-service producer/consumer)
MinIO (S3)PI19200Chapter screenshot storage (geospatial-service)

Kafka Cluster (KRaft Mode — No Zookeeper)

BrokerHostRolePorts
kafka1PI1 (192.168.1.199)broker + controller9092, 29092, 19092, 9093
kafka2PI2 (192.168.1.105)broker only9092, 29092, 19092
  • Cluster ID: HLThU0HXQJegC_vT4NGpCw
  • Topics: adventuretube-data-create (2 partitions), adventuretube-data-delete (1 partition), adventuretube-screenshots-create (1 partition), adventuretube-screenshots-delete (1 partition)
  • Kafdrop UI: PI1:9000 (kafka.travel-tube.com)

2. Docker Architecture — Three-Layer Separation of Concerns

With this tech stack, the entire backend system is organized into three distinct layers, which makes perfect sense for creating separate Docker Compose files for initialization and management. The first two sections — Infrastructure Layer and Platform Layer — are not subject to frequent development iteration, but rather serve as a stable foundation. The Business Layer is where development and iteration of business logic is focused, except in situations where there are major updates for infrastructure or platform levels.

Infrastructure Layer (Storage Systems)

File: docker-compose-storages.yml

This foundational layer provides all data persistence and storage systems:

  • PostgreSQL Database: Primary relational database for structured data, user profiles, and content metadata
  • MongoDB Database: NoSQL database optimized for geospatial data and flexible content storage
  • Redis Cache: In-memory caching for session management and performance optimization
  • Storage Volumes: Persistent file storage for media content and system backups

Platform Layer (Spring Cloud Applications)

File: docker-compose-clouds.yml

This layer handles cross-cutting concerns and system-wide functionality:

Eureka Server
Central service registry that handles automatic registration, health monitoring, and dynamic service discovery for all microservices.

Config Server
Centralized configuration management system that provides environment-specific settings and Git-based version control for all services.

Gateway Service
Single entry point API gateway that handles request routing, authentication, rate limiting, and Swagger documentation aggregation.

Business Layer (Domain Services)

File: docker-compose-adventuretubes.yml

This layer focuses on specific business capabilities and domain logic:

Auth Service
JWT-based authentication and authorization service with Google OAuth integration for secure user identity management.

Member Service
User profile and account management service handling registration, preferences, and relationship data.

Geospatial Service
Location-based service using MongoDB for spatial data, Kafka for fail-safe storage processing, and MinIO S3 for chapter screenshot storage. Includes async screenshot generation pipeline (yt-dlp + ffmpeg + MinIO upload) triggered via Kafka events.

Web Service
Frontend interface service that provides APIs for any web application needing integration with the AdventureTube content ecosystem.

Architectural Benefits

This structure allows for independent scaling, deployment, and technology choices while maintaining clear boundaries between infrastructure, platform, and business concerns. This approach provides great flexibility in managing the entire system, allowing the use of two separate Raspberry Pi 5 micro servers without paying for cloud services during the development phase.

3. CI/CD Pipeline & Environment Variables

→ See dedicated post: AdventureTube Cloud Services – CI/CD Pipeline & Environment Variables

4. Pi Cluster — All Services

PI1 — 192.168.1.199 (Storage + Monitoring + Tooling)

ContainerStackPurpose
kafka1adventuretube-microserviceKafka broker + KRaft controller
kafdropadventuretube-microserviceKafka web UI
postgresadventuretube-microservicePostgreSQL (member-service)
pgadminadventuretube-microservicePostgreSQL admin UI
mongodbadventuretube-microserviceMongoDB (geospatial-service)
mongo-expressadventuretube-microserviceMongoDB admin UI
minioadventuretube-microserviceMinIO S3 object storage (chapter screenshots)
jenkins-masterjenkins-docker-composeCI/CD server
grafanagrafana-prometheus-docker-composeDashboards
prometheusgrafana-prometheus-docker-composeMetrics collection
zipkingrafana-prometheus-docker-composeDistributed tracing
cadvisorgrafana-prometheus-docker-composeContainer metrics
node_exportergrafana-prometheus-docker-composeHost metrics
kafka-exportergrafana-prometheus-docker-composeKafka metrics
nginx-app-1nginxReverse proxy for all domains
nginx-db-1nginxNginx Proxy Manager DB
n8nn8n-docker-composeWorkflow automation
wordpresswordpressBlog
wordpress-dbwordpressWordPress DB
fastapi_whisperwhisperWhisper AI transcription
portainer–Docker management UI

PI2 — 192.168.1.105 (Spring Cloud + Kafka Broker 2)

ContainerStackPurpose
config-serviceadventuretube-microserviceCentralized config (Git-backed)
eureka-serveradventuretube-microserviceService discovery
gateway-serviceadventuretube-microserviceAPI Gateway
kafka2adventuretube-microserviceKafka broker (2nd node)
adventurevictoriaadventuretubeAdventureVictoria web app
jenkins-agentjenkins-docker-composeCI/CD build agent
kafka-exportergrafana-prometheus-for-kafkaKafka metrics
cadvisorgrafana-prometheus-for-kafkaContainer metrics
node_exportergrafana-prometheus-for-kafkaHost metrics
fastapi_whisperwhisperWhisper AI (2nd instance)
portainer–Docker management UI

PI3 — 192.168.1.141 (Lightweight Services)

ContainerStackPurpose
adventurevictoriaadventuretubetravel-tube.com main website (:3010→3000)
jenkins-agentjenkins-docker-composeCI/CD build agent (jenkins-agent3, :2222→22)
kafka-exportergrafana-prometheusKafka metrics (:9308)
cadvisorgrafana-prometheusContainer metrics (:8080)
node_exportergrafana-prometheusHost metrics (:9100)
portainer–Docker management UI (:9443)

5. Deployment Modes

Production (full Pi cluster)

Client → Nginx Proxy Manager (PI1) → Gateway (PI2:8030) → Business Services (PI2)
                                                             → PostgreSQL (PI1)
                                                             → MongoDB (PI1)
                                                             → Kafka (PI1 + PI2)

Development (Mac + Pi)

  • PI1: databases + Kafka + monitoring (same as prod)
  • PI2: Eureka + Config + Gateway + kafka2 (same as prod)
  • Mac (IntelliJ): auth, member, geospatial, web services run as Java processes
  • Services register to Eureka on PI2, connect to databases/Kafka on PI1+PI2
  • Access via Gateway: 192.168.1.105:8030 or direct: localhost:{port}
  • After deploy, Eureka may show 2 instances per service (Mac + PI2) — Gateway load-balances between them

6. Docker Compose Files

FileRuns OnServices
docker-compose-kafka.ymlPI1 (kafka1 + kafdrop), PI2 (kafka2)Kafka cluster
docker-compose-storages.ymlPI1PostgreSQL, MongoDB, pgAdmin, mongo-express
docker-compose-clouds.ymlPI2Eureka, Config, Gateway
docker-compose-adventuretubes.ymlPI2Auth, Member, Web, Geospatial services

All compose files require --env-file so ${CLOUD_IP_ADDRESS}, ${PI1_IP}, ${PI2_IP}, ${KAFKA_CLUSTER_ID} etc. resolve correctly.

# Example: start Kafka on PI1
docker compose --env-file env.pi -f docker-compose-kafka.yml up -d

7. Domain Names (Nginx Proxy Manager on PI1)

All SSL via Let’s Encrypt. Domain: travel-tube.com (migrated from adventuretube.net).

Core Services

DomainPurpose
travel-tube.comMain website
api.travel-tube.comAPI Gateway
eureka.travel-tube.comEureka dashboard
config.travel-tube.comConfig server

Monitoring & Admin

DomainPurpose
grafana.travel-tube.comGrafana dashboards
zipkin.travel-tube.comDistributed tracing UI
kafka.travel-tube.comKafdrop (Kafka web UI)
pgadmin.travel-tube.comPostgreSQL admin
jenkins.travel-tube.comJenkins CI/CD
s3.travel-tube.comMinIO S3 API (chapter screenshots)

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top