REST API Hono + JWT + Drizzle ORM + SQLite

Proyek REST API modern berkinerja tinggi yang dibangun menggunakan Hono, JWT Authentication, Drizzle ORM, dan SQLite lokal. Arsitektur proyek ini didesain agar mudah dimigrasikan ke Cloudflare Workers + D1 di production tanpa perubahan struktur yang besar.

Dilengkapi dengan dokumentasi interaktif otomatis Swagger UI / OpenAPI 3.0.0 yang mendeteksi setiap penambahan rute baru secara dinamis.

---

Arsitektur

Frontend / Client
       │
       ▼
   Hono API
       │
       ├────────► Swagger UI (/swagger) & OpenAPI Spec (/api/doc)
       ▼
  Drizzle ORM
       │
       ▼
 SQLite (Local Development)  ───►  Cloudflare D1 (Production Ready)

---

Teknologi Utama

• Hono: Framework web ultrafast untuk edge & Node.js.
• Drizzle ORM: TypeScript ORM modern dengan pengetikan statis yang kuat.
• SQLite (better-sqlite3): Database engine lokal yang kompatibel penuh dengan skema Cloudflare D1.
• JWT (jsonwebtoken): Autentikasi berbasis token dengan rotasi refresh token & mekanisme pencabutan (blacklist).
• Password Hashing (bcryptjs): Enkripsi kata sandi yang aman.
• Swagger UI (@hono/swagger-ui): Dokumentasi interaktif otomatis.

---

Struktur Folder

src/
├── db/
│   ├── koneksi.ts           # Koneksi Drizzle ORM & SQLite lokal
│   └── schema-user.ts       # Skema tabel: users, revoked_tokens, user_session_resets
├── middleware/
│   ├── auth.ts              # Middleware validasi JWT, blacklist token & session reset
│   ├── role.ts              # Middleware pembatasan hak akses berbasis role
│   └── index.ts             # Export middleware
├── routes/
│   ├── auth.ts              # Endpoint autentikasi (/api/auth/*)
│   ├── users.ts             # Endpoint manajemen user (/api/users/*)
│   ├── courses.ts           # Endpoint modul kursus (/api/courses)
│   ├── classes.ts           # Endpoint modul kelas (/api/classes)
│   ├── quizzes.ts           # Endpoint modul kuis (/api/quizzes)
│   ├── assignments.ts       # Endpoint modul tugas (/api/assignments)
│   ├── certificates.ts      # Endpoint modul sertifikat (/api/certificates)
│   └── web.ts               # Router utama yang menyatukan seluruh rute di bawah /api
├── utils/
│   ├── jwt-helper.ts        # Helper pembuat & verifikator Access & Refresh Token
│   ├── password-helper.ts   # Helper enkripsi & komparasi kata sandi bcrypt
│   └── openapi-generator.ts # Auto-generator spesifikasi OpenAPI 3.0.0
├── index.ts                 # Definisi Hono app & endpoint Swagger UI
└── server.ts                # Entry point server Node.js untuk lokal dev

---

Cara Menjalankan Proyek dari Awal (Getting Started)

1. Prasyarat (Prerequisites)

Pastikan Anda telah menginstal:

• Node.js (versi >= 20.x direkomendasikan)
• npm

2. Kloning & Instalasi Dependensi

Masuk ke folder proyek dan instal seluruh dependensi:

npm install

3. Konfigurasi Environment (.env)

Salin atau buat file .env berdasarkan .env.example:

cp .env.example .env

Pastikan .env berisi rahasia JWT Anda:

JWT_SECRET=ganti_dengan_rahasia_jwt_anda

4. Inisialisasi Database SQLite

Jalankan sinkronisasi skema database menggunakan Drizzle Kit. Perintah ini akan membuat file ./sqlite.db beserta seluruh tabel (users, revoked_tokens, user_session_resets):

npx drizzle-kit push

