Tartalomjegyzék

  1. Önálló Laboratórium Terv: MotoRun Backend Migráció
  2. Önálló Laboratórium Féléves Terv
  3. 1. Bevezető és a projekt háttere
  4. 2. A félév célkitűzései
  5. 3. Tervezett Architektúra
  6. 4. Főbb technikai kihívások
  7. 5. Ütemterv (10 hét)
Önálló Laboratórium Terv: MotoRun Backend Migráció Önálló Laboratórium Terv: MotoRun Backend Migráció

Önálló Laboratórium Terv: MotoRun Backend Migráció

2026. febr. 18. / 6 perc olvasás / Címkék: Önlab, Spring Boot, Android

Önálló Laboratórium Féléves Terv

Téma: Versenyadminisztrációs rendszer migrációja BaaS környezetből Cloud-Native Spring alapokra
Hallgató: Nagy Benedek (Szoftverfejlesztés/IIT specializáció)
Konzulens: Imre Gábor
Félév: 2025/26 Tavasz

1. Bevezető és a projekt háttere

A MotoRun egy saját fejlesztésű, élesben használt Android alkalmazás (Kotlin, Jetpack Compose), amely a Silkolene motoRun motoros tájékozódási verseny-sorozat adminisztrációját támogatja. A rendszer évente kb. 4 versenynapon kerül bevetésre, ahol a pontőrök az ellenőrzőpontokon rögzítik a versenyzők áthaladását, és az adatokat valós időben szinkronizálják a szervezőkkel. A versenyek rendszerint olyan terepen zajlanak, ahol a mobilnet-lefedettség szórványos vagy teljesen hiányzik, ezért az alkalmazás strict offline-first elven működik.

A backend jelenleg Firebase Authentication és Firestore - ez a BaaS megoldás induláskor jól szolgált, de az alkalmazás kinőtte:

  • A Firestore árazási modellje miatt kliensoldalon rate limitinget kellett bevezetnem, ami perces szinkronizációs késéseket okoz.
  • Üzleti logika kizárólag a klienseken fut, mert a Firestore önmagában csak adattárolásra képes.
  • Nincs szerveroldali source of truth - ha több szervezői eszköz párhuzamosan módosít, a konfliktusfeloldás esetleges.
  • Samsung eszközökön a NET_CAPABILITY_VALIDATED megbízhatatlan, ami az offline/online állapot detektálásánál okoz gondot.

2. A félév célkitűzései

A célom a teljes Firebase backend leváltása saját fejlesztésű, cloud-native Spring Boot monolith architektúrára. A meglévő Android kliens offline-first logikáját (Room) érintetlenül hagyom - kizárólag a remote sync réteget cserélem le.

A fókusz egyértelműen a backend, de a feladat magában foglalja a kliensoldalon a Firebase SDK-k kivezetését és a Retrofit + WebSocket integráció megvalósítását is.

A fejlesztésnek július 2-ra (az idei 1. versenynap) production-ready állapotba kell kerülnie. A fejlesztés alatt a production környezet továbbra is Firebase-en marad; az átállás egy clean cutover lesz, amikor a teljes rendszer tesztelten működőképes.

Kitekintés: A rendszert úgy tervezem, hogy a BSc szakdolgozat keretében továbbfejleszthető legyen (web admin felület, analitika, multi-datacenter replikáció) architektúra-módosítás nélkül.

3. Tervezett Architektúra

A rendszer egy Spring Boot alkalmazásból, egy PostgreSQL adatbázisból és a meglévő Android kliensből áll. Az alkalmazás Spring Modulith alapon tagolt: auth és entry modul, közös konfiguráció és infrastruktúra réteg.

Auth modul - A Firebase Auth leváltása. JWT alapú autentikáció (access + refresh token), RBAC (CHECKPOINT, ORGANIZER, ADMIN szerepkörök), felhasználókezelés (CRUD). Jelszavak BCrypt hashsel tárolva. Spring Security filter chain érvényesíti a JWT validációt és a CORS szabályokat.

Entry modul - A Firestore leváltása. Entry CRUD REST API-val, szerveroldali validáció, optimistic locking alapú konfliktusfeloldás, és STOMP over WebSocket valós idejű broadcast. Az adatokat PostgreSQL tárolja, a séma verziókezelést Liquibase végzi. Az auditáláshoz Hibernate Envers infrastruktúra kerül beépítésre (a rollback UI a szakdolgozat scope-ja).

Android kliens - A Room alapú offline-first működés változatlan marad. A Firebase SDK-kat Retrofit (REST) és egy STOMP kliens váltja le. A hálózat-elérhetőséget a Spring Boot Actuator health endpoint validálja, kiváltva az OS-szintű detektálást.

Infrastruktúra - Docker Compose, GitHub Actions CI/CD, Spring Boot 4.0.3, Java 25, Gradle Kotlin DSL, Micrometer metrikák -> Prometheus -> Grafana.

