# PromptScale Blueprint // Harvest & Toggl Clone
> Production-grade B2B Time Tracker & Customizable Invoicing Engine. Built with Next.js 14, Supabase/PostgreSQL, TypeScript, and Vitest Two-Gate regression testing.

---

## ⚡ Quickstart: Run Locally in Under 2 Minutes

### 1. Prerequisites
- **Node.js:** `v20.x` or higher
- **Package Manager:** `pnpm` (recommended) or `npm`
- **Database:** Local Docker Postgres OR a free [Supabase](https://supabase.com) project

### 2. Clone & Install
```bash
# Clone the repository
git clone https://github.com/your-username/harvest-clone-promptscale.git
cd harvest-clone-promptscale

# Install dependencies
pnpm install
```

### 3. Configure Environment Variables
Copy the example environment file:
```bash
cp .env.example .env.local
```
Fill in your database URL (must use port 6543 pooler if using Supabase):
```env
DATABASE_URL="postgresql://postgres:password@localhost:5432/harvest_db"
NEXT_PUBLIC_APP_URL="http://localhost:3000"
```

### 4. Run Migrations & Seed Sample Data
```bash
# Apply schema and seed demo workspace, clients, projects & rates
pnpm run db:push
pnpm run db:seed
```

### 5. Launch Development Server
```bash
pnpm run dev
```
Open [http://localhost:3000](http://localhost:3000) in your browser. Default login: `admin@example.com` / `password123`.

---

## 🧪 Testing & Regression Gates

We enforce the **Two-Gate Regression Rule**:
```bash
# Gate 1: Pre-Implementation Green Baseline
pnpm run test:gate1

# Gate 2: Full Integration & Concurrency Check
pnpm run test:gate2
```

To run individual test suites:
```bash
pnpm test                  # Unit tests (Time math, Currency precision)
pnpm run test:integration  # Concurrency & race condition tests
pnpm run test:e2e          # Playwright timer & invoice generation flow
```

---

## 🤖 Feeding This Blueprint to Your AI Coding Agent

If you are generating or extending this codebase with **Cursor, Claude Code, Windsurf, or Devin**:

1. **Step 1:** Open your agent's Planning Mode (or start a fresh chat in Claude Code / Cursor Composer).
2. **Step 2:** Paste the contents of `harvest-time-tracker.plan.md`.
3. **Step 3:** Use this kickoff prompt:
   > *"I have attached the complete PromptScale technical blueprint for the Harvest Clone. We are entering Strict Planning Mode. Review the schema, 200-line modular file limits, and test requirements. Do not write any code until you ask me up to 5 clarifying questions and confirm Phase 1 scope."*
4. **Step 4:** Execute the project strictly phase-by-phase using the prompts in Section 5 of the plan.

---

## 📁 Key Directories & Architecture
- `src/components/timer/`: Live timer display, drift-corrected elapsed time, and idle prompt dialog.
- `src/components/invoices/`: Customizable invoice modal with sequential numbering and printable sheet.
- `src/server/actions/`: Server actions with PostgreSQL row-level locks preventing invoice sequence collisions.
- `src/server/db/schema.ts`: Drizzle ORM definitions with UTC `TIMESTAMPTZ` enforcement.