Arsitektur

Pendahuluan

Dokumen ini menjelaskan arsitektur frontend Ravenxcope, arah dependensi antar lapisan, alur inisialisasi runtime, dan keputusan desain penting yang membentuk basis kode.

---

Pola Arsitektur

Frontend mengikuti arsitektur React praktis yang berorientasi pada fitur (feature-oriented). Pohon rute (route tree) dan metadata navigasi dipusatkan di src/app/routes.tsx, tata letak global berada di src/core/layout, kerangka rute/halaman yang dapat digunakan kembali berada di src/core/page, akses data dipusatkan di src/lib/api.ts, dan layar fitur berada di bawah src/modules.

---

Tanggung Jawab Lapisan

Lapisan	File / Folder Utama	Tanggung Jawab
Entri	src/main.tsx	Memasang (mount) React, mengimpor CSS global, inisialisasi i18n
Perutean	src/app/App.tsx, src/app/routes.tsx, src/app/PrivateRoutes.tsx	Mendefinisikan rute publik/privat, metadata rute dasbor, item navigasi, dan guard rute
Tata Letak	src/core/layout/	Shell aplikasi, sidebar, header, dropdown pengguna, pengalih bahasa, drawer seluler, bingkai konten/footer
Kerangka Halaman	src/core/page/	Pembungkus halaman rute, header/toolbar halaman, kartu tabel, status kosong/pemuatan, transisi
UI Fitur	src/modules/{sensors,users,roles,organizations,analytics}	Halaman tingkat rute, partial khusus fitur, dialog, dan sub-alur domain
UI Bersama	src/components/ui/	Button, card, dialog, table, select, sheet, tooltip, dan primitif lainnya
Hook Data	src/hooks/useApi.ts	Hook pengambilan data kecil untuk pembacaan sumber daya umum
Klien API	src/lib/api.ts	Instans Axios, interceptor, grup titik akhir, serialisasi kueri
Auth	src/lib/auth.ts	Pembantu sesi cookie dan pembantu izin
Konfigurasi	src/config/appConfig.ts	Penguraian konfigurasi runtime, validasi, dan pembekuan (freezing)
Tipe	src/types/index.ts	Tipe payload API, entitas, filter, analitik, dan komponen
Lokalisasi	src/i18n.ts, src/locales/	Pengaturan i18next dan katalog pesan

---

Arah Dependensi

Aturan dependensi saat ini:

• Komponen fitur memanggil objek api pusat alih-alih membuat klien Axios ad-hoc.
• apiClient melampirkan token bearer melalui auth.getToken().
• appConfig adalah satu-satunya sumber konfigurasi runtime yang telah dibersihkan.
• Primitif UI Bersama tidak memanggil API backend.
• Tipe dipusatkan di src/types/index.ts, tidak diletakkan bersama per fitur.

---

Inisialisasi Runtime

Urutan boot browser adalah:

1. Pemuatan Bundle: index.html memuat bundle skrip yang telah dibangun dan config.js.
2. Inisialisasi Pengaturan: src/main.tsx mengimpor src/i18n.ts, src/index.css, dan App.
3. Lokalisasi: src/i18n.ts memuat sumber daya Bahasa Inggris dan Bahasa Indonesia, memilih bahasa, dan menyimpan perubahan.
4. Pemasangan Aplikasi: App memasang provider global, router, dan komponen tata letak inti.
5. Auth Guard: Rute dasbor privat memanggil auth.isAuthenticated() sebelum perenderan.
6. Hidrasi Shell: Shell aplikasi dasbor mengambil data pengguna saat ini dan merender navigasi.
7. Pemuatan Fitur: Tampilan fitur mengambil data backend melalui api atau hook kustom.

---

Keputusan Desain Penting

1. Objek API tunggal yang terpusat - src/lib/api.ts mengelompokkan semua panggilan backend berdasarkan domain.
2. Penyimpanan sesi berbasis cookie - Token akses, ID pengguna, dan ID organisasi disimpan melalui js-cookie.
3. Konfigurasi runtime alih-alih build ulang - window.__APP_CONFIG__ memungkinkan perubahan konfigurasi tanpa melakukan build ulang.
4. Hook asinkron manual alih-alih React Query - Aplikasi menggunakan useState dan useEffect untuk pengambilan data.
5. Shell dasbor tingkat rute - /dashboard merender AppShell dengan Outlet bersarang.
6. Bendera fitur (Feature flags) - UI chat AI analitik memeriksa bendera frontend dan status backend.
7. Penanganan respons yang fleksibel - Komponen mentoleransi beberapa bentuk respons selama stabilisasi kontrak.

---

Hutang Arsitektur yang Diketahui

Area	Masalah	Dampak
Komposisi shell aplikasi	AppShell.tsx memusatkan tata letak standar vs workspace	Tetap sebagai satu-satunya batas tata letak global
Organisasi halaman tingkat rute	Halaman rute berada di bawah modules/*/pages	Lanjutkan menjaga orkestrasi di halaman
Tampilan fitur besar	Tampilan analitik memiliki orkestrasi data yang substansial	Fokus pada hook domain untuk ekstraksi lebih lanjut
Chrome halaman yang dapat digunakan kembali	RoutePage dan DataTableCard adalah kerangka standar	Gunakan untuk halaman manajemen baru
Konsistensi tata letak	Halaman daftar menggunakan kerangka tabel bersama	Jaga agar halaman CRUD di masa depan tetap sejajar
Konstanta rute	ROUTES dan dashboardRoutes mencakup navigasi	Pusatkan jalur di src/lib/constants.ts
State/pengambilan data	State server dikelola secara manual	Logika pemuatan/kesalahan yang duplikat
Permukaan API	Semua titik akhir dalam satu api.ts besar	File dengan tingkat perubahan tinggi
Organisasi tipe	Semua tipe domain dalam satu types/index.ts	Lebih sulit untuk dinavigasi
Kontrak respons	Beberapa bentuk respons didukung	Potensi penyimpangan kontrak
Pengujian	Tidak ada rangkaian pengujian frontend khusus	Risiko regresi untuk alur inti