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

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:

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

Digunakan untuk:

• business logic
• validation
• orchestration

---

3. /server (Backend Layer)

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

Digunakan untuk:

• database access
• heavy logic
• internal backend

---

4. /components

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

---

5. /lib

Utility global:

• prisma instance
• auth helper
• formatter

---

🔄 Data Flow Standard

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