URLKU

Link panjang? Pendekin aja. Bikin link singkat, mudah dibagikan, dan gampang diingat.

URLKU adalah layanan pemendek URL (URL shortener). Kamu tempel URL panjang, lalu URLKU memberimu link pendek seperti https://urlku.com/a8K2x, atau alias pilihanmu sendiri seperti https://urlku.com/toko. Setiap klik tercatat, jadi kamu bisa melihat statistik sederhana.

• Backend: Crystal + Kemal (REST API + redirect)
• Frontend: React + Vite + TypeScript + Tailwind CSS (SPA)
• Database: SQLite (development), siap pindah ke PostgreSQL (production)

Quick start

git clone https://github.com/leeclza/urlku.git
cd urlku
docker compose up --build

Buka http://localhost:8080. Short link dilayani di http://localhost:3000.

---

Daftar isi

1. SKPL singkat
2. Fitur
3. Tech stack
4. Arsitektur
5. Cara setup & menjalankan
6. Environment variables
7. Testing
8. Dokumentasi API
9. Deployment production
10. Rencana pengembangan

---

1. SKPL singkat

Spesifikasi Kebutuhan Perangkat Lunak.

1.1 Tujuan

Menyediakan layanan web untuk mengubah URL panjang menjadi link pendek yang mudah dibagikan, dengan opsi alias sendiri, masa berlaku, dan statistik klik.

1.2 Lingkup

• Aplikasi web (SPA) berbahasa Indonesia untuk membuat dan mengelola link.
• REST API untuk membuat, melihat, menghapus link, dan mengambil statistik.
• Endpoint redirect GET /:short_code yang mengarahkan pengunjung ke URL asli.
• Belum ada sistem akun. Link dikelola per browser lewat manage token (lihat 1.5).

1.3 Pengguna

1.4 Kebutuhan fungsional

1.5 Kebutuhan non-fungsional

1.6 Model data

links                                  clicks
─────────────────────────────          ───────────────────────────
id               PK                    id          PK
short_code       UNIQUE, 3–32          link_id     FK → links.id (CASCADE)
original_url     ≤ 2048                clicked_at
created_at                             referrer    (host saja)
expires_at       NULL = selamanya      user_agent  (kategori perangkat)
click_count      ≥ 0
last_clicked_at                        INDEX (link_id, clicked_at)
manage_token_hash  SHA-256
INDEX (expires_at)

---

2. Fitur

• ✂️ Pemendek URL dengan kode acak yang aman
• 🏷️ Alias custom (urlku.com/toko) dengan validasi dan pesan error yang jelas
• ⏳ Masa berlaku link (1/7/30 hari atau tanggal custom)
• 📊 Statistik: total klik, klik per hari (grafik 30 hari), sumber referrer, perangkat
• 🔳 QR code untuk setiap link (bisa diunduh)
• 🧹 Auto-cleanup link kedaluwarsa & data klik lama
• 📋 Tombol salin dengan feedback "Tersalin!"
• 🗂️ Dashboard link milikmu (disimpan di browser ini)
• 🌗 Dark mode
• 🛡️ Validasi URL anti-SSRF, rate limiting, CORS allow-list, security headers

---

3. Tech stack

---

4. Arsitektur