4. Főbb technikai kihívások

Offline-first sync és konfliktuskezelés - A pontőrök eszközei órákig offline lehetnek. Visszacsatlakozáskor a felhalmozott bejegyzéseket bulk push/pull-al szinkronizálom. A szerver optimistic locking (version mező) alapján autoritatívan dönt a konfliktusokról. Ez a jelenlegi kliensoldali konfliktusfeloldást váltja le.

Valós idejű adatszórás - A polling alapú Firestore sync-et STOMP WebSocket broadcast váltja fel. A szervező a verseny közben késleltetés nélkül látja az összes ellenőrzőpont adatát, a pontőrök pedig a saját és szomszédos checkpointjaikat. Ha a WebSocket integráció (Krossbow library) váratlan problémákat okozna, fallback-ként polling-alapú REST sync is használható.

Adatbázis séma verziókezelés - A Firestore dokumentum-modelltől relációs sémára váltok. A Liquibase changelog-first megközelítés biztosítja a migrációk reprodukálhatóságát és rollback képességét.

Hálózat-detektálás - A Samsung-specifikus NET_CAPABILITY_VALIDATED bug miatt az OS-szintű hálózatfigyelés nem elég megbízható. Bejelentkezés előtt a health check endpoint aktív pollinggal validálja a szerver elérhetőségét; bejelentkezés után a STOMP WebSocket connection state veszi át ezt a szerepet.

5. Ütemterv (10 hét)

Az ütemtervet úgy terveztem, hogy a 10. hét végére (április 26.) a teljes rendszer funkcionálisan kész legyen. Az ezt követő ~10 hét a július 2-ai versenynapig hardening, tesztelés és prezentáció-előkészítés. Az első hetekre terhelem a backend fejlesztést, mert ott nincs Android-függőség és egységekben is jól tesztelhető.

  • 1. hét (Febr. 16 – 22.) - Projekt scaffolding, követelmények és architektúra véglegesítése. Spring Boot alkalmazás skeleton generálása Spring Initializr-rel (auth + entry modul csomagstruktúrával). Docker Compose környezet (PostgreSQL + alkalmazás + Prometheus + Grafana), Liquibase alapsémák (users, entries, refresh_sessions).

  • 2. hét (Febr. 23 – Márc. 1.) - CI/CD és megfigyelhetőség. GitHub Actions workflow (build, teszt, Docker image push, autodeploy). Micrometer metrikák bekötése, Prometheus scrape konfiguráció, Grafana dashboard alap (JVM, HTTP, DB connection pool). Spring Boot Actuator health endpoint konfigurálása.

  • 3. hét (Márc. 2 – 8.) - Auth modul teljes implementáció: felhasználó CRUD, BCrypt jelszókezelés, JWT access/refresh token generálás és validálás, refresh token rotation, RBAC. Spring Security filter chain és CORS konfiguráció.

  • 4. hét (Márc. 9 – 15.) - Entry modul REST API: Entry CRUD végpontok, DTO mapping, szerveroldali validációk (kilométeróra delta ellenőrzés, soft delete), year-scoped resource path-ok (/api/v1/entries/{year}).

  • 5. hét (Márc. 16 – 22.) - Szinkronizációs réteg: bulk push/pull endpointok, optimistic locking alapú konfliktusfeloldás, determinisztikus conflict response-ok. Hibernate Envers audit infrastruktúra beépítése.

  • 6. hét (Márc. 23 – 29.) - STOMP over WebSocket integráció az entry modulban. Topic-ok kialakítása (/topic/entries/{year}/{date}, /topic/entries/{year}/{date}/{checkpointId}), broadcast minden sikeres write után, subscription szintű RBAC.

  • 7. hét (Márc. 30 – Ápr. 5.) - Android kliens: Firebase Auth kivezetése. Retrofit hálózati réteg beépítése, JWT token management (OkHttp Interceptor, automatikus refresh), login flow átírása.

  • 8. hét (Ápr. 6 – 12.) - Android kliens: Firestore SDK kivezetése. A Room adatbázis és az új REST sync réteg összekötése, offline entry queue kezelése, bulk sync logika implementálása.

  • 9. hét (Ápr. 13 – 19.) - Android kliens: STOMP kliens (Krossbow) integrálása a valós idejű frissítésekhez. Health check alapú hálózatfigyelés implementálása (pre-auth polling, post-auth WebSocket state).

  • 10. hét (Ápr. 20 – 26.) - End-to-end integrációs tesztelés: teljes flow (offline rögzítés → visszacsatlakozás → sync → konfliktusfeloldás → broadcast) több szimulált eszközzel. Dokumentáció: Önálló Lab beszámoló. Utolsó hibajavítások.

Az április 26. utáni heteket az ütemtervben nem jelölöm külön - ez a tartalék a július 2-ai versenynapig a stabilitási tesztelésre, az éles környezet beüzemelésére és a prezentáció előkészítésére szolgál.

Vissza a bloghoz