Getting Started

Selamat datang! Dokumentasi ini akan bantu kamu setup project Soul Map Atlas di local machine.

Prerequisites

• Node.js 20+ (rekomendasi: pakai latest LTS)
• pnpm 9+ (package manager wajib, tidak support npm atau yarn)
• Git
• Cloudflare account — untuk D1 database dan deployment

Quick Start

1. Clone Repository

git clone https://github.com/alphaenano/soul-map-atlas-journey.git
cd soul-map-atlas-journey

2. Install Dependencies

pnpm install

Command ini akan install semua dependencies termasuk global tools (Biome, lefthook, turbo, wrangler).

3. Setup Environment Variables

Copy file .dev.vars.example ke .dev.vars dan isi dengan credentials kamu:

cp apps/api/.dev.vars.example apps/api/.dev.vars

Minimal variable yang harus diisi:

BETTER_AUTH_URL=http://localhost:8787
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

Untuk Google OAuth, daftarkan app di Google Cloud Console dan tambahkan redirect URL: http://localhost:8787/api/auth/callback/google.

4. Setup D1 Database (Local)

cd packages/db
npx wrangler d1 create soul-map-atlas-db --local

Kemudian apply migrations:

npx wrangler d1 migrations apply soul-map-atlas-db --local

5. Generate Worker Types

pnpm run prepare

Command ini akan generate worker-configuration.d.ts via wrangler types.

6. Jalankan Development Server

# Terminal 1: API server
cd apps/api
pnpm run dev

# Terminal 2: Web frontend
cd apps/web
pnpm run dev

# Terminal 3: Docs site
cd apps/docs
pnpm run dev

Atau pakai turbo untuk run semua sekaligus:

pnpm run dev

Development Workflow

Code Formatting

Project pakai Biome sebagai formatter dan linter. Pre-commit hook akan otomatis format staged files:

# Format manual
pnpm biome format --write apps/api/src/index.ts

# Check semua file
pnpm biome check --write .

Git Workflow

Kita pakai branch development untuk development. Task branches dibuat dari development:

git checkout development
git pull origin development
git checkout -b feature/SOUL-XX-short-description

Setelah selesai, push ke remote dan buat MR ke development.

Shortcut: kamu juga bisa kerja langsung di development untuk task kecil (post Plane comment dengan commit hash).

Running Tests

# Type check semua packages
pnpm run typecheck

# Build semua packages
pnpm run build

# Lint semua
pnpm run lint

Project Structure

apps/
  web/          # React + Vite frontend
  api/          # oRPC API backend
  docs/         # VitePress documentation
packages/
  db/           # Drizzle ORM + D1 schema
  auth/         # better-auth config
  email/        # Resend email sender
  payment/      # Doku payment gateway
  shared/       # Types, utilities

Useful Commands

Command	Description
pnpm install	Install semua dependencies
pnpm run build	Build semua packages
pnpm run dev	Jalankan dev server untuk semua apps
pnpm run lint	Lint semua file
pnpm run typecheck	Type check semua packages
pnpm run prepare	Generate worker types dan setup hooks

Troubleshooting

worker-configuration.d.ts tidak ada

Jalankan pnpm run prepare atau cd apps/api && npx wrangler types.

D1 database tidak terhubung

Pastikan:

1. Database sudah dibuat: npx wrangler d1 create soul-map-atlas-db --local
2. Database ID sudah diisi di wrangler.jsonc
3. Migrations sudah di-apply

Build error: "Cannot find module '@packages/db'"

Jalankan pnpm run build di root untuk build internal packages terlebih dahulu.

OAuth callback error

Pastikan redirect URL di Google Console match dengan BETTER_AUTH_URL (termasuk port).

Next Steps

• Baca Architecture untuk paham monorepo structure.
• Baca Tech Stack untuk detail teknologi.
• Baca Data Governance untuk paham business logic.
• Lihat API Docs untuk reference endpoint.

Butuh bantuan? Cek GitHub Issues atau tanya di tim.