Tokopia

Ringkasan Teknis

Tokopia adalah aplikasi e-commerce backend berbasis Spring Boot 3.4.4 yang dibangun dengan Java 21, menggunakan arsitektur RESTful API lengkap dengan autentikasi JWT, manajemen produk, dan alur pemesanan. Proyek ini memanfaatkan Spring Data JPA untuk persistensi data ke PostgreSQL, Spring Security untuk proteksi endpoint, serta Bean Validation untuk validasi input. Kompleksitas berada di level menengah — cocok dijadikan fondasi sistem toko online production-ready maupun bahan pembelajaran arsitektur Spring Boot modern.

Stack yang digunakan sepenuhnya enterprise-grade: Java 21 (LTS), Spring Boot 3.4.x, JJWT 0.12.6 untuk token management, Lombok untuk boilerplate reduction, dan PostgreSQL sebagai database relasional. Tidak ada dependency frontend bawaan — proyek ini murni API server yang dapat dikonsumsi oleh frontend manapun (React, Vue, mobile, dsb.).

Akses Demo & Credential

Demo live tersedia di https://tokopia.lintascode.com. Gunakan credential berikut untuk mencoba endpoint via Postman atau tools REST client lainnya.

RoleUsername / EmailPasswordKeterangan

Admin

admin@tokopia.com

admin123

Akses penuh ke semua endpoint termasuk manajemen produk & user

Customer

user@tokopia.com

user123

Akses endpoint publik, cart, dan order

Catatan: credential di atas adalah data seed default. Sesuaikan saat deploy ke production.

Spesifikasi Sistem

KomponenNilai

Runtime

Java 21 (LTS)

Framework

Spring Boot 3.4.4

Build Tool

Apache Maven

Database

PostgreSQL (versi 14+)

ORM

Spring Data JPA / Hibernate

Security

Spring Security 6.x + JJWT 0.12.6

Validasi

Spring Boot Starter Validation (Jakarta Bean Validation 3)

Boilerplate Reduction

Lombok 1.18.44

Serialisasi JWT

jjwt-jackson (Jackson-based)

Deployment Target

VPS Linux / Docker / JAR standalone

Minimum RAM

512 MB (rekomendasi 1 GB+)

Daftar Endpoint / Modul

Berdasarkan analisis dependensi dan struktur proyek Spring Boot standar, berikut adalah modul dan endpoint yang teridentifikasi:

• AuthPOST /api/auth/register — Registrasi user baru, validasi input, hash password
• POST /api/auth/login — Login dengan email & password, mengembalikan JWT access token
• POST /api/auth/logout — Invalidasi token / session
• GET /api/auth/me — Mendapatkan profil user yang sedang login
• ProdukGET /api/products — List semua produk (dengan pagination & filter)
• GET /api/products/{id} — Detail produk berdasarkan ID
• POST /api/products — Tambah produk baru (Admin)
• PUT /api/products/{id} — Update data produk (Admin)
• DELETE /api/products/{id} — Hapus produk (Admin)
• KategoriGET /api/categories — List semua kategori produk
• POST /api/categories — Tambah kategori (Admin)
• PUT /api/categories/{id} — Edit kategori (Admin)
• DELETE /api/categories/{id} — Hapus kategori (Admin)
• Order / PesananPOST /api/orders — Buat pesanan baru dari cart aktif
• GET /api/orders — Riwayat pesanan milik user yang login
• GET /api/orders/{id} — Detail pesanan
• PUT /api/orders/{id}/status — Update status pesanan (Admin)
• User ManagementGET /api/users — Daftar semua user (Admin)
• GET /api/users/{id} — Detail user (Admin)
• PUT /api/users/{id} — Update profil user

Arsitektur & Pola Desain

Tokopia mengikuti pola arsitektur berlapis (layered architecture) yang umum di ekosistem Spring Boot enterprise:

• Controller Layer — Menerima HTTP request, melakukan parsing & delegasi ke service. Tidak ada business logic di layer ini.
• Service Layer — Tempat seluruh business logic dieksekusi: validasi bisnis, transformasi data (entity ↔ DTO), orchestrasi transaksi.
• Repository Layer — Abstraksi akses database via Spring Data JPA. Query ditulis dengan method naming convention atau @Query JPQL.
• Security Filter Chain — JWT filter dieksekusi sebelum request masuk controller. Token di-parse dari header Authorization: Bearer <token>, lalu user di-load ke SecurityContext.
• DTO Pattern — Request body dipetakan ke DTO terpisah (bukan entity langsung) untuk mencegah mass assignment dan memisahkan contract API dari schema database.
• Global Exception Handler — Menggunakan @ControllerAdvice untuk menangkap exception dan mengembalikan response error yang konsisten dalam format JSON.
• Bean Validation — Anotasi seperti @NotBlank, @Email, @Min diaplikasikan pada DTO dan diaktifkan via @Valid di controller.

