Pendahuluan: Saat README Berhenti Berkata Jujur
Setelah Part 5, Part 6, dan Part 7, kode mfarim/spring-elearning-react sudah banyak berubah. Sayangnya, README-nya hampir tidak berubah. Isinya masih menjanjikan "Redis cache", broker STOMP yang "backed by Redis", dan "decoupled micro-architecture".
Ternyata semuanya tidak benar. Redis hanya menyimpan refresh token, broker-nya adalah simple broker Spring di memori, dan backend-nya cuma satu service Spring Boot. Bahkan saya sendiri ikut mengulang klaim "Redis cache" itu di Part 1 series ini.
Menurut saya, dokumentasi yang tidak akurat lebih mahal daripada dokumentasi yang tidak ada. Kontributor bisa merencanakan pekerjaan di sekitar cache yang tidak ada. Pewawancara bisa bertanya bagaimana invalidasi cache-nya bekerja, dan jawaban jujurnya adalah "tidak ada cache". Operator bisa melakukan scale out karena "STOMP pakai Redis", lalu guru berhenti menerima event live.
Di bagian terakhir ini, saya cerita soal dua pull request:
- Pull Request #24: docs/architecture-accuracy: koreksi klaim README dan
docs/ARCHITECTURE.mdbaru (316 baris). - Pull Request #25: feat/roadmap-hardening: test dan laporan JaCoCo yang menyertai perubahan di Part 6 dan 7.
Klik diagram untuk membukanya dalam ukuran penuh.
1. Mengaudit README Terhadap Kode
Saya memeriksa README satu klaim demi satu klaim terhadap source code, sama seperti audit kode keamanan di Part 5:
| README bilang | Yang sebenarnya dilakukan kode | Teks perbaikan |
|---|---|---|
| "Redis cache" | Tidak ada @Cacheable, tidak ada cache manager. Redis menyimpan jti refresh token | "Redis-backed refresh-token rotation" |
| "STOMP message broker backed by Redis" | config.enableSimpleBroker("/topic", "/queue"), di memori | "in-memory simple broker" (fan-out Redis datang belakangan di PR #25, sebagai opsi) |
| "decoupled micro-architecture" | Satu deployable Spring Boot dengan package per domain | "modular monolith dengan SPA React terpisah" |
| Redis sebagai "Session & Telemetry Broker" | Sesi berupa JWT stateless; telemetri lewat STOMP | "Refresh-token store, rotasi & pencabutan per jti" |
| Node 20 Alpine | Dockerfile memakai node:22-alpine (sejak PR #6) | Node 22, Nginx 1.28 |
Struktur proyek dengan modul learning/ dan config/ berisi JWT | Package-nya material/, announcement/, grade/, dan security/ terpisah | Struktur dibuat ulang dari package yang sebenarnya |
Perbaikannya bukan membuat sistem terdengar lebih kecil. Yang saya lakukan adalah mendeskripsikan apa yang benar-benar dikerjakan sistem, lalu menunjuk satu tempat yang menjelaskan kenapa.
Aturan yang sekarang saya pakai: setiap klaim arsitektur di README harus bisa dicek dengan
grep. Kalau tertulis "Redis cache", berarti@CacheableatauCacheManagerharus ada di suatu tempat.
2. Isi docs/ARCHITECTURE.md
README menjawab "ini apa dan bagaimana menjalankannya". docs/ARCHITECTURE.md menjawab "bagaimana sistem ini dibangun, kenapa, dan di mana batasnya". Dokumen ini saya bagi menjadi sepuluh bagian:
| # | Bagian | Format | Pertanyaan yang dijawab |
|---|---|---|---|
| 1 | System context | Mermaid flowchart + tabel | Apa berjalan di mana, dan siapa bicara dengan siapa? |
| 2 | Backend modules | Tabel | Di mana sebuah logika seharusnya ditempatkan? |
| 3 | Data model | Mermaid erDiagram | Bagaimana kelas, ujian, attempt, dan jawaban saling terhubung? |
| 4 | Authentication and token rotation | Mermaid sequenceDiagram | Apa yang terjadi saat login, refresh, pemakaian ulang, logout? |
| 5 | Exam lifecycle | sequenceDiagram + stateDiagram-v2 | Aturan apa yang ditegakkan server selama ujian? |
| 6 | Real-time proctoring | Aturan + mode pengiriman | Siapa boleh subscribe, dan bagaimana event sampai ke guru? |
| 7 | Design decisions | Keputusan / alternatif / alasan | Kenapa ini dan bukan alternatif yang paling jelas? |
| 8 | Scaling limits and roadmap | Tabel pengaturan + item terbuka | Apa yang berubah dengan beberapa instance, dan apa yang masih kurang? |
| 9 | Testing strategy | Saat ini vs rencana | Apa yang dites, di level mana? |
| 10 | Operations | Daftar | CI, deploy, health check, job background, log |
Diagram sebagai kode
Semua diagram saya buat dengan Mermaid, sehingga GitHub langsung me-render-nya dan diagram tinggal di samping kode dalam pull request yang sama. Saat alur berubah, diagramnya ikut berubah di diff yang sama, dan reviewer melihat keduanya. Ini system context saat ini:
Keputusan, beserta alternatif yang ditolak
Bagian yang paling berguna bagi pembaca (dan bagi saya sendiri enam bulan lagi) adalah tabel keputusan. Setiap barisnya menyebut alternatif yang saya pertimbangkan dan kenapa alternatif itu kalah:
| Keputusan | Alternatif yang dipertimbangkan | Alasan |
|---|---|---|
| Modular monolith | Microservices | Satu tim dan satu deployable; package per domain menjaga batas tetap jelas dan memungkinkan ekstraksi nanti |
| JWT stateless + refresh token di Redis | Sesi di server; JWT tanpa store | Jalur utama tetap stateless, sementara logout, rotasi, dan revoke-all tetap bekerja |
| Refresh token di cookie httpOnly | Refresh token di localStorage | Tidak bisa dibaca script yang disuntikkan; dibatasi ke endpoint auth dengan SameSite=Strict |
| STOMP di memori + fan-out Redis pub/sub | STOMP broker relay (RabbitMQ / ActiveMQ) | Memakai ulang Redis; tidak ada broker baru yang harus dijalankan |
| Job kedaluwarsa + optimistic locking | Finalisasi hanya saat siswa kembali | Hasil tepat waktu; @Version membuatnya aman lintas instance tanpa distributed lock |
| Waktu dan penilaian di server | Mempercayai timer dan jawaban dari klien | Klien tidak bisa dipercaya |
| Docker Compose di VPS di belakang Cloudflare | Kubernetes; PaaS terkelola | Biaya rendah dan bisa diprediksi |
Keputusan tanpa alternatif terbaca seperti selera. Dengan alternatif, keputusan itu terbaca sebagai trade-off yang sudah dipikirkan.
Menuliskan batasannya
Bagian scaling sengaja saya buka dengan kalimat yang kurang nyaman: konfigurasi default ditujukan untuk satu instance backend. Setelah itu ada daftar pengaturan untuk beberapa instance (tiga switch dari Part 7) dan apa saja yang masih terbuka:
LocalDateTimedengan zona waktu server;Instant/timestamptzdalam UTC akan menghilangkan ambiguitas lintas wilayah.- Access token tinggal di
localStorageselama 15 menit; token di memori dengan silent refresh akan menutup celah itu. - Integration test dengan Testcontainers untuk alur login dan ujian secara penuh, serta test suite frontend.
- Migrasi ke Spring Boot 4 di kemudian hari.
Awalnya, mencantumkan keterbatasan terasa berisiko untuk proyek portofolio. Kenyataannya justru kebalikan dari yang saya takutkan: daftar itu menunjukkan bahwa saya tahu di mana batas-batasnya.
3. Strategi Testing
Sebelum PR #25, backend saya hanya punya tiga class test: test context-load, JwtProviderTest, dan FileStorageServiceTest. Setiap aturan baru di Part 6 dan 7 saya kirim bersama test-nya. Sekarang suite-nya berisi 55 test di 12 class:
| Class | Test | Yang dilindungi |
|---|---|---|
AnswerGraderTest | 6 | Normalisasi isian singkat, alternatif ` |
ExamRunnerServiceTest | 10 | Penilaian, penilaian manual, deadline, ujian ulang, job kedaluwarsa |
ExamRealtimeServiceTest | 5 | Pengiriman setelah commit, fan-out Redis, fallback, pesan rusak |
RefreshTokenStoreTest | 4 | Simpan, konsumsi tepat sekali, user salah, revoke-all |
RefreshTokenCookiesTest | 4 | Atribut cookie, penghapusan, pemindahan body ke cookie |
JwtProviderTest | 7 | Claim typ dua arah, jti unik, secret publik ditolak |
InMemoryRateLimiterTest | 3 | Kapasitas, key terpisah, reset |
RedisRateLimiterTest | 4 | Counter bersama, penolakan, fail open, reset |
S3StorageBackendTest | 3 | Upload, metadata download, objek tidak ada |
FileStorageServiceKeyTest | 2 | Nama acak, key absolut/backslash ditolak |
FileStorageServiceTest | 6 | Path traversal, ekstensi berbahaya |
BackendApplicationTests | 1 | Context Spring berjalan dengan PostgreSQL dan Redis |
Mock di batas, tes aturannya
Sebanyak 54 dari 55 test adalah JUnit 5 + Mockito biasa, tanpa context Spring, dan semuanya selesai dalam hitungan detik. Idenya sederhana: mock infrastrukturnya (Redis, client S3, repository JPA), lalu tes aturannya secara nyata.
Untuk RefreshTokenStore, aturannya adalah "refresh token hanya berlaku tepat sekali". Test-nya meniru Redis supaya berperilaku seperti GETDEL (ada nilai di panggilan pertama, null setelahnya), lalu memeriksa jawaban dari store:
@Test
void aRefreshTokenCanBeConsumedExactlyOnce() {
when(values.getAndDelete("auth:refresh:jti-1")).thenReturn("7").thenReturn(null);
assertTrue(store.consume("jti-1", 7L));
assertFalse(store.consume("jti-1", 7L), "a replayed refresh token must be rejected");
}
Keputusan fail open dari Part 7 juga sebuah aturan, jadi saya beri test, bukan sekadar komentar:
@Test
void failsOpenWhenRedisIsUnavailable() {
when(redis.execute(eq(RedisRateLimiter.INCREMENT_SCRIPT), eq(List.of("rate:login:ip:1")), eq("60000")))
.thenThrow(new RedisConnectionFailureException("connection refused"));
assertTrue(limiter.tryAcquire("login:ip:1", 5, minute));
}
Menguji "hanya setelah commit" tanpa database
Aturan yang paling sulit dites adalah "event monitor hanya dikirim setelah transaksi commit". Ternyata saya tidak butuh transaksi sungguhan. TransactionSynchronizationManager milik Spring bisa dikendalikan secara manual:
@Test
void insideATransactionTheEventIsSentOnlyAfterCommit() {
TransactionSynchronizationManager.initSynchronization();
service("local").broadcastExamEvent(7L, "EXAM_SUBMITTED", Map.of("score", 80));
verifyNoInteractions(messaging); // belum ada yang dikirim
TransactionSynchronizationManager.getSynchronizations().forEach(TransactionSynchronization::afterCommit);
verify(messaging).convertAndSend(eq(MONITOR), any(Object.class));
}
@AfterEach membersihkan synchronization supaya state tidak bocor antar-test.
Kode murni tidak butuh mock sama sekali
AnswerGrader dari Part 6 tidak punya dependensi, jadi test-nya cukup berisi input dan output. Itu alasan utama saya mengeluarkan logika penilaian dari service: aturan yang menentukan nilai siswa seharusnya menjadi kode yang paling mudah dites di proyek ini.
Menguji bug-nya, bukan hanya fiturnya
Test yang paling berharga buat saya adalah yang mereproduksi bug dari Part 6, sehingga bug itu tidak bisa kembali tanpa ketahuan:
@Test void savingAnAnswerAfterTheDeadlineFinalizesTheAttempt() // bug rollback
@Test void manualGradingKeepsAttemptPendingUntilEveryEssayIsGraded() // penilaian parsial tampil sebagai final
@Test void startCreatesTheNextAttemptNumberWhenRetriesAreAllowed() // crash ujian ulang
@Test void finalizeDoesNothingForAttemptsThatAreAlreadyFinished() // penilaian ganda
Yang tidak bisa dibuktikan unit test
Mock tidak bisa membuktikan bahwa native SQL di findExpiredInProgressAttemptIds berjalan di PostgreSQL, bahwa @Version benar-benar menghasilkan konflik, atau bahwa migrasi V3 berjalan mulus di data lama. Untuk itu saya butuh database sungguhan. Satu-satunya integration test (contextLoads) berjalan dengan service container PostgreSQL 16 dan Redis 7 di CI, sehingga Flyway menerapkan V1 → V3 di setiap build. Namun, test alur penuh dengan Testcontainers masih ada di roadmap, dan dokumentasinya menyebutkan hal itu.
4. Coverage JaCoCo di Setiap Run CI
Coverage saya ukur dengan plugin Maven JaCoCo. prepare-agent menginstrumentasi test, dan report berjalan di fase test:
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>${jacoco.version}</version> <!-- 0.8.12 -->
<executions>
<execution>
<id>prepare-agent</id>
<goals><goal>prepare-agent</goal></goals>
</execution>
<execution>
<id>report</id>
<phase>test</phase>
<goals><goal>report</goal></goals>
</execution>
</executions>
</plugin>
Workflow GitHub Actions menjalankan PostgreSQL dan Redis sebagai service container, menjalankan ./mvnw clean package, lalu mengubah jacoco.csv menjadi ringkasan satu baris di halaman job dan meng-upload laporan HTML-nya:
- name: Build and Package with Maven
run: ./mvnw clean package
- name: Publish coverage summary
if: always()
run: |
if [ -f target/site/jacoco/jacoco.csv ]; then
awk -F, 'NR > 1 { missed += $8; covered += $9 }
END { total = missed + covered; if (total > 0) printf "### Backend line coverage: %.1f%% (%d of %d lines)\n", 100 * covered / total, covered, total }' \
target/site/jacoco/jacoco.csv >> "$GITHUB_STEP_SUMMARY"
fi
- name: Upload coverage report
if: always()
uses: actions/upload-artifact@v4
with:
name: jacoco-report
path: backend/target/site/jacoco
if-no-files-found: ignore
Kolom 8 dan 9 di CSV JaCoCo adalah LINE_MISSED dan LINE_COVERED. Dengan if: always(), angkanya tetap dipublikasikan walaupun ada test yang gagal, karena justru saat itulah kita ingin melihatnya.
Kenapa belum ada batas minimum coverage
JaCoCo bisa menggagalkan build di bawah persentase tertentu, tetapi untuk saat ini saya memilih tidak memakainya. Controller dan kode import Excel sebagian besar belum dites, jadi batas minimum apa pun hari ini akan terlalu rendah sampai tidak bermakna, atau malah memblokir pull request yang tidak berhubungan. Rencana saya, yang tertulis di tabel strategi testing, adalah menambahkan batas itu setelah suite Testcontainers ada. Sampai saat itu, angkanya terlihat di setiap run, dan penurunan akan ketahuan saat review.
5. Seluruh Series dalam Satu Tabel
| Part | Topik | Pull request |
|---|---|---|
| 1 | Membangun ulang monolit Laravel menjadi Spring Boot + React | — |
| 2 | Path traversal, refresh token, ketahanan Docker | #1 |
| 3 | JWT stateless, RBAC level method, OWASP Top 10, rate limiting | #1, #3, #4 |
| 4 | Deploy single VPS dengan Docker Compose, Nginx, dan SSL | #2 |
| 5 | Audit kedua: IP klien asli, rotasi refresh, wajib ganti password, otorisasi file dan STOMP | #5, #6 |
| 6 | Integritas ujian: noRollbackFor, job kedaluwarsa, attempt unik, @Version | #25 |
| 7 | Cookie httpOnly, CSP, Redis dan S3 untuk beberapa instance | #25 |
| 8 | Dokumentasi arsitektur, strategi testing, JaCoCo | #24, #25 |
Kesimpulan
Series ini dimulai sebagai "membangun ulang platform e-learning Laravel dengan Spring Boot dan React". Akhirnya, perjalanan ini sampai di tempat yang lebih berguna: sistem yang keamanannya, aturan ujiannya, dan batas scaling-nya tertulis, dites, dan sesuai dengan kodenya.
Kalau saya harus menyimpan tiga kebiasaan dari delapan part ini, inilah yang saya pilih:
- Audit dengan pengetahuan penyerang. Anggap mereka sudah membaca repo kamu (Part 5).
- Biarkan database menjamin apa yang tidak bisa dijamin
if. Unique key, kolom version, dan batas transaksi (Part 6). - Buat dokumentasi yang bisa dicek. Setiap klaim harus berjarak satu
grepdari kode yang membuktikannya (Part 8).
Terima kasih sudah mengikuti series ini sampai akhir. Kode, dokumentasi, dan demo live-nya semuanya publik, jadi issue dan pull request dari kamu sangat saya tunggu.
- Demo live: https://spring-elearning.mfarim.com
- Source code: github.com/mfarim/spring-elearning-react
- Panduan arsitektur: docs/ARCHITECTURE.md
- Pull request: #24, #25

Ditulis oleh Muhammad Fari Madyan
Senior Full Stack Engineer dan co-founder LampungDev. Saya menuliskan apa yang saya bangun supaya orang lain bisa ikut belajar.

