Everprompt Design

# EverPrompt — Design Specification

**Prompt Intelligence System**

> Non una notes app con AI. Un sistema che trasforma ogni prompt in un asset versionato, valutabile, migliorabile e recuperabile semanticamente.

**Date**: 2026-03-31
**Status**: Approved
**Version**: 1.0

---

## Table of Contents

1. [Identity & Stack](#1-identity--stack)
2. [Data Model](#2-data-model)
3. [AI Pipeline & Orchestration](#3-ai-pipeline--orchestration)
4. [Search System](#4-search-system)
5. [API Design](#5-api-design)
6. [UI/UX Design](#6-uiux-design)
7. [Claude CLI Plugin](#7-claude-cli-plugin)
8. [Project Structure & Deployment](#8-project-structure--deployment)
9. [Versioning Roadmap](#9-versioning-roadmap)

---

## 1. Identity & Stack

**Name**: EverPrompt
**Tagline**: Your prompts, forever better.

Three souls in one product:

- **Intelligent archive** — store, organize, find prompts
- **AI critic** — score, judge, improve prompts automatically
- **Semantic retrieval engine** — find prompts by meaning, not just keywords

### Technology Stack

| Layer | Technology | Role |
|-------|-----------|-------|
| Frontend | React 19 + TypeScript + Vite | SPA |
| Routing | React Router v7 | Client-side routing |
| State | Zustand (UI) + TanStack Query v5 (server) | State management |
| UI Kit | shadcn/ui + Radix + Tailwind CSS v4 | Component system |
| Animations | Framer Motion | Micro-interactions, transitions |
| Charts | Recharts | Dashboard metrics |
| Layout | react-resizable-panels | Resizable panels |
| Command | cmdk | Command palette |
| Editor | Monaco Editor | Prompt body editing |
| Table | TanStack Table v8 | List/table view |
| Notifications | Sonner | Toast notifications |
| Icons | Lucide React | Consistent iconography |
| Backend | Hono + Zod | API framework |
| ORM | Drizzle ORM | Type-safe SQL |
| Runtime (prod) | Cloudflare Workers | Edge compute |
| Runtime (dev) | Bun | Dev server + tooling |
| DB | Cloudflare D1 (SQLite) | Source of truth |
| Search | Cloudflare Vectorize | Semantic search |
| Embeddings | Workers AI (`bge-base-en-v1.5`) | Vector generation |
| AI Analysis | Claude API (Haiku + Sonnet) | Scoring, judgment, improvement |
| Object Store | Cloudflare R2 | Attachments, exports |
| Cache | Cloudflare KV | Cache facets, dashboard |
| Queue | Cloudflare Queues | Async AI pipeline |
| Auth | Cloudflare Zero Trust | Access protection |
| Plugin | Claude CLI Plugin (hook) | Prompt capture |

### Design Decisions

- **D1 as source of truth**: consistent, SQL, PITR 30 days. KV is eventual-consistent so never used for core data.
- **Vectorize for semantic search**: native CF, metadata filtering, no external vector DB needed.
- **Claude API hybrid**: Haiku for fast classification (cheap), Sonnet for quality analysis (accurate). Workers AI only for embeddings.
- **No RAG on R2**: prompts are short/medium text, directly embeddable. R2 is only for attachments/exports/snapshots.
- **Queues for async pipeline**: non-blocking UX, automatic retries, no Durable Objects complexity.

---

## 2. Data Model

### Entity Relationship