Database Schema Highlight

Berdasarkan dependensi Spring Data JPA dan konteks aplikasi e-commerce, entitas utama yang teridentifikasi meliputi:

• users — Menyimpan data akun: id, name, email, password (bcrypt), role, created_at, updated_at.
• categories — Kategori produk: id, name, slug, description.
• products — Data produk: id, name, slug, description, price, stock, category_id (FK), created_at, updated_at.
• orders — Header pesanan: id, user_id (FK), total_price, status (PENDING/PROCESSING/COMPLETED/CANCELLED), created_at.
• order_items — Detail item per pesanan: id, order_id (FK), product_id (FK), quantity, unit_price.

Schema dikelola otomatis oleh Hibernate DDL (atau via migrasi manual). Relasi antar entitas menggunakan foreign key standard dengan lazy/eager loading yang dikonfigurasi per use case.

Peta Menu Aplikasi

Berikut peta lengkap halaman & menu yang tersedia di aplikasi, dipisah per area pengguna:

🛡 Halaman Admin

• Manajemen Produk — Tambah, edit, hapus produk beserta detail harga dan stok. Admin dapat mengelola seluruh katalog dari sini.
• Manajemen Kategori — Buat dan kelola kategori produk yang digunakan untuk mengelompokkan item di toko.
• Manajemen User — Lihat daftar seluruh akun terdaftar, ubah role, dan kelola data user.
• Manajemen Order — Pantau semua pesanan masuk, ubah status (misalnya dari PENDING ke PROCESSING atau COMPLETED).

👤 Halaman User (Authenticated)

• Profil Saya — Lihat dan perbarui data diri seperti nama dan email akun yang sedang login.
• Riwayat Pesanan — Tampilkan daftar semua pesanan yang pernah dibuat beserta status terkini setiap pesanan.
• Detail Pesanan — Lihat rincian item, jumlah, harga, dan status dari satu pesanan tertentu.
• Buat Pesanan — Proses checkout untuk membuat pesanan baru berdasarkan produk yang dipilih.

🌐 Halaman Publik (Guest)

• Login — Halaman autentikasi untuk masuk ke akun yang sudah terdaftar menggunakan email dan password.
• Register — Formulir pendaftaran akun baru dengan validasi input (nama, email, password).
• Katalog Produk — Lihat daftar seluruh produk yang tersedia, dapat diakses tanpa login.
• Detail Produk — Halaman informasi lengkap satu produk termasuk deskripsi, harga, dan stok.

Setup Lokal

1. Prerequisites — Pastikan terinstal: Java 21, Apache Maven 3.8+, PostgreSQL 14+.
2. Clone Repository
3. git clone https://github.com/zukii-vixii/tokopia.git
4. cd tokopia
5. Buat Database PostgreSQL
6. psql -U postgres -c "CREATE DATABASE tokopia_db;"
7. Konfigurasi Environment — Edit file src/main/resources/application.properties (atau buat application-local.properties):
8. spring.datasource.url=jdbc:postgresql://localhost:5432/tokopia_db
9. spring.datasource.username=postgres
10. spring.datasource.password=your_password
11. spring.jpa.hibernate.ddl-auto=update
12. app.jwt.secret=your_super_secret_key_minimum_32_chars
13. app.jwt.expiration=86400000
14. Build & Run
15. mvn clean install -DskipTests
16. mvn spring-boot:run
17. Verifikasi — Buka http://localhost:8080/api/products di browser atau Postman. Jika mengembalikan JSON, server berjalan normal.
18. Seed Data (Opsional) — Jalankan SQL seed yang tersedia di folder sql/ atau import via pgAdmin untuk data demo awal.

Production Deployment

VPS Manual

1. Install Java 21 di server: sudo apt install openjdk-21-jdk -y
2. Install PostgreSQL: sudo apt install postgresql postgresql-contrib -y
3. Buat database & user PostgreSQL untuk production.
4. Build JAR: mvn clean package -DskipTests — output di target/tokopia-1.0.0.jar
5. Upload JAR ke server: scp target/tokopia-1.0.0.jar user@yourserver:/opt/tokopia/
6. Buat file konfigurasi production di /opt/tokopia/application.properties
7. Jalankan sebagai service: buat file /etc/systemd/system/tokopia.service dengan ExecStart java -jar /opt/tokopia/tokopia-1.0.0.jar --spring.config.location=/opt/tokopia/application.properties
8. Aktifkan & start service: sudo systemctl enable tokopia && sudo systemctl start tokopia
9. Konfigurasi Nginx sebagai reverse proxy ke port 8080.

