clienthub/.planning/research/PITFALLS.md

Pitfalls — ClientHub Freelancer Client Portal

Domain: Freelancer client portal with secret-link access, solo developer, Vercel deploy Researched: 2026-05-09 Confidence: HIGH

---

Critical Pitfalls

1. Secret Links That Are Guessable or Enumerable

What goes wrong: If client tokens are generated from names, sequential IDs, or short strings, they can be enumerated. /client/mario-rossi or /client/3 are not secrets.

Prevention:

• Generate tokens as cryptographically random UUIDs (v4) or nanoid (21 chars / ~126 bits of entropy)
• Never derive from name, company, or sequential ID
• Never log or display full tokens in admin analytics

Warning signs: Client slug contains the client's name. Token under 20 characters. Link can be reconstructed from info the client already knows.

Phase mapping: Phase 1 — data model + routing. Cannot be retrofitted after links are distributed.

---

2. Client API Exposes Admin Data (Hidden in UI Only)

What goes wrong: Developers fetch all client data and conditionally render fields. A technical client opens DevTools and sees the full quote breakdown — the exact thing the product prevents.

Prevention:

• Define two distinct data shapes: ClientView and AdminView
• Client API routes (/api/c/[token]/) return ClientView only — enforced server-side, not in the UI
• accepted_total goes on the clients row. Client API never queries quote_items

Warning signs: Client API response includes lineItems filtered in the frontend. "Client sees only total" enforced with display: none.

Phase mapping: Data model and API shape — Phase 1.

---

3. Data Loss from Vercel Filesystem / In-Memory Storage

What goes wrong: Vercel serverless functions are stateless. File writes to local filesystem and in-memory state are lost between invocations. SQLite on disk silently vanishes after cold start. Bug only manifests in production.

Prevention:

• External persistent DB from day one: Neon (Postgres free tier)
• Never write to fs for persistent data on Vercel
• Validate persistence in the first production deploy

Warning signs: Project stores data in a data/ JSON directory. SQLite without a remote adapter. Data changes in one request not visible in the next.

Phase mapping: Day-one infrastructure decision — Phase 1, before any real data is entered.

---

4. Over-Engineering Before the First Client Uses It

What goes wrong: Building the Claude onboarding flow and quote generator before a single client has opened their dashboard. Real clients still managed via email while the portal is "almost ready."

Prevention:

• Hard success criterion for Phase 1: one client link is shareable and works
• Phase 1 ships read-only client dashboard only
• Collect direct feedback from one real client before adding features

Warning signs: >2 weeks pass without a shareable client link. Claude integration started before admin edit UI exists.

Phase mapping: Enforced by roadmap phase ordering.

---

5. Token Is the Primary Key (Unrotatable)

What goes wrong: A client forwards their link. The link appears in a screenshot. There is no mechanism to rotate without losing data or breaking bookmarks. Worse if token = primary key: rotation requires a migration.

Prevention:

• Data model: stable internal UUID as PK; secret token is a separate, independently updatable field
• Build "Regenerate link" in admin area during Phase 2 — it's a single field UPDATE
• Overwriting the token field is sufficient to invalidate the old link

Warning signs: Token is used as PK of the client record. No admin affordance to regenerate a link.

Phase mapping: Data model separation — Phase 1. Admin rotation UI — Phase 2.

---

6. Client Approval Has No Immutable Record

What goes wrong: Client clicks "Approve." Later: "I never approved that." If approval is a boolean with no timestamp, there is no evidence. Weakens your position in commercial disputes.

Prevention:

• Store approved_at timestamp alongside the approval boolean — from day one
• Display approval timestamp in admin view
• Approvals are immutable for clients — no "undo" button

Warning signs: Approval is a boolean column with no timestamp. Client-visible "undo approval" button exists.

Phase mapping: Schema — Phase 1. Display in admin — Phase 2.

---

Moderate Pitfalls

7. Payment Status Without a Valid State Machine

Payment has three states (da_saldare / inviata / saldato) for two payments. If transitions are not enforced, the dashboard shows contradictory states.

Prevention: Enforce valid transitions: da_saldare → inviata → saldato. Admin UI offers only valid next states.

Phase mapping: Admin UI — Phase 2.

---

8. Google Drive Links That Rot

Document links break when sharing settings change or the Drive account changes. Client sees a broken link to their own deliverable.

Prevention: Store a display name alongside the URL so broken links are visible in admin. Build a simple "update link" affordance in Phase 2.

---

9. Admin Area With No Real Access Control

/admin is a secret route with no authentication. A client who guesses the URL accesses all client data.

Prevention: Add Next.js middleware check against ADMIN_PASSWORD env variable before Phase 2 ships. Never rely on security through obscurity for a route that contains all client data.

Phase mapping: Phase 2, before admin area contains real data.

---

10. Comments Scope Creeping Into Threading

"Clients can leave comments" becomes complex when replies, read/unread state, and notifications are added. Can double Phase 1 scope.

Prevention: Phase 1 ships comments as a flat append-only list per task. No threading, no replies, no email notifications.

---

Minor Pitfalls

11. DNS Configuration as a Last-Minute Task

welcomeclient.iamcavalli.net requires a CNAME to Vercel's DNS. Propagation takes minutes to hours. Doing this the day of a client demo misses the deadline.

Prevention: Configure DNS in Phase 1 before the UI is complete. Verify propagation independently.

---

12. Mobile Responsiveness as an Afterthought

Clients open the link on their phone from a shared message. A broken mobile layout is the first impression.

Prevention: Use Tailwind mobile-first defaults from the start. Test on a real phone before any link is sent.

---

13. No Empty States

A new client record with no tasks shows a blank page. The client assumes something is broken.

Prevention: Design minimal empty states for no-tasks, no-documents, no-comments.

---

Phase-Specific Warnings Summary

Phase Topic	Likely Pitfall	Mitigation
Client token generation	Guessable slug from name	Crypto-random UUID/nanoid, never name-derived
Client-facing API	Admin data in JSON response	ClientView type enforced server-side
Storage choice	Vercel filesystem not persistent	External DB (Neon) before first data write
Admin area access	No real auth	Middleware check before Phase 2 ships
Approval recording	Boolean-only, no audit trail	Store approved_at from day one
Token in data model	Token = PK, unrotatable	Separate stable ID from rotatable token field
Phase ordering	Claude flow before dashboard	Enforce: client view → admin edit → Claude
Comments	Threading scope creep	Flat list in Phase 1
DNS	Last-minute failure	Configure and verify in Phase 1