---
name: mimo-backend
description: >
  Backend architecture, API design, and build guidelines for the Mimo personal finance mobile app.
  Activate for: designing endpoints, writing Go/Gin handlers, database schema (GORM), JWT auth,
  AI integration with fallback chain (Groq → OpenRouter → OpenCode), backup/sync features,
  Mimo companion logic, achievement/XP system, N+1 prevention, encryption, and all backend tasks
  related to the Mimo project at d:\Project\mimo.
---

# Mimo Backend Skill

## Project Context

Mimo adalah aplikasi keuangan personal berbasis React Native (Expo) dengan backend Go/Gin.
Semua referensi backend ada di dua dokumen utama di root project:

- `be-setup.md` — Arsitektur, DB schema (GORM), semua API endpoint + request/response examples, mapping screen → endpoint
- `be-build.md` — Best practices: enkripsi, deduplikasi, N+1 prevention, persistent mobile login, caching, rate limiting, dll
- `build-phase.md` — Roadmap dan fase pembangunan backend (Phase 1–5)

Backend folder ada di: `d:\Project\mimo\backend\`

---

## Rules: WAJIB Ikuti Saat Mengerjakan Backend Mimo

### 1. Tech Stack
- Runtime: **Go v1.22+**
- Framework: **Gin** (`github.com/gin-gonic/gin`)
- ORM: **GORM** (`gorm.io/gorm`) dengan driver PostgreSQL
- Auth: **JWT** (`github.com/golang-jwt/jwt/v5`) + **OAuth2** (Google & Apple)
- Validasi: **go-playground/validator** (`github.com/go-playground/validator/v10`)
- Swagger: **swaggo/gin-swagger**
- AI Fallback: Groq → OpenRouter → OpenCode (urutan ini, jangan dibalik)
- Hosting: Heroku

### 2. Struktur Folder Wajib
```
mimo-backend/
├── cmd/main.go
├── internal/
│   ├── handlers/      # *_handler.go
│   ├── services/      # *_service.go
│   ├── models/        # GORM structs
│   ├── middleware/    # auth.go, ratelimit.go, cors.go
│   ├── routes/routes.go
│   └── db/database.go
├── docs/              # swagger auto-generated
├── .env
├── go.mod
└── go.sum
```

### 3. Security Rules (TIDAK BOLEH DILANGGAR)
- Password: **SELALU bcrypt cost 12**, JANGAN plaintext
- Field sensitif (`phone`, `monthlyIncome`): **SELALU AES-GCM enkripsi** sebelum simpan ke DB
- Refresh token: **SELALU simpan SHA-256 hash** di DB, kirim plaintext ke client
- JWT: **SELALU verifikasi signing method** di middleware
- Input: **SELALU validasi** dengan go-validator sebelum proses

### 4. Database Rules
- **WAJIB soft delete** (`gorm.Model` di semua model utama)
- **WAJIB composite unique index** untuk mencegah duplikat (budget per bulan, achievement per user)
- **WAJIB Preload/Joins** — jangan N+1 query
- **WAJIB `Select()` field spesifik** — jangan expose `password_hash`
- **WAJIB context timeout 5 detik** di setiap operasi DB
- **WAJIB Database Transaction** untuk operasi multi-step

### 5. Response Format
Selalu gunakan format ini:
```go
// Success
gin.H{"success": true, "data": ..., "message": "OK"}

// Error
gin.H{"success": false, "error": "ERROR_CODE", "message": "Deskripsi."}
```

HTTP status yang benar:
- `200` GET/update berhasil
- `201` POST create berhasil
- `400` input tidak valid
- `401` belum login / token invalid
- `403` tidak punya akses
- `404` tidak ditemukan
- `409` duplikat data
- `422` validasi gagal
- `429` rate limit
- `500` server error

### 6. Mobile Auth (Login Sekali, Tetap Masuk)
- Access Token: **15 menit**, simpan di memory
- Refresh Token: **90 hari**, simpan di DB (sebagai hash), client simpan di Expo SecureStore
- **WAJIB Refresh Token Rotation** — setiap refresh, token lama di-revoke dan baru diterbitkan
- Logout: revoke refresh token di DB
- Logout All: revoke semua token user di DB

### 7. AI Service Rules
```go
// Urutan fallback WAJIB: Groq → OpenRouter → OpenCode
providers := []AIProvider{groqProvider, openRouterProvider, openCodeProvider}
for _, p := range providers {
    result, err := p.Complete(ctx, prompt)
    if err == nil { return result, nil }
    if isRateLimitError(err) { continue } // coba provider berikutnya
    return nil, err // error lain, stop
}
```

### 8. List Endpoint Rules
- **WAJIB pagination** di semua endpoint yang return list
- Default: `page=1`, `limit=20`, max `limit=100`
- Response wajib include `pagination.total`, `pagination.totalPages`

---

## Endpoint Summary (11 Grup)

| # | Grup | Base Path | Screen |
|---|------|-----------|--------|
| 1 | Auth | `/auth` | Login/Register |
| 2 | User & Profil | `/users/me` | AccountScreen |
| 3 | Transactions | `/transactions` | HomeScreen, TransactionScreen |
| 4 | Analysis | `/analysis` | AnalysisScreen |
| 5 | Budget | `/budgets` | CreateBudgetScreen |
| 6 | Savings Goals | `/savings-goals` | SavingsGoalsScreen |
| 7 | Mimo Companion | `/companion` | AccountScreen |
| 8 | Achievements | `/achievements` | AccountScreen |
| 9 | AI | `/ai` | AIAssistantScreen, AIRecommendationsScreen |
| 10 | Notifications | `/notifications` | HomeScreen |
| 11 | Backup & Sync | `/sync` | AccountScreen |

---

## Cara Baca Dokumen Referensi

Sebelum mengerjakan task backend apapun:

1. Baca `be-setup.md` untuk memahami endpoint yang perlu dibuat
2. Baca `be-build.md` untuk memahami best practices yang harus diikuti
3. Baca `build-phase.md` untuk tahu fase mana yang sedang dikerjakan
4. Jangan duplikat endpoint yang sudah ada
5. Jangan ubah response format dari yang sudah didefinisikan

---

## Model Database yang Sudah Didefinisikan

`User`, `Transaction`, `Budget`, `Wallet`, `SavingsGoal`, `Achievement`, `UserAchievement`, `ChatMessage`, `Notification`, `RefreshToken`

Semua ada di `be-setup.md` section "Database Schema (GORM)".