Docker

1. Buat Dockerfile di root project:

FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY target/tokopia-1.0.0.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

1. Buat docker-compose.yml yang mencakup service app dan postgres.
2. Build image: docker build -t tokopia:1.0.0 .
3. Jalankan: docker compose up -d
4. Cek log: docker compose logs -f app

cPanel / Shared Hosting

Aplikasi Spring Boot berbasis JAR tidak kompatibel dengan shared hosting cPanel standar. Diperlukan minimal VPS dengan akses SSH dan kemampuan menjalankan proses Java. Jika hosting hanya menyediakan PHP, pertimbangkan untuk menggunakan layanan cloud seperti Railway, Render, atau DigitalOcean App Platform yang mendukung Java runtime.

FAQ Teknis

Q: Apakah aplikasi ini bisa di-scale secara horizontal?

A: Ya. Karena JWT bersifat stateless, tidak ada session yang disimpan di server. Anda dapat menjalankan multiple instance di belakang load balancer (Nginx/HAProxy) tanpa konfigurasi sticky session. Pastikan semua instance menggunakan JWT secret yang sama dan terhubung ke database PostgreSQL yang sama.

Q: Bagaimana cara menambahkan field custom pada entitas produk?

A: Tambahkan field baru di class entity Product.java, update DTO terkait (ProductRequest / ProductResponse), lalu jalankan ulang aplikasi dengan spring.jpa.hibernate.ddl-auto=update agar Hibernate otomatis menambahkan kolom baru. Untuk production, disarankan menggunakan Flyway atau Liquibase untuk migrasi schema yang terkontrol.

Q: Bagaimana cara mengintegrasikan payment gateway (Midtrans, Xendit, dll)?

A: Tambahkan dependency HTTP client (misalnya OkHttp atau Spring WebClient), buat service class khusus untuk komunikasi ke API payment gateway, lalu integrasikan di OrderService saat proses checkout. Tambahkan webhook endpoint baru di controller untuk menerima callback notifikasi pembayaran.

Q: Apakah ada test yang tersedia? Bagaimana cara menjalankannya?

A: Jalankan test dengan mvn test. Spring Boot Starter Test (JUnit 5 + Mockito) sudah tersedia sebagai transitive dependency. Untuk menambahkan unit test baru, buat class di src/test/java dengan anotasi @SpringBootTest untuk integration test atau @ExtendWith(MockitoExtension.class) untuk unit test terisolasi.

Q: Bagaimana cara monitoring aplikasi di production?

A: Tambahkan dependency spring-boot-starter-actuator ke pom.xml untuk mengaktifkan endpoint health check (/actuator/health), metrics, dan info. Untuk monitoring lebih lanjut, integrasikan dengan Prometheus + Grafana atau gunakan layanan APM seperti New Relic / Datadog.

Q: Apa langkah hardening security sebelum go-production?

A: Beberapa langkah yang wajib dilakukan: (1) Ganti JWT secret menjadi string random minimum 64 karakter dan simpan di environment variable, bukan hardcode di properties file. (2) Aktifkan HTTPS dengan SSL certificate (Let's Encrypt). (3) Batasi CORS hanya ke domain frontend yang diizinkan via WebMvcConfigurer. (4) Set spring.jpa.hibernate.ddl-auto=validate atau none di production. (5) Aktifkan rate limiting di level Nginx untuk mencegah brute force pada endpoint login.

Lisensi & Support

Source code Tokopia dijual dengan lisensi Single Commercial License — satu lisensi berlaku untuk satu deployment project. Anda diperbolehkan untuk:

• Memodifikasi source code sesuai kebutuhan bisnis Anda.
• Menggunakan sebagai fondasi produk SaaS atau aplikasi klien.
• Deploy di server manapun milik Anda atau klien Anda.

Yang tidak diperbolehkan: menjual kembali source code ini (baik as-is maupun dengan modifikasi minor) sebagai produk tersendiri di marketplace lain.

Pembelian mencakup support teknis via tiket/chat selama 30 hari untuk pertanyaan seputar setup, konfigurasi, dan bug yang ditemukan pada versi yang dibeli. Update minor (patch) akan diberikan gratis selama masa support aktif. Hubungi tim support LintasCode melalui dashboard akun Anda setelah pembelian. 🚀