Cardverse API
Cardverse adalah backend API RESTful berkinerja tinggi untuk aplikasi trading card / Pokemon TCG, dibangun menggunakan Go + Gin Framework, PostgreSQL (GORM), JWT Authentication, Refresh Token Rotation, Google OAuth, serta manajemen aset media statis.
Disusun dengan arsitektur per-module (modular monolith) sehingga bersih, teruji (testable), dan mudah dikembangkan secara berkelanjutan.
Aturan penulisan kode, konvensi penamaan, dan clean code best practice ada di
CONVENTION.md.
📁 Struktur Folder Project
cardverse/
├── cmd/
│ ├── api/
│ │ └── main.go # Entry point server HTTP API
│ └── seed/
│ └── main.go # Entry point seeder data master
├── config/
│ └── config.go # Memuat environment variables (.env)
├── internal/
│ ├── database/
│ │ ├── database.go # Koneksi DB PostgreSQL + AutoMigrate GORM
│ │ └── seeder.go # Seed data master (Series, Sets, Cards, Admin)
│ ├── middleware/
│ │ ├── auth.go # Auth middleware (JWT + RequireRoles)
│ │ ├── cors.go # CORS middleware
│ │ ├── logger.go # Request logger dengan auto-redact data sensitif
│ │ └── rate_limiter.go # Rate limiter per-IP (Token Bucket)
│ ├── modules/ # Modular domain features
│ │ ├── auth/ # Login, Register, Google OAuth, Refresh Token, Reset Password
│ │ ├── user/ # Profile, Avatar Upload, Admin User Management
│ │ ├── seriessetmaster/ # Data Master Series & Set Expansion
│ │ └── cardmaster/ # Data Master Kartu TCG (HP, Attacks, Battle, Element)
│ ├── router/
│ │ └── router.go # Pendaftaran route module & static file serving
│ └── pkg/ # Utility & Helper generik
│ ├── response/ # Format JSON response standar + pagination
│ ├── logger/ # Logger terpusat
│ ├── validator/ # Error translator validasi DTO per-field
│ └── utils/ # JWT, Hash Password, String Slug/Underscore, Image/File utils
├── public/ # Penyimpanan Aset Gambar & Media Statis
│ ├── images/
│ │ ├── avatars/ # Foto profil user
│ │ ├── series/ # Banner/gambar Series
│ │ ├── elements/ # Ikon elemen kartu (Grass, Fire, Water, dst)
│ │ ├── evolusi-mega/ # Gambar kartu seri Evolusi Mega
│ │ ├── matahari-bulan/ # Gambar kartu seri Matahari & Bulan
│ │ ├── pedang-perisai/ # Gambar kartu seri Pedang & Perisai
│ │ └── scarlet-violet/ # Gambar kartu seri Scarlet & Violet
├── .env.example
├── CONVENTION.md # Aturan penulisan kode & standar proyek
├── Makefile # Command shortcuts (dev, test, build, seed)
├── go.mod
└── README.md
⚡ Cara Menjalankan
1. Prasyarat
- Go 1.22+
- PostgreSQL
2. Install Dependency
go mod tidy
3. Setup Environment Variables
cp .env.example .env
# Sesuaikan kredensial PostgreSQL (DB_NAME=cardverse), JWT Secret, dan GOOGLE_CLIENT_ID di file .env
4. Buat Database PostgreSQL
Buat database PostgreSQL baru dengan nama cardverse:
psql -U postgres -c "CREATE DATABASE cardverse;"
5. Jalankan Seeder Data Master (Opsional)
go run ./cmd/seed
# atau
make seed
6. Jalankan Server Development
go run ./cmd/api
# atau dengan Hot-Reload (Air):
make dev
Server akan berjalan di http://localhost:8080.
🛠️ Daftar Endpoint API
Server Health Check (/health)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| GET | /health |
❌ Public | Cek status kesehatan server |
1. Authentication Module (/api/v1/auth)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| POST | /api/v1/auth/register |
❌ Public | Registrasi akun baru (Kirim email konfirmasi) |
| POST | /api/v1/auth/login |
❌ Public | Login via email & password (mengembalikan Access & Refresh) |
| POST | /api/v1/auth/google |
❌ Public | Login / Auto-Register via Google OAuth (ID Token) |
| POST | /api/v1/auth/refresh-token |
❌ Public | Minta Access Token baru & rotate Refresh Token |
| POST | /api/v1/auth/logout |
❌ Public | Logout & mencabut Refresh Token |
| POST | /api/v1/auth/verify-email |
❌ Public | Verifikasi email user via token OTP |
| POST | /api/v1/auth/forgot-password |
❌ Public | Minta token/OTP reset password |
| POST | /api/v1/auth/reset-password |
❌ Public | Reset password akun |
2. User Module (/api/v1/users)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| GET | /api/v1/users/me |
✅ Logged In | Ambil profil user yang sedang login |
| PUT | /api/v1/users/me |
✅ Logged In | Update nama profil user |
| POST | /api/v1/users/me/avatar |
✅ Logged In | Upload file gambar avatar (multipart/form-data) |
| GET | /api/v1/users |
🔒 Admin/Superadmin | Get daftar semua user (Paginasi & Search) |
| POST | /api/v1/users |
🔒 Admin/Superadmin | Buat user baru |
| GET | /api/v1/users/:id |
🔒 Admin/Superadmin | Ambil detail user berdasarkan ID |
| PUT | /api/v1/users/:id |
🔒 Admin/Superadmin | Update data user |
| PUT | /api/v1/users/:id/suspend |
🔒 Admin/Superadmin | Suspensikan akun user |
| PUT | /api/v1/users/:id/unsuspend |
🔒 Admin/Superadmin | Cabut suspensi akun user |
| DELETE | /api/v1/users/:id |
🔒 Admin/Superadmin | Hapus user |
3. Series & Set Master Module (/api/v1/series, /api/v1/sets, /api/v1/series-set-masters)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| GET | /api/v1/series |
❌ Public | Get semua Series TCG |
| POST | /api/v1/series |
🔒 Admin/Superadmin | Buat Series TCG baru |
| PUT | /api/v1/series/:id |
🔒 Admin/Superadmin | Update Series TCG & gambar |
| GET | /api/v1/sets |
❌ Public | Get semua Expansion Set (Filter by search/parent_id) |
| GET | /api/v1/sets/code/:code |
❌ Public | Get detail Set berdasarkan set_code (misal M-P) |
| POST | /api/v1/sets |
🔒 Admin/Superadmin | Buat Expansion Set baru |
| PUT | /api/v1/sets/:id |
🔒 Admin/Superadmin | Update Expansion Set & gambar |
| GET | /api/v1/series-set-masters/:id |
❌ Public | Get detail Series/Set Master berdasarkan ID |
| DELETE | /api/v1/series-set-masters/:id |
🔒 Admin/Superadmin | Hapus Series/Set Master berdasarkan ID |
4. Card Master Module (/api/v1/cards)
| Method | Endpoint | Auth | Deskripsi |
|---|---|---|---|
| GET | /api/v1/cards |
❌ Public | Get daftar kartu TCG (Paginasi, Filter & Search) |
| GET | /api/v1/cards/elements |
❌ Public | Get daftar tipe elemen kartu (Fire, Water, Grass, dll) |
| GET | /api/v1/cards/:id |
❌ Public | Get detail kartu TCG berdasarkan ID |
| POST | /api/v1/cards |
🔒 Admin/Superadmin | Buat data kartu master baru |
| PUT | /api/v1/cards/:id |
🔒 Admin/Superadmin | Update data kartu master |
| DELETE | /api/v1/cards/:id |
🔒 Admin/Superadmin | Hapus data kartu master |
🔒 Otentikasi & Header
Untuk endpoint yang memerlukan otentikasi (Auth Required), sertakan Access Token pada HTTP Header:
Authorization: Bearer <ACCESS_TOKEN>
🧪 Menjalankan Unit Test
Proyek ini dilengkapi dengan unit test menyeluruh (menggunakan mock repository tanpa memerlukan database asli saat testing):
# Jalankan semua unit test
go test ./...
# Jalankan test dengan detail & coverage
go test ./... -v -cover
# Shortcut Makefile
make test
📄 Lisensi
© Cardverse Development Team. Hak Cipta Dilindungi Undang-Undang.