A Next.js application for authoring, organizing, sharing, and reusing AI prompts. Users compose prompts from reusable building blocks (pieces like personas, formats, tones, constraints), tag and categorize them, fork community prompts, and target them at specific models (ChatGPT, Claude, Gemini, Midjourney, DALL·E, Stable Diffusion).
Inferred from
prisma/schema.prisma, theapp/(dashboard)route tree (prompts,pieces,library,compose,explore), andlib/actions/*.
- Prompt management — create, edit, version, and rate prompts with rich content, variables (
Jsonfield), and visibility scopes (PUBLIC/PRIVATE/UNLISTED). - Reusable pieces — typed building blocks (
PERSONA,FORMAT,CONSTRAINT,CONTEXT,TONE,CUSTOM) tracked per user with use counts. - Compose workflow — dedicated
/composeroute for assembling prompts from pieces. - Explore & library — browse public prompts (
/explore) and curate your saved set (/library). - Fork tracking — prompts reference a
forked_fromparent and trackfork_count. - Categories & tags — hierarchical
Categorytree (self-referentialparent_id,depth) plus many-to-many tagging viaPromptTag/ReferenceTag. - References & snippets — separate knowledge model (
Reference,Snippet) for docs, skills, agents, patterns, and decisions. - Ratings & analytics —
avg_rating,rating_count,use_count,version_countdenormalized on prompts. - Authentication — credentials (bcrypt-hashed
password_hash) plus GitHub and Google OAuth via NextAuth + Prisma adapter. - Global search & contact form — search server actions (
lib/actions/search.actions.ts) and a public contact page (app/(landing)/contact). - Settings — account/preferences page under
/settings. - File uploads — UploadThing integration.
- Transactional email — Resend with
@react-email/componentstemplates. - Theming — light/dark via
next-themes, animated theme toggle. - Landing page — hero, FAQ, app preview, mobile menu (
app/(landing)/page.tsx). - Health check —
app/healthpage andapp/api/health-runtimeroute.
| Area | Choice |
|---|---|
| Framework | Next.js 16 (App Router, React 19) |
| Language | TypeScript 5 |
| Styling | Tailwind CSS v4 (CSS-native config), tailwind-merge, tw-animate-css |
| UI primitives | Radix UI, shadcn (components/ui), lucide-react, cmdk, sonner |
| Animation | Framer Motion |
| Forms / validation | React Hook Form + Zod (@hookform/resolvers) |
| Server actions | next-safe-action (Zod-typed) |
| Data fetching | Server Components + unstable_cache with tag-based revalidation |
| ORM / DB | Prisma 7 + @prisma/adapter-pg on PostgreSQL 16 |
| Auth | NextAuth v4 + @auth/prisma-adapter, bcrypt for credentials |
| Cache / rate limit | Upstash Redis (@upstash/redis) |
Resend + @react-email/components |
|
| Uploads | UploadThing |
| State | Zustand, nuqs (URL state) |
| Charts | Recharts |
| Logging | Pino (pretty in dev, JSON in prod) |
| Security headers | Nosecone |
| Env safety | @t3-oss/env-nextjs + Zod |
| Testing | Vitest, Testing Library, MSW, Playwright |
| Tooling | ESLint 9 (flat), Prettier, Husky, lint-staged, commitlint |
| Deploy | Netlify (netlify.toml); Vercel-compatible |
app/
(auth)/ # /login, /register — public, centered layout
(dashboard)/ # protected: dashboard, prompts, pieces, library, compose, explore, settings
(landing)/ # marketing: landing page + /contact
api/
auth/[...nextauth]/ # NextAuth catch-all
webhooks/ # generic webhook receiver
health-runtime/ # runtime health probe
health/ # status page
globals.css
layout.tsx
components/
forms/ # form components (e.g. social-auth-buttons)
layout/ # nav config, sidebar, headers
layouts/ # page-level layout wrappers
settings/ # settings UI blocks
ui/ # shadcn primitives
theme-provider.tsx, theme-toggle.tsx
lib/
actions/ # typed Server Actions (auth, prompt, piece, library, search, contact, settings, …)
data/ # cached Prisma reads (cache-tags + unstable_cache)
auth.ts # NextAuth config
db.ts # Prisma singleton
env.ts # validated env vars
logger.ts # Pino
mail.ts # Resend client
markdown.ts # markdown helpers
motion-variants.ts # Framer Motion presets
safe-action.ts # next-safe-action clients (actionClient, authActionClient)
utils.ts # cn, formatDate, slugify
validators.ts # shared Zod schemas
prisma/
schema.prisma # User, Prompt, PromptPiece, Category, Tag, Reference, Snippet, …
migrations/
seed.ts, seed-pieces.ts, seed-prompts.ts
constants/ # ROUTES, settings-config
config/ # app config
hooks/ # custom React hooks
public/ # static assets
scripts/ # utility scripts
types/ # shared TS types
reference/ # internal docs / research notes
docker-compose.yml # Postgres 16 + Redis 7
proxy.ts # request proxy entry (Not واضح from code without further inspection)
Architecture style: modular monolith. Reads and writes are split by directory — lib/data/* for cached queries, lib/actions/* for typed mutations — and the App Router uses route groups ((auth), (dashboard), (landing)) for layout-scoped concerns.
- Node.js 20+
- pnpm (recommended;
pnpm-lock.yamlandpnpm-workspace.yamlare checked in) - Docker (for local Postgres + Redis)
pnpm install
cp .env.example .env.local # fill in secrets
docker compose up -d # start Postgres (5432) and Redis (6379)
pnpm prisma migrate dev # apply schema
pnpm db:seed # optional: seed base data
pnpm db:seed:pieces # optional: seed pieces
pnpm db:seed:prompts # optional: seed promptsFrom .env.example and lib/env.ts:
DATABASE_URL=postgresql://postgres:password@localhost:5432/myapp?schema=public
NEXTAUTH_SECRET=
NEXTAUTH_URL=http://localhost:3000
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=
RESEND_API_KEY=
UPLOADTHING_TOKEN=
NEXT_PUBLIC_APP_URL=http://localhost:3000
lib/env.tsvalidates a subset of these at build time (DB, NextAuth, OAuth, Resend, app URL). Upstash and UploadThing keys are read directly where used.
pnpm dev # http://localhost:3000
pnpm build # runs `prisma generate && next build`
pnpm start # production server| Script | Purpose |
|---|---|
pnpm dev |
Next.js dev server |
pnpm build |
prisma generate then production build |
pnpm start |
Run the built app |
pnpm lint |
ESLint 9 (flat config) |
pnpm db:seed |
Seed base data |
pnpm db:seed:pieces |
Seed prompt pieces |
pnpm db:seed:prompts |
Seed prompts |
pnpm vitest |
Unit/integration tests (per CLAUDE.md) |
pnpm playwright test |
E2E tests (per CLAUDE.md) |
This app is primarily a server-component + Server Actions design — there are few public REST endpoints:
| Path | Purpose |
|---|---|
app/api/auth/[...nextauth] |
NextAuth handlers (sign-in, callbacks, session) |
app/api/webhooks |
Generic webhook receiver |
app/api/health-runtime |
Runtime health probe |
Mutations are exposed as typed Server Actions in lib/actions/:
auth.actions.ts— register, credential sign-in helpersprompt.actions.ts,piece.actions.ts,category.actions.ts,tag.actions.tslibrary.actions.ts— save/unsave to user librarysearch.actions.ts— global searchsettings.actions.ts,user.actions.ts,contact.actions.ts
Each action chains .schema(zodSchema).action(...) and returns { error } on failure or plain data on success. After a write, the action revalidates the relevant cache tag from lib/data/cache-tags.ts.
- Auth gate at the layout —
app/(dashboard)/layout.tsxcallsauth()and redirects to/loginif there is no session, so individual dashboard pages don't repeat the check. - Cached reads, tagged invalidation — every function in
lib/data/*wraps Prisma inunstable_cachewith explicit cache keys and tags. Mutations callrevalidateTag(...)to bust them. - Two safe-action clients —
actionClient(no auth) andauthActionClient(injectsctx.userId). - Singleton Prisma —
lib/db.tsuses theglobalThispattern to survive hot reload. - Validated env at build time — never
process.envin app code; importenvfromlib/env.ts. - Centralized routes — all paths in
constants/routes.ts(ROUTES); never hardcode strings. - Tailwind v4 — no
tailwind.config.ts; tokens live in CSS. Usecn()(lib/utils.ts) for conditional classes. - Snake_case columns, cuid IDs — visible across the Prisma schema (
user_id,created_at,forked_from_id). - Denormalized counters —
avg_rating,rating_count,fork_count,use_count,version_countonPrompt;usage_countonTag. Implies write-side maintenance in actions.
prisma/schema.prismadeclaresprovider = "postgresql"but nourl = env("DATABASE_URL")line — connection URL is presumably wired viaprisma.config.ts. Worth verifying when migrating.- The
Usermodel usespassword_hashdirectly and is not wired to NextAuth'sAccount/Sessiontables, even though@auth/prisma-adapteris installed. Credentials and OAuth users may live in different shapes — Not واضح from code alone whether OAuth provisioning is fully implemented. - No
LICENSEfile is present in the repo. proxy.tsat the root has no obvious caller — Not واضح from code.- E2E and unit test directories (
tests/e2e,tests/unit) are referenced inCLAUDE.mdbut were not located during this scan; tests may not yet be populated.
- Fork and create a feature branch (
feat/...,fix/...— Conventional Commits enforced via commitlint). pnpm install, run the Docker stack, copy.env.example.- Run
pnpm lintand tests before opening a PR. Husky + lint-staged run on commit. - Keep mutations in
lib/actions/*and reads inlib/data/*; updatecache-tags.tswhen adding new resources. - Add new routes to
constants/routes.tsand nav items tocomponents/layout/nav-config.ts.
- Read
CLAUDE.mdfirst — it's the canonical architecture doc. - Start at
app/(dashboard)/layout.tsxto see the auth gate, then follow a feature end-to-end: e.g.app/(dashboard)/prompts/page.tsx→lib/data/prompts.ts(read) →lib/actions/prompt.actions.ts(write) →lib/validators.ts(schema). - When adding a new resource: schema → migration →
lib/data/<x>.ts(with cache tag) →lib/actions/<x>.actions.ts→ route underapp/(dashboard)/<x>/.