Arsitektur Aplikasi

Repository ini adalah satu aplikasi Next.js yang seluruh halamannya disiapkan sebagai halaman statis saat build, lalu dijalankan sebagai Worker di Cloudflare. Tidak ada database maupun lapisan API terpisah: setiap rute membaca konten dari src/data lewat helper di src/lib, dan komponen di src/components menyusun tampilannya. Alias impor @/* dipetakan ke ./src/*, sehingga seluruh modul saling merujuk dengan awalan yang sama tanpa path relatif panjang. tsconfig.json:25-29¹

Peta modul

graph TD
  App["src/app — rute dan prerender"] --> Components["src/components — UI"]
  Components --> Lib["src/lib — logika murni"]
  App --> Lib
  Lib --> Data["src/data — konten statis"]
  Layout["layout.tsx — RootLayout"] --> App
  Lib --> Seo["src/lib/seo.ts"]
  style App fill:#f59e0b,color:#000
  style Layout fill:#f59e0b,color:#000
  style Lib fill:#2d7d46,color:#fff
  style Seo fill:#2d7d46,color:#fff
  style Components fill:#8b5cf6,color:#fff
  style Data fill:#336791,color:#fff
%% fig: Lapisan modul src
%% desc: Rute di src/app memakai komponen, rute dan komponen membaca helper di src/lib, lalu helper membaca konten statis di src/data.

Lapisan halaman

RootLayout membungkus semua rute: ia memuat tiga font lewat next/font/google, menaruh themeInitScript di <head>, dan menyetel lang="id" pada elemen <html>. src/app/layout.tsx:50-62² Halaman beranda merangkai dua tingkat belajar langsung dari metadata kategori, jadi label dan deskripsi menu tidak ditulis ulang di halaman. src/app/page.tsx:45-48³ Layout rute pemula hanya membungkus anaknya dengan FullscreenFrame, sehingga mode layar penuh berlaku untuk seluruh turunan rute itu. src/app/pemula/layout.tsx:3-5⁴

Lapisan logika murni

src/lib/categories.ts sengaja tidak mengimpor apa pun agar komponen klien bisa memakainya tanpa menarik data pelajaran. src/lib/categories.ts:1-4⁵ src/lib/lessons.ts yang melakukan penggabungan: empat berkas praktik dan satu berkas pertemuan tajwid disatukan lalu diurutkan menurut position, dan seluruh pembacaan pelajaran melewati listLessons, listAllLessons, dan getLesson. src/lib/lessons.ts:1-25⁶ Identitas situs dipusatkan di src/lib/seo.ts, yang menyimpan SITE_URL, SITE_NAME, dan SITE_DESCRIPTION tanpa dependensi; rincian pemakaiannya ada di SEO dan Metadata. src/lib/seo.ts:5-9⁷

Dua helper membaca sumber data yang berbeda. src/lib/quran.ts mengimpor quran.json dan menyaring ayat berdasarkan halaman mushaf atau pasangan surah–ayat. src/lib/quran.ts:1-4⁸ src/lib/learning-progress.ts menyimpan progres di localStorage lewat kunci materi-progress dan terakhir-belajar, dengan parser yang menolak nilai rusak. src/lib/learning-progress.ts:1-4⁹ Alur penyimpanan progres dibahas di Progres Belajar di Perangkat, sedangkan isi berkas Qur'an di Data Qur'an dan Mushaf.

Prerender rute dinamis

Rute [slug] tidak dirender saat request. Keduanya mengekspor generateStaticParams yang memetakan daftar pelajaran satu kategori menjadi daftar slug, sehingga setiap pelajaran menjadi halaman statis saat build. src/app/pemula/[slug]/page.tsx:16-18¹⁰ src/app/lanjutan/[slug]/page.tsx:22-24¹¹ Halaman pemula juga mengalihkan slug yang bukan kategori praktik ke rute yang benar, dan sebaliknya di lanjutan, jadi satu pelajaran hanya punya satu URL. Rincian isi halaman pelajaran ada di Alur Konten Pelajaran.

Jalur build ke Cloudflare Workers

Build berjalan dua tahap: next build menghasilkan keluaran Next.js, lalu opennextjs-cloudflare build mengubahnya menjadi Worker dan aset statis. Skrip preview, deploy, dan upload di package.json menjalankan kedua tahap itu berurutan. package.json:15-17¹²

graph LR
  Next["next build"] --> OpenNext["opennextjs-cloudflare build"]
  OpenNext --> Out[".open-next/worker.js dan .open-next/assets"]
  Out --> Worker["worker.ts — tulis ulang Cache-Control"]
  Out --> Assets["Workers static assets (ASSETS)"]
  Worker --> Edge["quran-academy di Cloudflare Workers"]
  style Next fill:#f59e0b,color:#000
  style OpenNext fill:#f59e0b,color:#000
  style Out fill:#8b5cf6,color:#fff
  style Assets fill:#336791,color:#fff
  style Worker fill:#2d7d46,color:#fff
  style Edge fill:#2d7d46,color:#fff
%% fig: Jalur build OpenNext ke Cloudflare Workers
%% desc: next build menghasilkan keluaran yang diubah adapter OpenNext menjadi Worker dan aset statis, lalu worker.ts membungkus fetch sebelum dilayani dari Cloudflare.

wrangler.jsonc mengikat semuanya: main menunjuk worker.ts, direktori aset diambil dari .open-next/assets dengan binding ASSETS, dan compatibility_flags mengaktifkan nodejs_compat. wrangler.jsonc:1-11¹³ Karena situs sepenuhnya statis, open-next.config.ts memakai staticAssetsIncrementalCache dan enableCacheInterception, sehingga halaman yang sudah diprerender dilayani dari aset, bukan dirender ulang oleh Worker pada setiap request. open-next.config.ts:1-9¹⁴

worker.ts tidak menambah rute apa pun. Ia memanggil openNextWorker.fetch, dan bila response.headers memuat s-maxage, header itu diganti menjadi public, max-age=0, must-revalidate. worker.ts:8-17¹⁵

⚠️ Penggantian header itu wajib dipertahankan. Header s-maxage=…, stale-while-revalidate=… dari Next.js membuat browser menyajikan halaman dari build sebelumnya setelah deploy, sementara chunk CSS lama sudah tidak ada dan permintaannya berakhir 404. Revalidasi setiap kunjungan lebih murah karena ETag mengubahnya menjadi 304.

Peran next.config.ts

Konfigurasi Next hanya berisi redirects, tanpa rewrites atau headers. Peta itu mempertahankan tautan lama: /ibtida dan /praktik menuju /pemula, /tartil dan /belajar menuju /lanjutan, sementara /quran, /daftar, /admin/:path*, dan /login dialihkan ke beranda karena pembaca Qur'an mandiri, pendaftaran kelas, dan area admin sudah tidak ada. next.config.ts:9-27¹⁶ Karena semua tujuan redirect berada di dalam rute yang diprerender, tidak ada rute dinamis yang perlu dijaga tetap hidup. Gambaran menyeluruh tentang isi situs ada di Ringkasan Proyek, dan langkah menjalankan build serta deploy dibahas di Pengujian dan Deploy.