Browser ──► Frontend SPA (Vite/React, :5173 / :8080)
   │              │  fetch JSON (CORS)
   │              ▼
   └──────► Backend Kemal (:3000) ──► SQLite / PostgreSQL
            ├─ /api/*   REST API
            ├─ /health
            └─ /:code   redirect 302 / halaman 404 / 410

Short URL mengarah ke backend (BASE_URL). Backend yang melakukan redirect, jadi frontend tidak ikut dalam alur klik.

urlku/
├── backend/
│   ├── src/
│   │   ├── app.cr                 # entrypoint (Kemal.run)
│   │   ├── urlku.cr               # wiring: container, middleware, routes
│   │   ├── config/                # Config (ENV), Database (dialect + migrasi)
│   │   ├── controllers/           # LinksController, RedirectController, presenter
│   │   ├── models/                # Link, LinkStats
│   │   ├── repositories/          # LinkRepository, ClickRepository (SQL)
│   │   ├── services/              # LinkService, UrlValidator, AliasValidator,
│   │   │                          # ShortCodeGenerator, RateLimiter
│   │   ├── middleware/            # CORS, rate limit, security headers
│   │   └── utils/                 # errors, http helper, halaman HTML, dotenv
│   ├── db/                        # schema.sqlite.sql, schema.postgres.sql
│   ├── spec/                      # test backend
│   ├── Dockerfile
│   └── shard.yml
├── frontend/
│   ├── src/
│   │   ├── components/            # Logo, Layout, ShortenForm, ResultCard, ClickChart...
│   │   ├── pages/                 # Home, Dashboard, LinkDetail, NotFound
│   │   ├── hooks/                 # useTheme, useCopy, useSavedLinks
│   │   ├── lib/                   # config, validasi, format, storage
│   │   ├── services/api.ts        # REST client
│   │   └── types/
│   ├── public/favicon.svg
│   ├── Dockerfile, nginx.conf
│   └── package.json
├── docker-compose.yml
├── .env.example
└── README.md

Alur request pembuatan link: RateLimitHandler → LinksController#create → LinkService (validasi URL, alias, expiry → generate kode → simpan) → LinkRepository.

Kepemilikan link tanpa akun: saat link dibuat, API mengembalikan manage_token sekali saja. Server hanya menyimpan hash SHA-256-nya. Frontend menyimpan token di localStorage, dan token ini wajib dikirim sebagai header X-Manage-Token untuk menghapus link.

---

5. Cara setup & menjalankan

Opsi A: Docker (paling gampang, disarankan untuk Windows)

Prasyarat: Docker Desktop.

cp .env.example .env        # opsional, default-nya sudah jalan
docker compose up --build

• Frontend: http://localhost:8080
• Backend / short link: http://localhost:3000
• Health check: http://localhost:3000/health

Data SQLite disimpan di volume urlku-data.

Opsi B: Jalankan lokal (development)

Prasyarat

• Crystal ≥ 1.12 + shards
• SQLite3 development library (libsqlite3-dev di Debian/Ubuntu, sqlite di macOS/Homebrew)
• Node.js ≥ 20 + npm

Catatan Windows: Crystal di Windows butuh (1) Developer Mode aktif supaya shards bisa membuat symlink, (2) Visual Studio Build Tools dengan workload Desktop development with C++ (termasuk Windows SDK), dan (3) sqlite3.lib. Kalau belum ada, lebih mudah jalankan backend lewat WSL2 atau Docker: docker compose up backend, lalu frontend tetap jalan dengan npm run dev (set CORS_ORIGIN=http://localhost:5173 di .env root).

1. Backend

cd backend
cp .env.example .env         # sudah berisi config lokal
shards install
crystal run src/app.cr       # atau: shards build && ./bin/urlku

Backend jalan di http://localhost:3000. Tabel dibuat otomatis saat start (lihat Database setup di bawah).

2. Frontend (terminal lain)

cd frontend
cp .env.example .env
npm install
npm run dev

Buka http://localhost:5173.

Database setup

Kamu tidak perlu menjalankan migrasi manual. Saat boot, backend menjalankan db/schema.sqlite.sql atau db/schema.postgres.sql (idempotent, CREATE ... IF NOT EXISTS), tergantung DATABASE_URL:

Repository menulis SQL dengan placeholder ?, yang otomatis diubah menjadi $1, $2, … untuk PostgreSQL.

---

6. Environment variables

Backend (backend/.env)

Frontend (frontend/.env, dibaca saat build)

Root (.env, untuk Docker Compose): BASE_URL, FRONTEND_URL, CORS_ORIGIN, RATE_LIMIT_*, TRUST_PROXY.

---

7. Testing

Backend

cd backend
crystal spec

Cakupan: validasi URL (skema berbahaya, host privat, panjang), short code generator, alias custom & duplikat, rute cadangan, expiration, redirect + click counter, format response API, statistik, hapus dengan token, rate limiting, CORS, dan error JSON.

Frontend

cd frontend
npm test            # Vitest
npm run typecheck   # tsc

Cakupan: render form URL, validasi, berhasil memendekkan (fetch di-mock), error alias terpakai, dan interaksi salin ("Tersalin!").

---

8. Dokumentasi API

Base URL: BASE_URL (default http://localhost:3000). Semua body menggunakan JSON.

Format error

{ "error": "CUSTOM_ALIAS_TAKEN", "message": "Alias tersebut sudah digunakan." }

POST /api/links

Membuat link. custom_alias dan expires_at (RFC 3339) opsional.

{ "url": "https://example.com", "custom_alias": "example", "expires_at": null }

201 Created

{
  "id": 1,
  "short_code": "example",
  "short_url": "http://localhost:3000/example",
  "original_url": "https://example.com",
  "created_at": "2026-09-30T12:00:00Z",
  "expires_at": null,
  "click_count": 0,
  "last_clicked_at": null,
  "status": "active",
  "manage_token": "k1Xh…"
}

manage_token hanya muncul di response ini. Simpan kalau kamu ingin bisa menghapus link.

GET /api/links/:short_code

Detail link: original_url, short_url, created_at, expires_at, click_count, last_clicked_at, status (active/expired). Bentuknya sama dengan response di atas, tanpa manage_token.

GET /api/links?codes=a,b,c

Mengambil hingga 100 link sekaligus (dipakai dashboard). Response: { "links": [ … ] }.

GET /api/links/:short_code/stats

{
  "short_code": "example",
  "short_url": "http://localhost:3000/example",
  "total_clicks": 42,
  "created_at": "2026-09-30T12:00:00Z",
  "expires_at": null,
  "last_clicked_at": "2026-09-30T15:20:11Z",
  "status": "active",
  "clicks_by_date": [{ "date": "2026-09-01", "clicks": 0 }, "… 30 hari …"],
  "referrers": [{ "name": "twitter.com", "clicks": 20 }, { "name": "Langsung", "clicks": 12 }],
  "devices": [{ "name": "mobile", "clicks": 30 }, { "name": "desktop", "clicks": 12 }]
}

GET /api/links/:short_code/qr.svg

QR code (SVG) yang berisi short URL. Dibuat oleh encoder QR murni Crystal (services/qr_code.cr, level koreksi M), tanpa library eksternal. Tambahkan ?download=1 untuk mengunduh sebagai file.

DELETE /api/links/:short_code

Header wajib: X-Manage-Token: <token>. Response 204 No Content, atau 403 FORBIDDEN.

GET /:short_code

• 302 ke URL asli (klik dicatat, Cache-Control: no-store)
• 404 halaman "Link tidak ditemukan."
• 410 halaman "Link ini sudah kedaluwarsa."

GET /health

{ "status": "ok", "version": "1.0.0" }

---

Auto-cleanup

Backend menjalankan job di background (fiber Crystal) secara berkala, jadi server yang sudah di-deploy tetap rapi tanpa perlu perintah manual:

• Link yang sudah kedaluwarsa lebih dari EXPIRED_LINK_RETENTION_DAYS hari dihapus beserta data kliknya, sehingga aliasnya bisa dipakai lagi.
• Data klik detail yang lebih lama dari CLICK_RETENTION_DAYS hari dihapus. Total klik per link tetap tersimpan.

Atur lewat env CLEANUP_INTERVAL_MINUTES (0 = mati). Lihat tabel Environment variables.

---

9. Deployment production

1. Domain: arahkan misalnya urlku.com ke backend (short link) dan app.urlku.com ke frontend. Atau pakai satu domain dengan reverse proxy yang meneruskan /api/*, /health, dan /:code ke backend, dengan halaman SPA di path khusus.
2. Env: BASE_URL=https://urlku.com, CORS_ORIGIN=https://app.urlku.com, FRONTEND_URL=https://app.urlku.com, TRUST_PROXY=true jika berada di belakang Nginx/Caddy/load balancer. Build frontend dengan VITE_API_URL/VITE_BASE_URL yang sesuai (build args di compose).
3. PostgreSQL: set DATABASE_URL=postgres://…. Skema dibuat otomatis saat start.
4. TLS: pasang HTTPS di reverse proxy (Caddy atau Nginx + Let's Encrypt).
5. Skala horizontal: rate limiter bawaan bersifat per-instance. Untuk lebih dari satu instance, buat implementasi RateLimiter berbasis Redis (INCR + EXPIRE) lalu pasang di Urlku::Container.
6. Backup: backup volume urlku-data (SQLite) atau gunakan backup terkelola PostgreSQL.

---

10. Rencana pengembangan

• Akun pengguna (login) sebagai pengganti manage token di browser
• Rate limiter Redis + cache lookup redirect
• Edit URL tujuan dan masa berlaku
• Integrasi daftar hitam domain berbahaya (mis. Google Safe Browsing), tanpa fetch URL tujuan
• Tool migrasi versi skema (saat ini skema bersifat additive/idempotent)
• Custom domain per pengguna
• Ekspor statistik (CSV)