clienthub/.planning/research/STACK.md

Technology Stack — ClientHub Freelancer Client Portal

Project: ClientHub (welcomeclient.iamcavalli.net) Researched: 2026-05-09 Confidence: HIGH

---

Recommended Stack

Core Framework

Technology	Version	Purpose	Why
Next.js	15.x (latest stable)	Full-stack app framework	App Router + Server Actions replace a separate API layer. Vercel-native: no adapter needed. First-class TypeScript.
React	19.x	UI rendering	Bundled with Next.js. Server Components eliminate client-side waterfalls for the read-heavy client portal.
TypeScript	5.x	Type safety	Drizzle + Zod give end-to-end type inference from DB schema to form validation.

Why NOT Remix / SvelteKit / Astro: They work on Vercel but add unfamiliarity overhead with no gain at this scale.

---

Database

Technology	Purpose	Why
Neon (serverless Postgres)	Primary database	Free plan: 0.5 GB storage + 100 CU-hours/month — sufficient for 5–20 clients. Scales to zero between uses. Native Vercel integration that auto-injects DATABASE_URL per preview branch.
Drizzle ORM	DB access + migrations	Lightest-weight TS ORM. Ships drizzle-orm/neon-http serverless driver — no persistent TCP connections, works in Vercel Node and Edge runtimes for free. Schema-as-code with drizzle-kit handles migrations.

Why NOT Prisma: Needs PgBouncer or Prisma Accelerate ($) for serverless connection pooling. Drizzle's neon-http handles this natively at zero cost.

Why NOT Supabase: Adds RLS, Realtime, and Auth overhead you don't need and will have to maintain.

---

Authentication

Technology	Purpose	Why
Auth.js (next-auth) v4	Admin session management	Credentials provider with a single admin account. Session stored as signed JWT cookie. No user table in DB.
Next.js Middleware (custom)	Client secret-link validation	Each client has a secretToken (nanoid, 21 chars) stored in DB. Middleware reads [token] path segment, validates against Neon, returns 404 on miss. Runs at the edge before any page renders.
nanoid	Token generation	Cryptographically secure, URL-safe, 21-char default (~126 bits of entropy). Generated once at client creation.

Auth flow summary:

• /admin/* → Auth.js session required (single admin account)
• /c/[token]/* → Middleware validates token against Neon, 404 on miss
• Client pages: zero auth library overhead

---

UI

Technology	Purpose	Why
Tailwind CSS v4	Utility-first styling	CSS-first configuration, zero runtime overhead.
shadcn/ui	Component library	Components copied into codebase (no runtime dep). Built on Radix UI (accessible). Provides: Badge, Progress, Card, Dialog, Table, Textarea, Select.
lucide-react	Icons	Tree-shaken, SVG-based, consistent.

---

Forms and Validation

Technology	Purpose	Why
Zod	Schema validation	Server-side in Server Actions + client-side with RHF resolver. Single source of truth for data shapes.
React Hook Form	Admin form state	Complex admin forms (client onboarding, task editing, quote builder). Client-facing pages use native <form> + Server Actions.

---

File Handling (v1)

None — document links stored as text fields in Postgres. Eliminates S3, CDN, and upload infrastructure from the initial build entirely.

If direct uploads needed in v2: UploadThing integrates directly with Next.js App Router, free tier (2 GB storage).

---

Infrastructure

Technology	Purpose	Why
Vercel Hobby plan	Deploy + CDN + serverless	Native Next.js. Custom subdomain (welcomeclient.iamcavalli.net) via DNS CNAME. No Docker, VPS, or CI/CD to manage.
Neon Vercel Integration	DB branch per preview	Creates a fresh Neon branch per Git branch automatically. Safe schema migration testing.

---

Installation Sequence

# 1. Bootstrap Next.js
npx create-next-app@latest clienthub --typescript --tailwind --app --src-dir

# 2. Database
npm install drizzle-orm @neondatabase/serverless
npm install -D drizzle-kit

# 3. Auth
npm install next-auth

# 4. Token generation
npm install nanoid

# 5. Validation + Forms
npm install zod @hookform/resolvers react-hook-form

# 6. shadcn/ui
npx shadcn@latest init
npx shadcn@latest add badge button card dialog dropdown-menu input label progress select separator table textarea

---

Key Architectural Decisions

1. Secret-link without Auth.js: Next.js Middleware validates [token] at the edge. Fast, zero client-side JS, 404 on invalid token.
2. Server Actions for all mutations: Task updates, comments, payment status — no REST API layer to maintain.
3. Privacy model is a DB query filter: Admin sees quote_items; clients see only clients.accepted_total. Not a UI filter — a DB design.
4. Two auth systems, zero overlap: Admin JWT cookie on /admin/*. Client token middleware on /c/*.

---

Confidence Levels

Area	Confidence	Notes
Next.js App Router	HIGH	Stable since Oct 2024
Neon free tier	HIGH	0.5 GB storage, 100 CU-hours/month
Drizzle + neon-http	HIGH	Free serverless driver, no connection pooling needed
Auth.js Credentials (admin)	HIGH	Mature, well-documented
nanoid secret tokens	HIGH	Cryptographically secure default
Tailwind v4 + Next.js	HIGH	Stable, PostCSS plugin verified
Vercel Hobby plan	HIGH	Custom subdomain supported