5. Menjalankan Server Lokal (Development)

Jalankan server pengembangan berbasis Node.js yang mendukung koneksi SQLite lokal:

npm run dev

Server akan berjalan secara lokal di:

• API URL: http://localhost:3000
• Swagger UI: http://localhost:3000/swagger
• OpenAPI JSON: http://localhost:3000/api/doc

---

Dokumentasi API (Swagger UI Otomatis)

Proyek ini memiliki Auto-Generator OpenAPI 3.0.0 Spec. Setiap kali Anda menambahkan rute baru di aplikasi Hono (misalnya coursesRoutes.post("/")), dokumentasi akan otomatis muncul pada Swagger UI tanpa perlu mengedit file YAML/JSON secara manual.

Buka browser ke: 👉 http://localhost:3000/swagger

---

Daftar Endpoint API

Autentikasi (/api/auth)

Method	Endpoint	Autentikasi	Deskripsi
POST	/api/auth/register	Publik	Pendaftaran akun baru (name, email, password, role?).
POST	/api/auth/login	Publik	Login user, mengembalikan token (Access Token 24j) & refreshToken (7 hari).
GET	/api/auth/me	Bearer JWT	Mengambil profil user yang sedang login saat ini.
POST	/api/auth/refresh-token	Bearer / JSON	Memperbarui Access Token & melakukan rotasi Refresh Token.
POST	/api/auth/logout	Bearer JWT	Logout & mencabut (blacklist) token aktif ke tabel revoked_tokens.
POST	/api/auth/session-reset	Bearer JWT	Mereset seluruh sesi aktif di semua perangkat untuk user terkait.

Manajemen User (/api/users)

Method	Endpoint	Autentikasi & Role	Deskripsi
GET	/api/users	Bearer JWT	Mengambil daftar semua user.
GET	/api/users/:id	Bearer JWT	Mengambil detail user berdasarkan ID.
POST	/api/users	Admin	Membuat user baru (khusus Admin).
PUT	/api/users/:id	Admin	Memperbarui data user (khusus Admin).
DELETE	/api/users/:id	Admin	Menghapus user berdasarkan ID (khusus Admin).

Modul Lainnya

Semua endpoint modul pendukung tersedia di bawah /api/:

• /api/courses
• /api/classes
• /api/quizzes
• /api/assignments
• /api/certificates

---

Hak Akses (Role)

Role	Hak Akses
admin	Full Access (kelola semua data & manajemen CRUD User).
instruktur	Kelola kelas & materi pembelajaran.
mahasiswa	Mengikuti pembelajaran (peran default saat pendaftaran).

---

Alur Autentikasi & Otorisasi

Request
  │
  ▼
JWT Middleware (Validasi Token Bearer & Cek Blacklist Revocation)
  │
  ▼
Role Middleware (Cek Hak Akses Role User)
  │
  ▼
Controller / Handler
  │
  ▼
Database SQLite via Drizzle ORM
  │
  ▼
JSON Response

---

Panduan Migrasi ke Cloudflare Workers + D1

Karena Cloudflare D1 menggunakan SQLite sebagai engine dasar, migrasi ke production sangat mudah:

1. Buat database D1 di Cloudflare dan tambahkan binding pada wrangler.jsonc.
2. Ubah adapter koneksi pada src/db/koneksi.ts:

   import { drizzle } from "drizzle-orm/d1";
   export const db = (env: any) => drizzle(env.DB);

3. Deploy menggunakan perintah:

   npm run deploy

---

Perintah Script Tersedia

• npm run dev: Menjalankan server lokal Node.js + SQLite (tsx watch src/server.ts).
• npm run dev:cf: Menjalankan server pengembangan Cloudflare Workers (wrangler dev).
• npm run deploy: Deploy ke Cloudflare Workers (wrangler deploy --minify).
• npx drizzle-kit push: Sinkronisasi skema ke database lokal (sqlite.db).