FORGE

FORGE — AI Product Engineering workspace yang mengubah ide mentah menjadi structured, build-ready digital products. Dari satu kalimat ide → Knowledge Base → PRD → Tech Spec → Build Tasks → Project Specification Bundle siap dieksekusi AI coding agent (Claude Code, OpenCode, Cursor).

FROM IDEA. TO PRODUCT.

Core Loop

IDEA → AI DISCOVERY → KNOWLEDGE BASE → PRD → TECH SPEC → BUILD TASKS → BUNDLE

• Knowledge Base — single source of truth: keputusan, requirement, constraint. Persistent antar sesi.
• 3-Level Versioning — KB change log, artifact versions, bundle releases. Regeneration selalu proposed diff — tidak ada silent overwrite.
• Universal AI Provider (BYOK) — model-agnostic, protokol OpenAI-compatible, API key terenkripsi server-side (AES-256-GCM).
• Project Specification Bundle — output Markdown + JSON tanpa lock-in: README.md, context/, specs/, tasks/, forge/manifest.json + version.json.

Tech Stack

Layer	Teknologi
Frontend	Next.js 16, React 19, TypeScript, Tailwind CSS 4
3D	Blender → glTF (Draco) → Three.js (RoomEnvironment + Bloom)
Backend	Next.js Route Handlers (business logic di src/server/*, terpisah dari UI)
Database	PostgreSQL 17 + Prisma ORM
Auth	Better Auth (email/password, session cookie)
AI	OpenAI-compatible protocol (BYOK), streaming SSE
Motion	GSAP ScrollTrigger, Lenis smooth scroll

Setup

Prasyarat: Node.js 24+, PostgreSQL 17 berjalan.

npm install
cp .env.example .env          # isi DATABASE_URL, BETTER_AUTH_SECRET, KEY_ENCRYPTION_SECRET
npx prisma db push            # migrasi schema
npm run dev                   # http://localhost:3000

Environment Variables

Variable	Keterangan
DATABASE_URL	Connection string PostgreSQL
BETTER_AUTH_SECRET	Secret session auth (min 32 char)
BETTER_AUTH_URL	Base URL deployment (mis. https://forge.app)
AI_DEFAULT_BASE_URL	Default AI provider (OpenAI-compatible) — opsional
AI_DEFAULT_MODEL	Model default platform
AI_DEFAULT_LABEL	Label default di UI (default: host URL)
AI_DEFAULT_KEY	API key default platform
KEY_ENCRYPTION_SECRET	Master key enkripsi API key user (min 32 char)
PLATFORM_DAILY_LIMIT	Budget harian per user saat pakai default platform (default 50 request)

BYOK-only mode: biarkan AI_DEFAULT_BASE_URL kosong → semua user wajib bawa API key sendiri (provider default di-disable, UI mengarahkan ke menu Providers).

Deploy Produksi (VPS + Docker Compose)

1. Generate secrets:

   openssl rand -hex 32   # BETTER_AUTH_SECRET
   openssl rand -hex 32   # KEY_ENCRYPTION_SECRET
   openssl rand -hex 16   # POSTGRES_PASSWORD

2. Siapkan .env di server (lihat table di atas; BETTER_AUTH_URL = domain publik + HTTPS).
3. Jalankan:

   docker compose up -d --build

   App + PostgreSQL 17 jalan, schema di-migrate otomatis (prisma migrate deploy), health check db aktif sebelum app start.
4. Reverse proxy (Caddy/Nginx) di depan untuk HTTPS. Cookie session otomatis secure di domain https.
5. Update versi: git pull && docker compose up -d --build (data aman di volume forge-db).

Deployment notes

• Mode single-node: rate limiter in-memory cukup. Multi-instance: pindahkan src/server/rate.ts ke Redis.
• Generation AI long-running (2-4 menit per request). Reverse proxy timeout minimal 300s (Caddy: flush_interval -1, Nginx: proxy_read_timeout 300s).
• Password owner pertama: daftar via UI, lalu nonaktifkan pendaftaran publik di src/app/register/page.tsx (hapus form) atau tambahkan flag env jika mau invite-only.

Penggunaan

1. Daftar → dashboard workspace.
2. (Opsional) Providers — tambah API key provider OpenAI-compatible apa pun (BYOK). Tanpa ini, dipakai default platform.
3. + Project Baru — tulis ide satu kalimat.
4. AI Discovery — jawab pertanyaan AI; konteks terekstrak ke Knowledge Base (status proposed, review sebelum confirm).
5. Artifacts — Generate PRD → review → Accept. Lanjut Tech Spec → Build Tasks (butuh artifact sebelumnya di-accept).
6. Release & Download ZIP — bundle siap diberikan ke AI coding agent.

Struktur

src/
├── app/               # route & halaman (UI layer)
│   ├── api/           # route handlers (thin wrapper)
│   └── components/    # komponen UI
├── server/            # business logic (UI-independent)
│   ├── ai/            # provider abstraction (OpenAI-compatible)
│   ├── artifacts.ts   # level-2 versioning
│   ├── bundle.ts      # bundle builder + level-3 releases
│   ├── crypto.ts      # AES-256-GCM BYOK encryption
│   ├── discovery.ts   # chat + context extraction
│   ├── generation.ts  # PRD/TechSpec/Tasks pipeline
│   └── kb.ts          # knowledge base + level-1 change log
└── prisma/schema.prisma

Security

• API key BYOK terenkripsi at-rest (AES-256-GCM), tidak pernah dikirim balik ke client, tidak masuk log.
• Authorization per-resource di API layer (ownership check), bukan client-side.
• SSRF guard pada user-supplied provider Base URL (blok localhost/internal IP).
• Session httpOnly cookie via Better Auth.

Author: Raliq Hidayat BM3