OPPE — One-Prompt Product Engine

Describe your idea in one sentence. OPPE builds the full application.

🌐 Languages: English · 中文

OPPE is an AI-driven platform that transforms natural language descriptions into fully functional, tested web applications. It orchestrates a pipeline of specialized AI agents — Planner, Builder, and QA — to break down your idea into features, generate production-ready code, and verify every feature works.

---

How It Works

Your Description → Planner → Builder → QA → Deployable App
                        │         │        │
                   feature list   code    verified

1. Planner — Analyzes your description and generates a structured feature list with dependencies
2. Builder — Implements each feature, generating complete code files (HTML/CSS/JS or Next.js/Vite projects)
3. QA — Verifies each feature using Playwright browser tests and AI code review

The result is a working web application you can download, deploy, or continue iterating on.

---

Tech Stack

Layer	Technology
Framework	Next.js 14 (App Router, TypeScript)
UI	Tailwind CSS + shadcn/ui
Database	SQLite (dev) / PostgreSQL (prod) with Prisma ORM
Auth	NextAuth.js v5 (Credentials + JWT)
AI	Anthropic Claude / OpenAI-compatible APIs
Real-time	Server-Sent Events (SSE)
Testing	Playwright (E2E)

---

Quick Start

Prerequisites

• Node.js ≥ 18
• npm (comes with Node.js)

1. Clone & Install

git clone https://github.com/YOUR_USERNAME/oppe.git
cd oppe
npm install

2. Configure Environment

Copy the example env file:

cp .env.example .env

Edit .env and add your LLM API keys. At minimum, you need:

NEXTAUTH_SECRET=<auto-generated>   # auto-generated by init script
NEXTAUTH_URL=http://localhost:3000
DATABASE_URL="file:../db/dev.db"

# Optional but recommended:
OPPE_ENCRYPTION_KEY=<your-stable-encryption-key>   # keeps API keys safe across secret rotations

⚠️ Never commit .env to version control. It's already in .gitignore.

3. Initialize

# Cross-platform (recommended)
npm run init

# Or platform-specific:
bash init.sh      # macOS / Linux
.\init.ps1        # Windows PowerShell

This will:

• Generate NEXTAUTH_SECRET
• Create the SQLite database
• Run Prisma migrations
• Start the dev server at http://localhost:3000

4. Start Using OPPE

1. Open http://localhost:3000
2. Register an account
3. Go to Settings → configure your LLM API key (Anthropic or OpenAI-compatible)
4. Create a new project and describe your app idea!

---

Project Structure

oppe/
├── app/
│   ├── api/                    # API routes (REST + SSE)
│   │   ├── auth/               # NextAuth endpoints
│   │   ├── projects/           # Project CRUD + agent pipeline
│   │   └── settings/           # User & LLM config management
│   ├── (auth)/                 # Login / Register pages
│   ├── dashboard/              # Project dashboard
│   ├── projects/               # Project detail + build views
│   ├── settings/               # User settings page
│   └── tools/                  # Generated tool runtime
├── components/ui/              # shadcn/ui components
├── lib/
│   ├── ai.ts                   # LLM abstraction (Anthropic + OpenAI)
│   ├── anthropic.ts            # Anthropic SDK wrapper
│   ├── auth.ts                 # NextAuth configuration
│   ├── crypto.ts               # API key encryption (AES-256-GCM)
│   ├── prisma.ts               # Database singleton
│   ├── prompts.ts              # Agent system prompts
│   ├── qa-runner.ts            # Playwright browser verification
│   ├── sandbox.ts              # Docker sandbox for nextjs/vite
│   └── sse.ts                  # Server-Sent Events helpers
├── prisma/
│   ├── schema.prisma           # Data model
│   └── migrations/             # Database migrations
├── prompts/                    # Agent prompt templates
├── docs/                       # Documentation
├── scripts/                    # CLI tools
└── feature_list.json           # Feature specification

---

Configuration

LLM Providers

OPPE supports two LLM backends:

Provider	SDK	Model Examples
Anthropic	@anthropic-ai/sdk	claude-sonnet-4-6, claude-opus-4-1
OpenAI-compatible	openai	gpt-4o, deepseek-chat, any /v1-compatible API

Configure in-app at /settings after logging in.

API Key Encryption

User LLM API keys are encrypted at rest using AES-256-GCM. The encryption key is derived from OPPE_ENCRYPTION_KEY (recommended) or falls back to NEXTAUTH_SECRET. Set OPPE_ENCRYPTION_KEY in your .env for long-term stability.

Tech Stacks

OPPE can generate projects in three modes:

Stack	Description
vanilla	Single-file HTML/CSS/JS — simplest, fastest
nextjs	Next.js 14 app — for complex full-stack apps
vite	Vite + React — modern SPA

---

API Overview

Endpoint	Method	Description
/api/projects	GET/POST	List / Create projects
/api/projects/[id]	GET/PUT/DELETE	Project CRUD
/api/projects/[id]/plan	POST	Trigger Planner (generate feature list)
/api/projects/[id]/build	POST	Trigger Builder (start code generation)
/api/projects/[id]/stream	GET	SSE stream for real-time build progress
/api/projects/[id]/download	GET	Download generated project as ZIP
/api/projects/[id]/clone	POST	Clone an existing project
/api/projects/[id]/records	GET/POST	Tool data records (CRUD for generated tools)
/api/settings/llm-configs	GET/POST	Manage LLM configurations

---

Security

• API Keys: Encrypted with AES-256-GCM before database storage
• Passwords: Hashed with bcrypt (12 rounds)
• Sessions: JWT-based, signed with NEXTAUTH_SECRET
• Rate Limiting: Login brute-force protection
• Input Validation: All API routes use Zod schemas
• File Writing: Path traversal protection via safePath

Reporting Vulnerabilities

Please report security issues privately to the maintainers. Do not open public issues for security vulnerabilities.

---

Contributing

OPPE is designed to be AI-friendly — the AGENTS.md and CLAUDE.md files provide guidance for AI coding assistants working with this codebase.

Development Setup

npm run dev          # Start dev server (http://localhost:3000)
npm run build        # Production build
npx tsc --noEmit     # Type check (run before commits)
npm run lint         # ESLint

Database Changes

# After modifying prisma/schema.prisma:
npx prisma migrate dev --name <description>

Running Tests

# E2E tests (requires dev server running)
npx playwright test

---

License

MIT — see LICENSE file for details.

---

Acknowledgments

Built with:

• Next.js
• Prisma
• Tailwind CSS
• shadcn/ui
• NextAuth.js
• Playwright
• Anthropic & OpenAI