setrip/ARCHITECTURE.md

# 🚀 SeTrip Project Architecture Guide

## 📌 Overview

Dokumen ini menjelaskan standar struktur project untuk aplikasi **SeTrip** menggunakan Next.js (App Router).

Tujuan:

- Menjaga code tetap rapi & scalable
- Menghindari spaghetti code
- Memudahkan AI / developer kontribusi

---

# 🧠 Core Principles

1. **Feature-based structure (WAJIB)**
2. **Separation client vs server logic**
3. **Colocation (file dekat dengan fitur)**
4. **No over-engineering (keep it simple)**

---

# 🏗️ Project Structure

```bash
src/
├── app/                # Next.js App Router (UI & routing)
│   ├── (public)/       # halaman publik
│   ├── (auth)/         # login/register
│   ├── trips/          # halaman trip
│   ├── create-trip/
│   └── profile/
│
├── features/           # 🔥 Business logic per domain
│   ├── auth/
│   ├── user/
│   ├── trip/
│   ├── booking/
│   └── review/
│
├── server/             # 🔒 Backend-only logic
│   ├── db/
│   ├── services/
│   └── repositories/
│
├── components/         # reusable UI components
│   ├── ui/
│   └── shared/
│
├── lib/                # helpers & utilities
│   ├── prisma.ts
│   ├── auth.ts
│   └── utils.ts
│
├── hooks/              # custom react hooks
├── types/              # global types
└── config/             # config (env, constants)
```

---

# 📂 Folder Rules

## 1. `/app` (Routing Layer)

Hanya untuk:

- page.tsx
- layout.tsx
- UI rendering
- data fetching ringan

❌ DILARANG:

- business logic
- query database langsung

---

## 2. `/features` (Domain Layer) 🔥

Setiap fitur punya folder sendiri:

```bash
features/trip/
├── components/
├── services/
├── hooks/
├── api/
└── types.ts
```

Digunakan untuk:

- business logic
- validation
- orchestration

---

## 3. `/server` (Backend Layer)

```bash
server/
├── db/
│   └── prisma.ts
├── services/
│   └── trip.service.ts
└── repositories/
    └── trip.repo.ts
```

Digunakan untuk:

- database access
- heavy logic
- internal backend

---

## 4. `/components`

```bash
components/
├── ui/        # button, input, modal
└── shared/    # navbar, header
```

---

## 5. `/lib`

Utility global:

- prisma instance
- auth helper
- formatter

---

# 🔄 Data Flow Standard

```text
UI (app/)
  ↓
Feature (features/)
  ↓
Service (server/services)
  ↓
Repository (server/repositories)
  ↓
Database
```

---

# 🧩 Example Flow (Create Trip)

1. User klik create trip (UI)
2. Call feature service
3. Feature validate data
4. Call server service
5. Service call repository
6. Repository insert ke database

---

# ⚠️ Anti-Pattern (DILARANG)

❌ Jangan:

- query Prisma langsung di page.tsx
- campur UI + logic
- buat folder controller/service ala backend di Next.js
- over abstraction di awal

---

# ✅ Best Practice

✔ Gunakan:

- Zod untuk validation
- Prisma untuk ORM
- Server Actions / API route secukupnya

✔ Naming:

- `trip.service.ts`
- `trip.repo.ts`
- `useTrip.ts`

---

# 🚀 Development Phases

## Phase 1 (MVP)

- Auth
- Create Trip
- Join Trip

## Phase 2

- Review
- Limit & validation

## Phase 3

- Payment
- Organizer role

---

## Phase 3+ (SeTrip saat ini — booking, detail, trust)

Alur data mengikuti pola yang sama: **UI (`app/`) → server actions (`features/*/actions.ts`) → service (`server/services`) → repository (`server/repositories`)**.

### Booking & pembayaran manual (`features/booking/`)

- **Peserta:** tombol *Saya sudah bayar* menulis `TripParticipant.markedPaidAt` (komitmen transfer manual).
- **Organizer:** panel *Konfirmasi pembayaran* memanggil service yang mengisi `paymentConfirmedAt`.
- Tetap **tanpa payment gateway**; bukti transfer bisa di luar app (WA) sesuai kebutuhan.

### Detail trip kuat (`Trip` + halaman detail)

- Field terstruktur: `meetingPoint`, `itinerary`, `whatsIncluded`, `whatsExcluded` (teks bebas / bullet).
- Form buat trip: `features/trip/schemas.ts` + `app/create-trip/page.tsx`.

### Trust & organizer (`server/services/trust.service.ts`)

- **Verified Organizer:** dihitung dari `OrganizerVerification.status === "APPROVED"` (lihat `lib/trust.ts → isVerifiedOrganizer()`). Tidak lagi pakai `User.isVerified`.
- **Trip leader:** heuristik `jumlah trip dibuat ≥ TRIP_LEADER_MIN_TRIPS` (`lib/trust.ts`).
- **Jumlah trip dibuat & rating organizer:** dihitung agregat dari DB (rating = rata-rata `TripReview` pada semua trip sang organizer).

### Verifikasi organizer (KYC ringan)

- Model `OrganizerVerification` (1-1 ke `User`) menyimpan KTP (nama, NIK unik, tanggal lahir, alamat), URL foto KTP & selfie, data rekening bank, dan status `PENDING` / `APPROVED` / `REJECTED` + audit reviewer.
- Alur: user submit di `/verify` (`features/organizer/`) → admin review di `/admin/verifications` → setujui/tolak.
- **Gate trip berbayar:** `createTripAction` menolak `price > 0` jika user belum `APPROVED` (`organizerService.isApproved`).
- **Akses admin:** `lib/admin.ts → isAdminEmail()` membaca `ADMIN_EMAILS` (env, comma-separated).

---

# 🧠 Final Principle

> Build fast → validate → refactor later

Jangan terlalu fokus ke arsitektur sempurna di awal.

---

# 📌 Notes for AI / Contributors

- Ikuti struktur ini tanpa pengecualian
- Jangan membuat folder baru tanpa alasan jelas
- Semua fitur baru harus masuk ke `/features`
- Semua akses DB harus lewat `/server`

---

# 📦 Tech Stack (MVP - Ideal)

Project SeTrip menggunakan stack berikut:

## Core

- Next.js (App Router)
- TypeScript
- Tailwind CSS

## Backend & Database

- Prisma (ORM)
- PostgreSQL

## Authentication

- NextAuth

## Validation

- Zod

## Utility

- Axios
- Dayjs
- Clsx
- Bcryptjs

---

# ⚠️ Rules for Dependencies

- Gunakan hanya library yang dibutuhkan untuk MVP
- Hindari menambahkan dependency tanpa alasan jelas
- Jangan install:
  - state management kompleks (Redux, Zustand)
  - realtime (socket.io)
  - queue system
  - payment gateway (di phase awal)

---

# 📌 Philosophy

> Minimal dependencies → faster development → easier maintenance

**End of Document**