This page documents all communication flows between the iOS app and the AdventureTube backend microservices and will be posted as YouTube for my channel “JAVAiOSwithAI”.
Shared Data Contract: Java ↔ iOS
All communication between Java backend and iOS relies on matched domain models that serialize/deserialize through JSON. If either side changes a field name, the contract breaks.
The Three Core Pairs
iOS adds one convenience property not in Java:
var isTerminal: Bool { self != .PENDING }This is iOS-only logic — used to know when to stop polling/streaming. Java doesn’t need it because the backend decides when a job ends.
Example JSON
{
"success": true,
"message": null,
"errorCode": null,
"data": {
"trackingId": "b8ece320-9673-48c5-95fe-e9e7c1b8d872",
"youtubeContentID": "WsghFCuoZ6Q",
"status": "PENDING",
"errorMessage": null,
"chaptersCount": 4,
"placesCount": 4
},
"timestamp": "2026-03-31T12:30:00"
}Episodes
Each episode documents a specific communication flow between iOS and the backend:
- Episode 1: Publish Story — The complete request flow when an iOS user publishes geo data through the microservice architecture (token refresh, Kafka async processing, SSE status streaming)
- Episode 2: Chapter Screenshots — Async pipeline that extracts screenshots from YouTube videos at chapter timestamps using yt-dlp + ffmpeg and uploads to MinIO S3
- Episode 3: Delete Story (with Screenshot Cleanup) — Synchronous delete pipeline that removes screenshots from MinIO S3 then deletes data from MongoDB, tracked via SSE
- Episode 4: Chapter Thumbnail — Displaying chapter screenshots as a horizontal scroll row on published story cards, with REST polling endpoint for iOS