> ## Documentation Index
> Fetch the complete documentation index at: https://belajarkoding.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Arsitektur

> Pahami struktur folder, model rendering, dan alur utama auth, billing, webhook, serta data access di KilatKoding.

## Struktur folder utama

| Path                   | Fungsi                                                                                               |
| ---------------------- | ---------------------------------------------------------------------------------------------------- |
| `app/`                 | Route App Router, layout, dan API route                                                              |
| `components/`          | Komponen reusable aplikasi                                                                           |
| `components/ui/`       | Primitive shadcn/ui                                                                                  |
| `config/`              | Konfigurasi terpusat untuk site, navigasi, pricing, preset desain, roadmap, status, dan open startup |
| `content/blog/`        | Postingan blog MDX                                                                                   |
| `emails/`              | Template React Email                                                                                 |
| `hooks/`               | Hook client seperti auth, payment, subscription, dan AI chat                                         |
| `lib/`                 | Helper bersama, integrasi, SEO, validations, rate limit                                              |
| `lib/data/`            | Data access layer untuk profile, payments, subscriptions, admin, audit, webhook events               |
| `lib/payments/`        | Integrasi Midtrans dan Doku                                                                          |
| `lib/ai/`              | Provider, middleware, dan usage tracking AI                                                          |
| `lib/storage/`         | Avatar storage helpers                                                                               |
| `supabase/migrations/` | SQL migration                                                                                        |
| `tests/`               | Unit test, DOM test, dan route test                                                                  |
| `e2e/`                 | Playwright smoke test                                                                                |

## Cara aplikasi ini dibagi

### Route groups

* `app/(marketing)/` untuk halaman publik.
* `app/(dashboard)/` untuk area user yang login.
* `app/auth/` untuk alur autentikasi.

Route group memakai tanda kurung, jadi nama foldernya tidak masuk ke URL.

## Model rendering

* Server components adalah default.
* Client components dipakai untuk form interaktif, switcher tema, design switcher, chart, dan hook browser.
* Supabase browser client dibuat di `lib/supabase/client.ts`.
* Supabase server client dibuat per request di `lib/supabase/server.ts`.

## Alur auth

1. User membuka halaman auth.
2. Form client memanggil Supabase auth.
3. `proxy.ts` dan `lib/supabase/proxy.ts` me-refresh session cookie pada request berikutnya.
4. Route yang dilindungi seperti `/dashboard` dan `/admin` memeriksa user login.
5. `/admin` juga memeriksa role admin dari `user_roles`.

## Alur billing dan pembayaran

1. User memilih plan di dashboard billing.
2. Client memanggil `POST /api/payments`.
3. Server mengambil harga dari `config/subscriptions.ts`.
4. Server membuat record `payments` dengan status `PENDING`.
5. Server mengembalikan Snap token Midtrans atau checkout URL Doku.
6. Webhook provider masuk ke route webhook terkait.
7. Route webhook memverifikasi signature, mencatat event, lalu mengaktifkan subscription saat pembayaran sukses.

## Alur webhook yang tahan retry

Webhook Midtrans dan Doku tidak langsung mengubah data tanpa pengaman. Repo ini memakai:

* tabel `webhook_events`,
* RPC claim idempotent,
* status `processed` atau `failed`,
* audit log untuk jejak pemrosesan.

Itu berarti retry provider tidak otomatis membuat data ganda.

## Alur profile dan avatar

1. User meminta signed upload URL ke `POST /api/profile/avatar`.
2. File di-upload ke bucket `avatars`.
3. User menyimpan referensi avatar lewat `POST /api/profile`.
4. Jika avatar lama diganti, object lama ikut dibersihkan.

## Data access layer

Repo ini tidak menaruh semua query langsung di route file. Banyak akses data dipisah ke `lib/data/*`, misalnya:

* `payments.ts`
* `subscriptions.ts`
* `profiles.ts`
* `admin.ts`
* `audit-logs.ts`
* `webhook-events.ts`
* `user-roles.ts`

Pola ini memudahkan testing dan memisahkan logika bisnis dari layer route.

## Rate limiting

Public form, payment, dan AI memakai `lib/rate-limit.ts`.

* Jika `SUPABASE_SERVICE_ROLE_KEY` tersedia, repo memakai backend rate limit persisten di Supabase.
* Jika tidak, repo fallback ke in-memory store lokal.
* Response membawa header `X-RateLimit-*`.

## Kapan halaman ini berguna

Halaman ini penting saat kamu:

* ingin refactor folder,
* ingin menambah route baru,
* ingin memahami mengapa session auth tetap sinkron,
* ingin men-debug billing atau webhook.