# 🏗️ PRODUCTION-GRADE PRD ## AI-Powered Career Optimization Platform **Prepared by:** APEX-PM | **Version:** 1.0 | **Date:** May 2026 --- ## 🎯 SECTION 1: PRODUCT IDENTITY ### 1.1 Product Name & Tagline | Option | Name | Rationale | |---|---|---| | 1 | **LaunchReady** | Action-oriented, implies momentum, broad career appeal, .com likely available as compound | | 2 | **Rolefit** | Crisp, SEO-friendly ("fit for the role"), signals AI matching precision | | 3 | **Careerio** | Playful tech-brand pattern (-io suffix), memorable, internationally neutral | **Recommended:** **Rolefit** > Tagline: *"Apply smarter. Land interviews faster."* --- ### 1.2 Vision Statement In 5 years, Rolefit is the default career intelligence layer that every job seeker uses — the way Grammarly is to writing — making the gap between a qualified candidate and a hired employee purely a function of effort, not access. --- ### 1.3 Mission Statement Rolefit gives every job seeker — regardless of background, network, or writing ability — an AI co-pilot that transforms their experience into a tailored, compelling application for any role in under 5 minutes. --- ### 1.4 North Star Metric **North Star Metric:** Weekly Active Applicants (WAA) — the number of unique users who generate and export at least one tailored application document per week. **Why WAA over alternatives:** - *Signups* measure acquisition, not value delivery - *Documents created* can be gamed by spam users; "exported" means the user found it useful enough to use - *Interview conversion rate* is too lagged and hard to attribute - WAA captures habitual product usage, which directly predicts paid conversion and retention --- ### 1.5 Target Audience — Full Persona #### 🎓 Primary Persona: "The Anxious Graduate" - **Name:** Maya, 23 - **Role:** Recent Computer Science graduate (or liberal arts) - **Company size:** Job seeking — targeting startups to Fortune 500 - **Technical level:** Moderate; comfortable with web apps, no developer skills - **Daily workflow (before Rolefit):** Spends 2–3 hours per application manually rewriting resume bullet points to match each JD, Googles "how to write cover letter for [company]," pastes into ChatGPT with inconsistent results, reformats Word docs until 1 AM - **Top 3 frustrations:** 1. Not knowing if her resume will pass ATS filters — applies and hears nothing 2. Cover letters feel generic even after hours of writing 3. Her LinkedIn "About" section has been blank for 6 months because she doesn't know what to say - **Success looks like:** Getting 3+ interview callbacks in her first month of job searching - **Willingness to pay:** Medium — will pay $12–$20/month if she sees a clear ROI signal (an interview callback) #### 💼 Secondary Persona: "The Frustrated Career Switcher" - **Name:** David, 34 - **Role:** Marketing Manager at a mid-size retail company, targeting Product Management roles at SaaS companies - **Company size:** Currently 300-person company; targeting 50–500 person tech companies - **Technical level:** High business literacy, low technical vocabulary for PM roles - **Daily workflow (before Rolefit):** Knows his experience is transferable but struggles to frame it in PM language; LinkedIn profile still reads like a marketer; has had 3 PM applications ghosted; paying a career coach $250/session - **Top 3 frustrations:** 1. Can't figure out how to translate marketing metrics into PM-relevant impact language 2. Every job description feels different — he can't maintain 12 versions of his resume manually 3. Feels underqualified on paper despite 10 years of relevant experience - **Success looks like:** Landing 2 PM interviews within 6 weeks without paying a career coach - **Willingness to pay:** High — currently spending $500+/month on coaching; $30–$50/month is trivially justifiable --- ## 🔥 SECTION 2: PROBLEM & OPPORTUNITY ANALYSIS ### 2.1 Problem Statement (Layered) | Layer | Statement | |---|---| | **Surface problem** | "I need a better resume and cover letter for this job" | | **Root problem** | Candidates lack the time, vocabulary, and strategic framing ability to present the same experience differently for every unique role — so they send the same generic application everywhere and wonder why they get no responses | | **Emotional problem** | Job searching is a prolonged assault on self-worth. Every application that doesn't get a callback reinforces the belief that "I'm not good enough." The current process is opaque, exhausting, and deeply demoralizing. | --- ### 2.2 Market Opportunity **TAM (Total Addressable Market):** 250M+ global job seekers annually. Career services market valued at ~$28B globally (2025). Online career platform segment: ~$6B. **SAM (Serviceable Addressable Market):** English-speaking digital job seekers (US, UK, Canada, Australia, India) actively applying to roles: ~45M annually. At average $20/month × 3 months active use = ~$2.7B SAM. **SOM (Serviceable Obtainable Market):** In Year 1–2, targeting 0.1% SAM penetration = 45,000 paying users × $20/month × 12 months = **~$10.8M ARR realistic ceiling** in Year 2. **Market timing — Why now:** 1. **AI commoditization of writing** has made generic AI-generated content the norm — the market *needs* a structured, job-specific AI layer, not raw ChatGPT 2. **ATS proliferation**: 98% of Fortune 500 and 75% of SMBs now use ATS — keyword optimization is no longer optional 3. **Remote work normalization** = more competitive applicant pools globally (a NYC role now gets 400+ applicants) 4. **Career switching is at a 20-year high** post-2022 tech layoffs — a massive cohort with transferable skills who need reframing help **Key accelerating trends:** - LinkedIn Premium costs $40–$80/month with limited AI features — price umbrella exists - Gen Z job seekers treat AI tools as default workflow — adoption friction is near zero - "Quiet quitting" → "quiet applying" = high-frequency, serial application behavior --- ### 2.3 Competitive Landscape | Competitor | Core Offering | Pricing | Key Weakness | Our Exploit | |---|---|---|---|---| | **Teal HQ** | Job tracker + resume builder with JD keyword matching | Free / $29/month Pro | Resume builder is rigid; AI suggestions are shallow; no cover letter generation; no LinkedIn optimization | Go deeper on AI output quality; cover all three documents; make LinkedIn a first-class feature | | **Kickresume** | Template-heavy resume + cover letter builder with basic AI | Free / $19/month | Templates are the product — AI is bolted on, not core; no JD analysis pipeline; weak ATS scoring | JD analysis is our core loop, not a feature; ATS score is real-time and actionable | | **Resume.io** | Beautiful resume templates, PDF export | Free / $2.95/week | Zero AI tailoring; purely a formatting tool; no job-application intelligence layer | We're not competing on templates — we're competing on intelligence. User's raw experience → job-specific applications, automatically | --- ### 2.4 Unique Value Proposition (UVP) > *Rolefit is the only career platform that analyzes any job description in real-time and generates a fully tailored resume, cover letter, AND LinkedIn section — optimized for ATS and human readers — in under 5 minutes.* **Feature Differentiation Table:** | Feature | Rolefit | Teal HQ | Kickresume | |---|---|---|---| | Real-time JD analysis & keyword extraction | ✅ Core loop | ⚠️ Basic | ❌ | | AI resume bullet rewriting per JD | ✅ | ⚠️ Shallow | ⚠️ Generic | | AI cover letter generation (JD-tailored) | ✅ | ❌ | ⚠️ Template-based | | LinkedIn About / Headline optimizer | ✅ | ❌ | ❌ | | ATS compatibility score (real-time) | ✅ | ⚠️ Limited | ❌ | | Application tracker with AI follow-up | ✅ Phase 2 | ✅ | ❌ | | Career switch skill-gap analysis | ✅ Phase 2 | ❌ | ❌ | | Multi-document version management | ✅ | ⚠️ | ⚠️ | --- ## 📋 SECTION 3: GOALS, OBJECTIVES & SUCCESS METRICS ### 3.1 Business Goals (SMART — 12-Month Horizon) **Goal 1: Revenue** — Achieve $25K MRR by Month 12 - Why: Validates product-market fit at meaningful scale; qualifies for Seed/Series A conversations **Goal 2: Paying Users** — 1,200 active paid subscribers by Month 12 - Why: A 1,200-user cohort provides statistically significant retention and churn data; forces GTM rigor **Goal 3: Organic Growth** — 35% of new signups from organic/referral by Month 8 - Why: CAC must trend toward zero for a sustainable PLG motion; referral validates delight --- ### 3.2 Product Goals (SMART) | Goal | Definition | Target | |---|---|---| | **Activation Rate** | % of signups who generate ≥1 exported document within 72 hours of signup | ≥55% by Month 3 | | **Day 7 Retention** | % of activated users who return and generate a document in Week 2 | ≥40% | | **Day 30 Retention** | % of activated users still active (≥1 document/week) at Day 30 | ≥25% | | **Core Engagement** | Average documents generated per active user per week | ≥3 docs/week | | **Freemium → Paid Conversion** | % of free users who upgrade within 30 days | ≥8% | --- ### 3.3 KPI Dashboard | KPI | Definition | Target | Tool | Cadence | |---|---|---|---|---| | Weekly Active Applicants (WAA) | Unique users exporting ≥1 doc/week | +15% WoW (early growth) | Mixpanel | Weekly | | Freemium → Paid CVR | Free users converting to paid plan | ≥8% / 30 days | Stripe + Mixpanel | Weekly | | MRR | Monthly Recurring Revenue | $25K by M12 | Stripe | Monthly | | Churn Rate | % paid users cancelling per month | <5%/month | Stripe | Monthly | | Documents Generated / User / Week | Core engagement depth | ≥3 | Mixpanel | Weekly | | ATS Score Improvement | Avg score delta pre/post optimization | ≥25 points | Internal analytics | Weekly | | Time-to-First-Doc | Minutes from signup to first exported document | <8 minutes | Mixpanel | Weekly | | NPS Score | Net Promoter Score via in-app survey at Day 14 | ≥45 | Typeform / PostHog | Monthly | | CAC | Total marketing spend / new paid users | <$25 | Internal / GA4 | Monthly | | LTV:CAC Ratio | LTV (avg revenue × avg lifespan) / CAC | ≥3:1 by M12 | Internal | Quarterly | --- ## 🗺️ SECTION 4: USER STORIES & EPIC BREAKDOWN ### Epic 1 — Onboarding & Authentication **Epic Goal:** Get a user from signup to their first tailored document export in under 8 minutes, collecting enough profile data to power AI generation without friction. **Priority:** P0 (MVP) | ID | User Story | Acceptance Criteria | Effort | Dependencies | |---|---|---|---|---| | US-101 | As a new user, I want to sign up with Google or email so that I can start without filling long forms | ✅ OAuth Google works; ✅ Email/password with verification; ✅ Session persists for 30 days | S | Auth provider (Clerk/Supabase) | | US-102 | As a new user, I want to import my existing resume (PDF/DOCX) so that I don't re-enter my entire work history | ✅ PDF and DOCX accepted; ✅ AI parses into structured profile fields; ✅ User can review and edit parsed data | L | File storage + AI parsing pipeline | | US-103 | As a new user, I want a guided profile setup (5 steps max) so that I can get to document generation quickly | ✅ Max 5 steps; ✅ Progress indicator; ✅ Each step skippable with sane defaults | M | Profile schema | | US-104 | As a user, I want to connect my LinkedIn URL so that Rolefit can suggest improvements to my existing profile | ✅ URL input field; ✅ System scrapes public profile; ✅ Data populates LinkedIn optimizer | M | LinkedIn scraping service | | US-105 | As a returning user, I want to log back in and see my dashboard immediately so that I don't re-onboard | ✅ Login < 2s; ✅ Dashboard shows last 3 documents; ✅ All previous JD analyses preserved | S | Session management | | US-106 | As a user, I want a product tour on first login so that I know what actions to take next | ✅ 4-step interactive tooltip tour; ✅ Dismissible; ✅ Re-accessible from Help menu | S | Frontend only | --- ### Epic 2 — Core Product Loop (JD Analysis → Document Generation) **Epic Goal:** Deliver the core value proposition — paste a JD, get optimized resume + cover letter + LinkedIn section — in one seamless flow. **Priority:** P0 (MVP) | ID | User Story | Acceptance Criteria | Effort | Dependencies | |---|---|---|---|---| | US-201 | As a job seeker, I want to paste a job description URL or raw text so that Rolefit can extract key requirements | ✅ URL scraping works for LinkedIn, Indeed, Greenhouse, Lever, Workday; ✅ Raw text fallback; ✅ Extracted keywords displayed for review | L | JD scraping + AI extraction | | US-202 | As a job seeker, I want to see my ATS match score before and after optimization so that I can quantify the improvement | ✅ Pre-opt score shown immediately after JD analysis; ✅ Post-opt score updates in real-time as bullets are applied; ✅ Missing keywords highlighted | M | Scoring algorithm | | US-203 | As a job seeker, I want AI to rewrite my resume bullet points tailored to the specific JD so that I don't have to do it manually | ✅ Each bullet shows original + AI-suggested version; ✅ User can accept/reject/edit each suggestion; ✅ Suggestions include JD keywords naturally | XL | AI generation pipeline | | US-204 | As a job seeker, I want a fully drafted, JD-tailored cover letter generated in one click so that I have a strong starting point | ✅ Cover letter generated in <15 seconds; ✅ References specific role, company, and JD requirements; ✅ 3 tone options (professional / conversational / assertive); ✅ Editable in rich text | XL | AI generation pipeline | | US-205 | As a job seeker, I want AI-suggested LinkedIn Headline and About section rewrite based on my target role so that I appear as a strong match to recruiters | ✅ Generates new Headline (max 220 chars); ✅ Generates About section (300–500 words); ✅ Shows current vs. suggested diff | L | AI generation pipeline | | US-206 | As a job seeker, I want to export my resume as a formatted PDF or DOCX so that I can submit it directly | ✅ PDF exports in <5 seconds; ✅ DOCX also available; ✅ ATS-safe formatting (no tables, no headers/footers, standard fonts) | M | PDF rendering service | | US-207 | As a job seeker, I want to save each JD analysis as a separate "Application" so that I can manage multiple jobs simultaneously | ✅ Each application saved with company name, role, and date; ✅ Max 3 applications on free plan; ✅ Unlimited on paid | S | Database schema | --- ### Epic 3 — Analytics, Insights & Tracking **Epic Goal:** Give users visibility into their job search performance and give Rolefit the data to improve AI output quality. **Priority:** P1 (Phase 2) | ID | User Story | Acceptance Criteria | Effort | Dependencies | |---|---|---|---|---| | US-301 | As a job seeker, I want an application tracker board so that I can see all jobs I've applied to in one place | ✅ Kanban columns: Saved / Applied / Interview / Offer / Rejected; ✅ Drag-and-drop status update; ✅ Linked to document versions | L | Application schema | | US-302 | As a job seeker, I want to see which keywords I'm consistently missing across applications so that I can improve my base profile | ✅ "Keyword gap report" shows top 10 most commonly missing keywords across last 5 applications | M | Analytics aggregation | | US-303 | As a job seeker, I want to see my ATS score trend over time so that I can measure improvement | ✅ Line chart showing average ATS score per week; ✅ Exportable as PNG | S | Chart library + analytics | | US-304 | As a job seeker, I want AI to suggest which skills to add to my profile based on my target roles so that I can improve my long-term competitiveness | ✅ Top 5 missing skills identified from last 10 JDs analyzed; ✅ Each with a "how to demonstrate this" tip | M | AI + analytics pipeline | | US-305 | As a job seeker, I want to log interview outcomes so that I can track what's working | ✅ Simple outcome logging (got interview / rejected / no response); ✅ System notes which document version was used | S | Application schema | --- ### Epic 4 — Settings, Billing & Account Management **Epic Goal:** Frictionless plan management, transparent billing, and profile control that doesn't interrupt the core product loop. **Priority:** P0 (MVP — billing core; P1 for advanced settings) | ID | User Story | Acceptance Criteria | Effort | Dependencies | |---|---|---|---|---| | US-401 | As a user, I want to upgrade from free to paid with one click so that I'm not blocked by friction when I hit limits | ✅ Upgrade CTA in-context when limits hit; ✅ Stripe Checkout loads in <2s; ✅ Immediate plan activation post-payment | M | Stripe integration | | US-402 | As a paying user, I want to manage or cancel my subscription without contacting support so that I feel in control | ✅ Self-serve cancel in Settings; ✅ Cancellation confirmation with pause option offered; ✅ Stripe Customer Portal integration | S | Stripe Customer Portal | | US-403 | As a user, I want to edit my base profile (work history, skills, education) at any time so that all future documents reflect current experience | ✅ All profile fields editable inline; ✅ Changes trigger notification: "Re-optimize existing documents?" | M | Profile schema | | US-404 | As a user, I want to control data privacy and delete my account if needed so that I trust the platform with my personal data | ✅ Account deletion removes all PII within 72 hours; ✅ Data export (JSON/PDF) available before deletion; ✅ GDPR-compliant | M | GDPR compliance module | | US-405 | As a user, I want to receive email notifications when new job matches are found based on my target roles so that I don't miss opportunities (Phase 2) | ✅ User defines 3 target roles/keywords; ✅ Daily digest email; ✅ Unsubscribe in one click | L | Background jobs + email service | --- ## ⚙️ SECTION 5: TECHNICAL ARCHITECTURE (PRODUCTION-GRADE) ### 5.1 Recommended Tech Stack | Layer | Choice | Rationale | Budget Alternative | |---|---|---|---| | **Frontend Framework** | Next.js 14 (App Router) | SSR for SEO, file-based routing, built-in API routes for BFF pattern, Vercel-native | Remix (slightly steeper learning curve) | | **UI Component Library** | shadcn/ui + Tailwind CSS | Unstyled composable components, zero vendor lock-in, Tailwind utility-first speed | Chakra UI (heavier bundle) | | **State Management** | Zustand + React Query (TanStack) | Zustand for global UI state (auth, modals); React Query for server state, caching, optimistic updates | Redux Toolkit (overkill for MVP) | | **Backend Framework** | Node.js + Hono (or Next.js API routes for MVP) | Hono is ultra-lightweight, edge-compatible, TypeScript-first; scales to separate service later | Express.js (MVP only) | | **API Architecture** | tRPC | End-to-end type safety from DB to frontend with zero schema duplication; ideal for TypeScript monorepo | REST with Zod validation | | **Authentication** | Clerk | Handles OAuth, email/password, session management, user metadata, webhooks — production-ready in hours | Supabase Auth (free tier) | | **Primary Database** | PostgreSQL via Supabase | Relational model fits user/application/document relationships; Supabase adds real-time, auth, storage | PlanetScale (MySQL, serverless) | | **Caching Layer** | Redis via Upstash | Serverless Redis, pay-per-request, cache JD analyses and AI responses to reduce OpenAI costs | In-memory cache (not recommended for prod) | | **File Storage** | Supabase Storage (S3-compatible) | Co-located with DB, simple SDK, handles resume uploads and exported PDFs | AWS S3 directly | | **Search** | PostgreSQL full-text search (MVP) → Typesense (Scale) | FTS sufficient for MVP; Typesense for fast job/document search at scale | Algolia (expensive) | | **Background Jobs** | Inngest | Durable functions for async AI generation, email digests, JD scraping queues; serverless-native | BullMQ + Redis | | **Real-time** | Supabase Realtime | WebSocket-based, already in stack; use for live ATS score updates during editing | Pusher (adds cost) | | **AI/ML Integration** | OpenAI GPT-4o (primary) + Claude claude-sonnet-4-20250514 (fallback/comparison) | GPT-4o for generation; structured outputs via JSON mode; function calling for keyword extraction | Groq (faster, cheaper, less capable) | | **PDF Generation** | Puppeteer (serverless via Browserless.io) | Pixel-perfect PDF rendering from HTML templates; ATS-safe output | React-pdf (less fidelity) | | **Email Service** | Resend + React Email | Developer-friendly, React component-based email templates, reliable deliverability | SendGrid | | **Payment Processing** | Stripe | Industry standard, Stripe Billing for subscriptions, Customer Portal for self-serve | Lemon Squeezy (simpler tax handling) | | **Hosting / Deployment** | Vercel (frontend + API) + Supabase (DB) | Zero-config Next.js deployment, global CDN, preview environments per PR | Railway (full-stack, simpler) | | **CI/CD Pipeline** | GitHub Actions | Free for public repos, native PR checks, deploy previews trigger automatically | CircleCI | | **Monitoring & Logging** | Axiom (logs) + Vercel Analytics | Structured logging, zero cold-start latency impact | Datadog (expensive) | | **Error Tracking** | Sentry | Industry standard, Next.js SDK, source maps, performance monitoring | LogRocket (session replay bonus) | --- ### 5.2 System Architecture Overview **Architecture Pattern: Modular Monolith → Service Extraction** For MVP, Rolefit runs as a **modular monolith** within a Next.js App Router project. All backend logic lives in `/app/api` (tRPC router) and is deployed as Vercel serverless functions. This avoids distributed systems complexity while keeping the codebase organized into clear domain modules: `auth`, `profile`, `jd-analysis`, `generation`, `documents`, `billing`. **Data Flow — Core Loop:** ``` User pastes JD URL/text → Next.js client sends tRPC mutation: jdAnalysis.analyze() → API validates auth (Clerk middleware) → Inngest enqueues background job: SCRAPE_AND_ANALYZE_JD → Inngest step 1: Scrape JD text (Puppeteer/fetch) → Inngest step 2: Send to OpenAI with function calling → structured JSON: {required_skills, nice_to_have, keywords, seniority, culture_signals} → Inngest step 3: Cache result in Upstash Redis (key: hash of JD text, TTL: 7 days) → Inngest step 4: Persist JdAnalysis record to Postgres → Supabase Realtime pushes event to client: "analysis_complete" → Client fetches analysis result, renders ATS score + keyword gaps → User clicks "Generate Documents" → tRPC mutation: documents.generate({ profileId, jdAnalysisId, docTypes: ['resume', 'cover_letter', 'linkedin'] }) → Parallel OpenAI API calls (GPT-4o) with user profile + JD analysis as context → Generated documents streamed back to client via Server-Sent Events → Documents persisted to Postgres; user can edit, then export via PDF generation service ``` **Key Architectural Decisions:** - **Streaming AI responses**: Use OpenAI streaming + SSE to show generation in real-time (users don't wait staring at a spinner — they watch their document being written) - **JD caching**: Same JD pasted by multiple users is only analyzed once (major cost reduction) - **Optimistic UI**: ATS score updates optimistically in the editor before server confirms, preventing perceived lag - **Profile versioning**: User profile snapshots are stored per-application so historical documents remain accurate even after profile edits --- ### 5.3 Database Schema (Core Tables) ```sql -- USERS (managed primarily by Clerk, extended here) users id UUID PRIMARY KEY DEFAULT gen_random_uuid() clerk_id VARCHAR(255) UNIQUE NOT NULL email VARCHAR(255) UNIQUE NOT NULL full_name VARCHAR(255) plan ENUM('free', 'pro', 'career') DEFAULT 'free' stripe_customer_id VARCHAR(255) created_at TIMESTAMPTZ DEFAULT NOW() updated_at TIMESTAMPTZ DEFAULT NOW() -- PROFILES (structured career data) profiles id UUID PRIMARY KEY user_id UUID REFERENCES users(id) ON DELETE CASCADE headline TEXT -- current professional headline summary TEXT -- base professional summary linkedin_url VARCHAR(500) target_roles TEXT[] -- e.g. ["Product Manager", "Senior PM"] target_industries TEXT[] created_at TIMESTAMPTZ updated_at TIMESTAMPTZ -- WORK_EXPERIENCES work_experiences id UUID PRIMARY KEY profile_id UUID REFERENCES profiles(id) ON DELETE CASCADE company VARCHAR(255) NOT NULL title VARCHAR(255) NOT NULL start_date DATE end_date DATE -- NULL if current is_current BOOLEAN DEFAULT FALSE bullets JSONB -- [{id, text, is_active}] sort_order INT created_at TIMESTAMPTZ -- JD_ANALYSES (cached job description breakdowns) jd_analyses id UUID PRIMARY KEY user_id UUID REFERENCES users(id) raw_text TEXT NOT NULL source_url VARCHAR(500) company_name VARCHAR(255) role_title VARCHAR(255) required_skills TEXT[] nice_to_have TEXT[] keywords TEXT[] seniority_level VARCHAR(50) analysis_data JSONB -- full structured AI output text_hash VARCHAR(64) UNIQUE -- for deduplication/caching created_at TIMESTAMPTZ -- APPLICATIONS (a user's application to a specific role) applications id UUID PRIMARY KEY user_id UUID REFERENCES users(id) ON DELETE CASCADE jd_analysis_id UUID REFERENCES jd_analyses(id) profile_snapshot JSONB -- frozen profile at time of application status ENUM('draft','applied','interview','offer','rejected') DEFAULT 'draft' ats_score_before INT ats_score_after INT notes TEXT applied_at TIMESTAMPTZ created_at TIMESTAMPTZ -- DOCUMENTS (generated outputs) documents id UUID PRIMARY KEY application_id UUID REFERENCES applications(id) ON DELETE CASCADE user_id UUID REFERENCES users(id) type ENUM('resume','cover_letter','linkedin_about','linkedin_headline') content TEXT NOT NULL -- final rendered content (markdown/HTML) content_delta JSONB -- diff from base profile content version INT DEFAULT 1 exported_at TIMESTAMPTZ -- NULL until exported storage_path VARCHAR(500) -- path in Supabase Storage for PDF created_at TIMESTAMPTZ -- SUBSCRIPTIONS subscriptions id UUID PRIMARY KEY user_id UUID REFERENCES users(id) ON DELETE CASCADE stripe_sub_id VARCHAR(255) UNIQUE plan ENUM('pro','career') status ENUM('active','past_due','cancelled','trialing') current_period_end TIMESTAMPTZ cancelled_at TIMESTAMPTZ created_at TIMESTAMPTZ ``` --- ### 5.4 API Endpoints (Core Routes) | Method | Route | Description | Auth | Request Body | Response | |---|---|---|---|---|---| | `POST` | `/api/trpc/auth.getSession` | Validate and return current session | ✅ | — | `{user, profile, plan}` | | `POST` | `/api/trpc/profile.upsert` | Create or update user profile | ✅ | `{headline, summary, targetRoles, ...}` | `{profile}` | | `POST` | `/api/trpc/profile.importResume` | Parse uploaded PDF/DOCX into profile | ✅ | `{fileUrl}` (Supabase Storage URL) | `{parsedProfile}` (draft for review) | | `POST` | `/api/trpc/jdAnalysis.analyze` | Submit JD for AI analysis | ✅ | `{text?, url?}` | `{jdAnalysisId, status: 'queued'}` | | `GET` | `/api/trpc/jdAnalysis.getById` | Fetch analysis result | ✅ | `{id}` | `{analysis}` | | `POST` | `/api/trpc/applications.create` | Create new application linked to JD analysis | ✅ | `{jdAnalysisId}` | `{application}` | | `POST` | `/api/trpc/documents.generate` | Trigger AI document generation | ✅ | `{applicationId, docTypes[]}` | `{jobId}` (SSE stream) | | `GET` | `/api/trpc/documents.getByApplication` | Fetch all documents for an application | ✅ | `{applicationId}` | `{documents[]}` | | `PATCH` | `/api/trpc/documents.update` | Save edited document content | ✅ | `{id, content}` | `{document}` | | `POST` | `/api/trpc/documents.export` | Generate PDF/DOCX and return download URL | ✅ | `{documentId, format}` | `{downloadUrl, expiresAt}` | | `GET` | `/api/trpc/applications.list` | List all user applications | ✅ | `{status?, limit, cursor}` | `{applications[], nextCursor}` | | `PATCH` | `/api/trpc/applications.updateStatus` | Update kanban status | ✅ | `{id, status}` | `{application}` | | `POST` | `/api/billing/create-checkout` | Initiate Stripe checkout session | ✅ | `{priceId, planId}` | `{checkoutUrl}` | | `POST` | `/api/billing/webhook` | Stripe webhook handler | ❌ (Stripe sig) | Stripe event payload | `{received: true}` | | `DELETE` | `/api/trpc/users.deleteAccount` | GDPR-compliant account deletion | ✅ | `{confirmEmail}` | `{status: 'queued', deletionAt}` | --- ### 5.5 Security Requirements **Authentication:** Clerk JWTs with RS256 signing. Short-lived access tokens (1hr), long-lived refresh tokens (30 days). All tRPC procedures wrapped in `protectedProcedure` middleware validating Clerk session. **Authorization (RBAC):** - `free` — max 3 applications, 3 documents/application, no export on cover letters - `pro` — unlimited applications, all document types, PDF + DOCX export - `career` — all Pro features + LinkedIn optimizer, keyword gap reports, priority AI queue - All authorization checks performed server-side only; client-side gates are UX only, never security **Data Encryption:** - In transit: TLS 1.3 enforced by Vercel + Supabase; HSTS headers enforced - At rest: Supabase encrypts all database storage (AES-256); Supabase Storage encrypted at rest - PII (resume content, work history): never logged in plaintext; Axiom log sanitization middleware strips profile content from logs **OWASP Top 10 (Application-Specific):** - **A01 Broken Access Control:** Row-Level Security policies on all Supabase tables (`user_id = auth.uid()`) - **A02 Cryptographic Failures:** No sensitive data in localStorage; JWTs in httpOnly cookies via Clerk - **A03 Injection:** tRPC + Zod validation on all inputs; parameterized queries via Prisma/Supabase client - **A05 Security Misconfiguration:** Environment variables audit checklist; no secrets in client bundle (checked via bundle analyzer) - **A07 Identification/Auth Failures:** Rate limiting on auth endpoints (Upstash Rate Limit); account lockout after 5 failed attempts - **A10 SSRF:** JD URL scraping runs in sandboxed Inngest function; allowlist of permitted domains (LinkedIn, Indeed, Greenhouse, Lever, Workday, Ashby); no arbitrary URL fetching **Compliance:** - **GDPR:** Data export (JSON), right to erasure (72hr deletion pipeline), privacy policy, cookie consent banner, DPA available - **SOC2 Type I:** Target Month 9 — begin audit preparation at Month 6 (Vanta for evidence collection) - **CCPA:** Privacy policy covers California residents; opt-out mechanism for data sale (N/A — we don't sell data) --- ### 5.6 Performance Targets | Metric | Target | Measurement | |---|---|---| | LCP (Largest Contentful Paint) | < 2.0s (desktop), < 2.5s (mobile) | Vercel Speed Insights, Lighthouse CI | | CLS (Cumulative Layout Shift) | < 0.05 | Core Web Vitals report | | FID / INP | < 100ms | Real User Monitoring via Vercel | | API p50 response time | < 200ms (non-AI routes) | Axiom | | API p95 response time | < 800ms (non-AI routes) | Axiom | | AI generation start (time to first token) | < 3 seconds | Inngest job metrics | | PDF export generation | < 8 seconds | Sentry performance | | Concurrent users (MVP) | 500 concurrent | Vercel auto-scales | | Concurrent users (Scale) | 5,000+ concurrent | Vercel + Supabase connection pooler (pgBouncer) | | Uptime SLA | 99.5% (MVP) → 99.9% (Scale) | UptimeRobot + Vercel SLA | --- ## 🎨 SECTION 6: UX / PRODUCT DESIGN SYSTEM ### 6.1 Information Architecture **Top-Level Navigation (Authenticated):** ``` Sidebar Nav: ├── 🏠 Dashboard — Activity overview, WAA, recent applications ├── 📋 Applications — Kanban board of all job applications ├── ✍️ New Application — JD input → optimization flow (primary CTA) ├── 👤 My Profile — Base resume data, work history, skills ├── 💡 Insights — Keyword gaps, score trends (Phase 2) └── ⚙️ Settings — Account, billing, notifications ``` **Key Pages:** | Page | Purpose | |---|---| | `/dashboard` | WAA stats, recent applications, upgrade prompt (free) | | `/applications` | Kanban board, all applications list | | `/applications/new` | JD paste/URL input → analysis trigger | | `/applications/[id]` | Application workspace: JD summary, ATS score, document tabs | | `/applications/[id]/resume` | Resume editor with AI suggestions | | `/applications/[id]/cover-letter` | Cover letter editor | | `/applications/[id]/linkedin` | LinkedIn optimizer | | `/profile` | Base profile editor, resume import | | `/settings` | Account, password, notifications | | `/settings/billing` | Plan management, invoice history | | `/onboarding` | Multi-step first-run experience | --- ### 6.2 Critical User Flows #### Flow 1 — First-Time JD Optimization (Core Loop) **Entry point:** Dashboard "New Application" CTA 1. User clicks **"New Application"** → navigates to `/applications/new` 2. User pastes JD URL or raw text into input field → clicks **"Analyze Job"** 3. System shows parsing animation (2–5s) → displays extracted: Role Title, Company, Top 10 Keywords, Required vs. Nice-to-Have skills 4. User reviews extraction → clicks **"Looks good, optimize my resume"** 5. System shows resume sections with before/after bullet suggestions (streamed in real-time) 6. User accepts/rejects/edits individual bullets → ATS score updates live in sidebar 7. User clicks **"Generate Cover Letter"** → 3 tone options shown 8. User selects tone → cover letter streams in → editable rich text 9. User clicks **"Export PDF"** → PDF downloads in <8s 10. System shows: "Application saved! Track it in your dashboard." **Edge case:** JD URL fails to scrape → System shows: *"We couldn't read that URL. Paste the job description text instead."* with raw text input pre-focused. --- #### Flow 2 — Resume Import & Profile Setup (Onboarding) **Entry point:** Post-signup redirect to `/onboarding` 1. Welcome screen: *"Let's build your career profile in 3 minutes."* → **"Get Started"** 2. Step 1 — Resume upload: Drag-and-drop PDF/DOCX, or **"Build from scratch"** 3. If upload: AI parses → shows structured preview (work history cards) → user confirms or edits 4. Step 2 — Target roles: Multi-select from suggestions + free text input (e.g., "Product Manager," "UX Designer") 5. Step 3 — Career goals: Single question: *"What's your primary goal right now?"* (New job, Career switch, Promotion) 6. Step 4 — (Optional) LinkedIn URL: *"Paste your LinkedIn URL to unlock profile optimization"* 7. Completion screen: *"You're ready! Let's find you a job."* → CTA: **"Paste your first job description"** **Edge case:** DOCX fails to parse → Show manual entry form pre-populated with any successfully parsed fields; flag failed sections with yellow warning. --- #### Flow 3 — Upgrade from Free to Pro (Conversion) **Entry point:** User hits free plan limit (3 applications) while creating Application #4 1. User clicks **"New Application"** on dashboard 2. System shows upgrade modal (not a redirect): *"You've used your 3 free applications. Upgrade to Pro for unlimited applications + all document types."* 3. Modal shows: Free vs. Pro comparison (3 rows max), price anchored to "less than one coffee/week" 4. User clicks **"Upgrade to Pro — $19/month"** → Stripe Checkout opens in modal/overlay (not new tab) 5. User completes payment → Stripe webhook fires → plan updated in DB → modal closes → user is on Pro 6. System shows success toast: *"Welcome to Pro! Your new application is ready."* → Immediately continues to Application #4 creation **Edge case:** Stripe checkout abandoned → User returned to dashboard; upgrade CTA remains prominent in nav; follow-up email sent at T+24hrs: *"Still thinking about it? Here's what Pro unlocks..."* --- ### 6.3 Design Principles | Principle | Definition | UI Implication | |---|---|---| | **Speed as respect** | Every second of waiting communicates disrespect for the user's time — especially in a product used by anxious job seekers | AI generation must stream; no blank loading screens; skeleton loaders everywhere; p95 non-AI responses < 800ms | | **Confidence through transparency** | Users should always know *why* the AI made a suggestion, not just *what* it suggested | Every AI-generated bullet or section shows the JD keyword it's targeting in a small tag; "Why this change?" tooltip available | | **Reduce, don't replace** | AI should handle the tedious parts; humans make the final call | Accept/reject/edit controls on every AI suggestion; never auto-apply changes; always show original alongside suggestion | | **One job, one focus** | Each screen should have exactly one primary action and zero ambiguity | Maximum one CTA per screen; secondary actions in overflow menus or lower visual hierarchy | | **Calm confidence** | Job searching is emotionally charged — the UI should project calm competence, not excitement or alarm | Muted color palette for secondary UI; green/positive language for progress (never "error" for partial matches — use "opportunity") | --- ### 6.4 Design System Recommendations **Color Palette:** - Primary: `#2563EB` (Rolefit Blue) — professional, trustworthy, high contrast - Secondary: `#0F172A` (Slate 900) — dark backgrounds, sidebar, text - Accent: `#10B981` (Emerald 500) — ATS score improvements, success states, positive signals - Warning: `#F59E0B` (Amber 500) — missing keywords, medium match score - Danger: `#EF4444` — not used for ATS scores (demoralization risk); only for hard errors - Background: `#F8FAFC` (Slate 50) — light mode canvas - Card surface: `#FFFFFF` with `box-shadow: 0 1px 3px rgba(0,0,0,0.08)` **Typography:** - Display/Headings: Inter (700) — clean, professional, excellent legibility - Body: Inter (400/500) — consistency with headings - Code/Document preview: JetBrains Mono — resume/cover letter preview panes - Scale: 12/14/16/20/24/32/48px — strict 8px grid adherence **Component Library:** shadcn/ui — all components built on Radix UI primitives (fully accessible), styled with Tailwind, zero vendor lock-in. **Accessibility (WCAG 2.1 AA):** - All color contrast ratios ≥ 4.5:1 for normal text, ≥ 3:1 for large text - All interactive elements keyboard-navigable with visible focus rings - Resume editor: announce AI suggestion insertions via `aria-live="polite"` (critical — screen reader users in job search) - PDF exports must not be the only way to access document content (HTML view required for accessibility) - All form fields have explicit `<label>` associations; error messages linked via `aria-describedby` --- ### 6.5 Empty States & Onboarding UX **Day 1 empty dashboard:** > Illustration of a blank application board + copy: *"Your job search starts here. Paste a job description and watch your resume transform."* → Single CTA: **"Analyze my first job description →"** **Onboarding sequence (post-signup):** 1. **Welcome (10s):** Name + goal capture — *"What are you looking for?"* [New job / Career switch / Side opportunity] 2. **Profile foundation (90s):** Resume upload or 3-field quick entry (current title, years experience, top skill) 3. **First magic moment (3–5 min):** Immediate redirect to JD input — no detour through settings or dashboard 4. **Aha moment trigger:** User sees their ATS score jump from, say, 42 → 78 after accepting 4 bullet suggestions. This is the moment. Reinforce with: *"Your resume is now 86% more likely to pass ATS filters for this role."* 5. **Value proof email (T+2hr):** *"You just gave your resume a 36-point boost. Here's what that means for your chances..."* --- ## 🚀 SECTION 7: GO-TO-MARKET & LAUNCH STRATEGY ### 7.1 Pricing Strategy **Model: Freemium with monthly subscription tiers** *(Rationale: Maximum top-of-funnel with paywall at natural "I need more" moment — application #4)* | Tier | Price | Features | Target User | |---|---|---|---| | **Free** | $0 | 3 applications, resume optimization only, no cover letter export, watermarked PDF | Evaluate product, student testing | | **Pro** | $19/month | Unlimited applications, resume + cover letter + LinkedIn optimizer, PDF + DOCX export, ATS scores | Active job seekers, 1–3 month engagement | | **Career** | $39/month | Everything in Pro + keyword gap reports, application tracker, priority AI queue, 1 LinkedIn profile audit/month | Career switchers, long job searches, power users | | **Annual Pro** | $149/year ($12.40/mo) | Same as Pro | Users committed to 6+ month search — drive with "save 35%" messaging | **Pricing psychology:** - **Freemium limit at 3 applications** — deliberately chosen because users who've made 3 applications are *already invested* and have validated the product works; conversion at this moment is natural - **$19 anchored against career coach** ($150–$300/session) and LinkedIn Premium ($39/month) in all upgrade flows - **Annual plan prominent in upgrade modal** — 35% savings message drives LTV and reduces churn risk - **Career tier at $39** exists primarily as an anchor to make Pro feel like exceptional value --- ### 7.2 Launch Phases **Pre-Launch (Weeks 1–6): Build in Public + Waitlist** - Goals: 500 waitlist signups; 50 beta testers; 10 success stories - Channels: Twitter/X build-in-public thread series; ProductHunt upcoming page; LinkedIn content targeting HR professionals and career coaches (build awareness); Reddit communities (r/jobs, r/cscareerquestions, r/careerguidance) - Tactics: Share real before/after resume examples (anonymized); invite career coaches to beta as strategic partners **MVP Launch (Week 8): ProductHunt + Community** - ProductHunt launch day targeting Top 5 Product of the Day - Personal outreach to 200 waitlist signups (manual, high-touch) - Launch post on LinkedIn: *"I built a tool that boosted my ATS score from 38 to 81. Here's how it works."* - Reddit posts in r/jobs (value-first, not promotional): *"How to actually get your resume past ATS filters in 2026 — and a tool that automates it"* - Goal: 200 signups Day 1; 20 paid users Week 1 **Growth Phase (Month 3–12):** - SEO content engine: 50+ articles targeting high-intent keywords ("how to tailor resume to job description," "ATS optimization guide 2026," "cover letter for career change") - Referral mechanic: *"Give a friend 1 free Pro month, get 1 free month yourself"* — triggered post-export (peak satisfaction) - Partnership: Career coaches and university career centers as affiliate/white-label channel - TikTok/Instagram Reels: 60-second demos of the ATS score jump — extremely shareable, job-search content performs well --- ### 7.3 Distribution Channels (Ranked by ROI) | Channel | Why It Fits | First Action | Timeline to Results | |---|---|---|---| | **SEO (Long-tail career content)** | High-intent search traffic with low CPC competition; compounds over time | Publish 5 cornerstone articles: "ATS optimization," "cover letter for career switch," "LinkedIn About section guide" | Month 3–12 (slow ramp, high LTV) | | **Reddit (r/jobs, r/cscareerquestions)** | 8M+ subscribers, organic community, users actively seeking advice | Value-first post with tool mentioned naturally; respond to 10 "resume help" threads/day during launch week | Week 1–4 (fast, requires authenticity) | | **ProductHunt** | Concentrated tech-savvy early adopter audience; strong launch spike for backlinks and social proof | Submit 4 weeks before launch; recruit hunters; prepare assets | Launch day spike | | **LinkedIn Content** | Career switchers (secondary persona) heavily active on LinkedIn; professional credibility channel | Founder posts a weekly "resume teardown" series showing before/after transformations | Month 1–6 (builds following) | | **University Career Centers** | Captive audience of primary persona (graduates); institutional trust; high volume | Cold email 50 career centers offering free Pro licenses for students | Month 3+ (slow sales cycle, high volume) | | **Affiliate — Career Coaches** | Career coaches spend $0 on client tools; offering white-label or co-branded version creates distribution | Identify 100 career coaches on LinkedIn with 5K–50K followers; offer 30% rev share | Month 4+ | --- ## 📅 SECTION 8: DEVELOPMENT ROADMAP ### 8.1 MVP Scope Definition **IN Scope for MVP:** - User authentication (Google + email) - Profile creation (manual entry + PDF/DOCX import) - JD analysis (URL + paste text) - Resume bullet optimization with accept/reject UI - ATS score before/after - Cover letter generation (Pro only) - LinkedIn About + Headline optimizer (Pro only — unlocks on upgrade) - PDF export (resume + cover letter) - Free vs. Pro plan enforcement (Stripe) - Application save/list view (no kanban yet) - Basic dashboard (recent applications, WAA display) - Mobile-responsive layout (not a native app — responsive web) **EXPLICITLY OUT of MVP:** - Application tracker kanban board (Phase 2) - Email job alerts (Phase 2) - Keyword gap report / analytics (Phase 2) - Team/collaborative features (Phase 3) - Interview prep / mock questions (Phase 3) - Chrome extension (Phase 3) - API access (Phase 3) - White-label / career coach portal (Phase 3) **MVP success definition:** - ≥200 signups in Week 1 - ≥20 paying users in Week 2 - Activation rate ≥50% (signup → first export within 72hrs) - Zero P0 bugs in core generation loop for 7 consecutive days - User NPS ≥ 40 from first 50 respondents --- ### 8.2 Phased Roadmap **Phase 1 — MVP (Weeks 1–8)** | Week | Milestone | Risk | Mitigation | |---|---|---|---| | 1–2 | Project setup, auth (Clerk), DB schema, profile CRUD | Schema changes late in project | Finalize schema before Week 3; migrations cost time | | 3–4 | JD analysis pipeline (scraping + OpenAI function calling), Redis caching | OpenAI API costs spike with testing | Use GPT-4o-mini for development; GPT-4o only in staging/prod | | 5–6 | Resume optimizer UI, ATS scoring algorithm, document generation (resume + cover letter) | Streaming SSE in Next.js App Router complexity | Validate SSE pattern with a spike in Week 2 | | 7 | LinkedIn optimizer, PDF export, Stripe integration | Puppeteer cold starts on Vercel | Move PDF generation to Browserless.io dedicated instance | | 8 | QA, Sentry/Axiom instrumentation, launch checklist, ProductHunt prep | Last-minute feature creep | Feature freeze at end of Week 7; Week 8 is polish-only | **Phase 2 — Growth (Months 3–6)** - Application tracker kanban (Supabase Realtime-powered drag-and-drop) - Keyword gap analytics dashboard - Email job alerts (Inngest cron + Resend) - Referral program (ReferralHero or custom) - SEO content site launch (Next.js blog, target 20 articles) - Annual plan promotion - A/B testing on onboarding flow (PostHog feature flags) **Phase 3 — Scale (Months 7–12+)** - Interview prep module (AI mock interview questions based on JD) - Chrome extension: highlight job on any page → auto-trigger analysis - Career coach/university portal: white-label, bulk license management - Salary intelligence: integrate compensation data per role/location - API access (developers building on Rolefit data) - Team plan: hiring managers can review candidate-submitted Rolefit applications --- ### 8.3 Risk Register | Risk | Likelihood | Impact | Mitigation | Owner | |---|---|---|---|---| | OpenAI API cost overrun (high usage, low conversion) | H | H | Aggressive Redis caching of JD analyses; rate limiting on free tier (5 AI calls/day); GPT-4o-mini for non-critical operations | Founder/CTO | | ATS score algorithm perceived as inaccurate | M | H | Clearly label as "estimate"; publish methodology; A/B test score framing language | PM | | JD scraping breaks when major job boards update their HTML | H | M | Fallback to paste-text input always available; use firecrawl.dev for resilient scraping; monitor scrape failure rate | Engineering | | Low Day-30 retention (job seekers leave once hired) | H | M | This is structural — mitigate by moving toward career management (LinkedIn, skill building) features and annual plan discounts that pre-commit users | PM/Growth | | Copycat product from existing resume builder (Kickresume, Resume.io) | M | M | Ship fast; build community moat; focus on document quality gap they can't close without AI-native rebuild | Founder | | GDPR/privacy complaint around resume data storage | L | H | Clear privacy policy, end-to-end encryption for PII, right-to-erasure pipeline before launch | Founder/Legal | | ProductHunt launch underperforms (< Top 10) | M | L | Pre-recruit 100+ supporters; plan 3 backup launch channels (Reddit, LinkedIn, newsletter) | Growth | --- ## ✅ SECTION 9: DEFINITION OF DONE & QUALITY GATES ### 9.1 MVP Launch Checklist - [ ] Core user flows (onboarding → JD analysis → document generation → export) work end-to-end without manual intervention - [ ] Google OAuth and email/password auth tested across Chrome, Safari, Firefox - [ ] Stripe checkout tested with real card + test card for failure states - [ ] Free plan limits enforced server-side (not just UI gating) - [ ] All screens responsive: tested at 375px (iPhone SE), 768px (tablet), 1280px (desktop) - [ ] All error states handled: JD scrape fail, AI timeout, PDF export fail, payment fail - [ ] Mixpanel events firing: `signup`, `profile_created`, `jd_analyzed`, `document_generated`, `document_exported`, `upgrade_clicked`, `upgrade_completed` - [ ] Privacy Policy and Terms of Service pages live (reviewed by legal or AI-generated + reviewed) - [ ] Cookie consent banner implemented (GDPR — EU users) - [ ] HTTPS enforced, HSTS headers active, no mixed content warnings - [ ] Lighthouse CI: LCP < 2.5s, CLS < 0.1, accessibility score ≥ 85 - [ ] SEO: title tags, meta descriptions, OG images on all public pages - [ ] Sentry live with source maps uploaded; test error captured and alerted - [ ] Supabase daily backups enabled and tested with restore drill - [ ] Rate limiting active on `/api/billing` and `/api/trpc/jdAnalysis.analyze` - [ ] Uptime monitoring (UptimeRobot) configured with PagerDuty/Slack alert --- ### 9.2 Testing Strategy **Unit Testing (Vitest):** - Coverage target: 80% on business logic modules (ATS scoring algorithm, JD keyword extraction, plan limit enforcement) - Critical modules: `atsScorer.ts`, `keywordExtractor.ts`, `planLimits.ts`, `documentGenerator.ts` **Integration Testing (Vitest + Supabase local):** - Critical paths: auth flow, profile CRUD, JD analysis persistence, document creation, Stripe webhook handling - Run against local Supabase instance with seed data **E2E Testing (Playwright):** - Automate 3 flows: full onboarding → first document export; free → paid upgrade; document edit → PDF export - Run in CI on every PR against staging environment **Load Testing (k6):** - Scenario 1: 100 concurrent users each submitting a JD analysis (peak traffic simulation) - Scenario 2: 50 concurrent PDF exports (Browserless capacity test) - Pass criteria: p95 < 5s for AI generation start; p95 < 3s for PDF export; 0 5xx errors under load --- ## 🤖 SECTION 10: AI VIBE CODING EXECUTION GUIDE ### 10.1 Vibe Coding Starter Prompt Sequence --- **Prompt 1 — Project Scaffolding (Use in: Cursor / Claude Code)** ``` Create a production-ready Next.js 14 App Router project called "rolefit" with the following setup: TECH STACK: - Next.js 14 with TypeScript (strict mode), App Router, Turbopack - Tailwind CSS + shadcn/ui (New York style, slate base color) - tRPC v11 with React Query for type-safe API - Zustand for client state management - Clerk for authentication (install @clerk/nextjs) - Prisma ORM with PostgreSQL connection string via env - Upstash Redis via @upstash/redis and @upstash/ratelimit - Inngest for background jobs (@inngest/sdk) - Resend for email (@resend/node + react-email) - Stripe (@stripe/stripe-js + stripe) - Sentry (@sentry/nextjs) - Zod for validation FILE STRUCTURE: /app /(auth)/sign-in, /sign-up — Clerk auth pages /(dashboard)/dashboard — protected layout with sidebar /(dashboard)/applications/[id] — application workspace /(dashboard)/profile — profile editor /(dashboard)/settings/billing /api/trpc/[trpc] — tRPC handler /api/billing/webhook — Stripe webhook /api/billing/create-checkout — Stripe checkout session /onboarding — multi-step onboarding flow /lib — utilities, trpc client, prisma client, stripe client /server /routers — tRPC routers (auth, profile, jdAnalysis, documents, applications, billing) /inngest — background job functions /components — shared UI components organized by domain /emails — React Email templates Generate: package.json with all deps, tsconfig.json (strict), tailwind.config.ts, middleware.ts (Clerk auth), environment variable example file (.env.example), and the root layout with Clerk provider, tRPC provider, and Zustand provider. Initialize shadcn/ui with the specified config. ``` --- **Prompt 2 — Database Schema (Use in: Cursor with Prisma)** ``` Generate a complete Prisma schema file (schema.prisma) for the Rolefit career platform with the following models. Use PostgreSQL provider. Enable Prisma Accelerate connection pooling. MODELS REQUIRED (use exact field names): 1. User — clerk_id (String @unique), email, fullName, plan (enum: FREE, PRO, CAREER), stripeCustomerId, createdAt, updatedAt 2. Profile — userId (FK→User), headline, summary, linkedinUrl, targetRoles (String[]), targetIndustries (String[]), workExperiences (relation), createdAt, updatedAt 3. WorkExperience — profileId (FK→Profile), company, title, startDate, endDate, isCurrent (Boolean), bullets (Json — array of {id, text, isActive}), sortOrder (Int) 4. JdAnalysis — userId (FK→User), rawText (String @db.Text), sourceUrl, companyName, roleTitle, requiredSkills (String[]), niceToHave (String[]), keywords (String[]), seniorityLevel, analysisData (Json), textHash (String @unique), createdAt 5. Application — userId (FK→User), jdAnalysisId (FK→JdAnalysis), profileSnapshot (Json), status (enum: DRAFT, APPLIED, INTERVIEW, OFFER, REJECTED), atsScoreBefore (Int?), atsScoreAfter (Int?), notes, appliedAt, createdAt. Relation to documents. 6. Document — applicationId (FK→Application), userId (FK→User), type (enum: RESUME, COVER_LETTER, LINKEDIN_ABOUT, LINKEDIN_HEADLINE), content (String @db.Text), contentDelta (Json?), version (Int @default(1)), exportedAt, storagePath, createdAt 7. Subscription — userId (FK→User @unique), stripeSubId (String @unique), plan (enum: PRO, CAREER), status (enum: ACTIVE, PAST_DUE, CANCELLED, TRIALING), currentPeriodEnd, cancelledAt, createdAt After the schema: generate all Prisma migration SQL and a seed file (seed.ts) that creates 2 test users (one free, one pro) with sample profiles and 1 JD analysis each. Also generate the Prisma client singleton (/lib/prisma.ts) with edge-safe instantiation for Next.js. ``` --- **Prompt 3 — Authentication System (Use in: Cursor)** ``` Implement the complete authentication and authorization system for Rolefit using Clerk + tRPC: 1. MIDDLEWARE (middleware.ts): Protect all routes under /(dashboard) and /onboarding. Allow public access to /, /sign-in, /sign-up, /api/billing/webhook. Use Clerk's clerkMiddleware(). 2. TRPC CONTEXT (/server/context.ts): Create createTRPCContext that extracts Clerk auth from request, looks up or creates the User record in Postgres, and attaches user + db to context. 3. TRPC BASE (/server/trpc.ts): Create publicProcedure and protectedProcedure. protectedProcedure should throw UNAUTHORIZED if no user in context. Create planProcedure(minPlan) that additionally checks plan tier (FREE < PRO < CAREER) and throws FORBIDDEN with upgrade prompt if plan is insufficient. 4. AUTH ROUTER (/server/routers/auth.ts): getSession (returns full user + profile + subscription), syncUser (called on first login via Clerk webhook to create DB user record). 5. CLERK WEBHOOK (/app/api/webhooks/clerk/route.ts): Handle user.created event → create User in DB. Handle user.deleted → trigger account deletion pipeline. 6. ONBOARDING REDIRECT: After first sign-in (detected by checking if profile exists), redirect to /onboarding instead of /dashboard. 7. PLAN LIMITS UTILITY (/lib/planLimits.ts): Export a planLimits object: FREE: { maxApplications: 3, canExportCoverLetter: false, canUseLinkedIn: false, aiCallsPerDay: 5 } PRO: { maxApplications: Infinity, canExportCoverLetter: true, canUseLinkedIn: true, aiCallsPerDay: 50 } CAREER: { maxApplications: Infinity, canExportCoverLetter: true, canUseLinkedIn: true, aiCallsPerDay: 200 } Use TypeScript throughout. All procedures must use Zod input validation. Include JSDoc comments on all exported functions. ``` --- **Prompt 4 — Core Feature Build: JD Analysis + Document Generation (Use in: Cursor)** ``` Build the core product loop for Rolefit — the AI-powered JD analysis and document generation pipeline: PART A — JD ANALYSIS PIPELINE: 1. Inngest function (ANALYZE_JD): - Step 1: If sourceUrl provided, fetch page content using cheerio/fetch (allowlist: linkedin.com, indeed.com, greenhouse.io, lever.co, workday.com, ashbyhq.com) - Step 2: Check Upstash Redis for cached analysis (key: sha256(rawText)). If hit, return cached. - Step 3: Call OpenAI GPT-4o with structured output (JSON mode) to extract: {companyName, roleTitle, seniorityLevel, requiredSkills: string[], niceToHave: string[], keywords: string[], culturalSignals: string[], compensationMentioned: boolean}. Use this system prompt: "You are an expert ATS and recruitment analyst. Extract structured data from job descriptions. Return ONLY valid JSON matching the schema." - Step 4: Cache result in Redis (TTL: 7 days). Persist JdAnalysis to DB. - Step 5: Create Application record linking user + JdAnalysis. - Step 6: Emit Supabase Realtime event: analysis_complete:{applicationId} 2. tRPC router (jdAnalysis.ts): - analyze mutation: validates input, checks rate limit (Upstash: 10 analyses/day for free, 50 for pro), triggers Inngest job, returns {applicationId, status: 'queued'} - getById query: returns full analysis with computed atsScoreBefore 3. ATS SCORING ALGORITHM (/lib/atsScorer.ts): - Input: {profileBullets: string[], keywords: string[], requiredSkills: string[]} - Score = (matched required skills × 2 + matched keywords) / (required skills × 2 + keywords) × 100 - Returns: {score: number, matchedKeywords: string[], missingKeywords: string[], matchedSkills: string[], missingSkills: string[]} PART B — DOCUMENT GENERATION (Streaming): 1. Inngest function (GENERATE_DOCUMENTS): - Accepts: {applicationId, docTypes: DocType[], userId} - Loads: user profile snapshot + JD analysis from DB - For each docType, calls OpenAI GPT-4o with streaming - Resume system prompt: "You are an expert ATS resume writer. Rewrite only the work experience bullets to naturally incorporate these missing keywords: {missingKeywords}. Keep achievements quantified. Preserve the user's voice. Return JSON: {revisedBullets: [{experienceId, bullets: [{id, original, suggested, targetKeyword}]}]}" - Cover letter system prompt: "Write a tailored cover letter for {roleTitle} at {companyName}. The candidate's background: {profileSummary}. Key JD requirements: {requiredSkills}. Tone: {tone}. Length: 3 paragraphs. Start with a compelling hook, not 'I am writing to apply'." - LinkedIn About prompt: "Rewrite this LinkedIn About section for someone targeting {roleTitle} roles. Current About: {currentAbout}. Target role requirements: {requiredSkills}. Write in first person, conversational, 350 words max." - Stream each response via Server-Sent Events endpoint: /api/documents/stream/[applicationId] - Persist final Document records to DB on stream completion 2. SSE endpoint (/app/api/documents/stream/[applicationId]/route.ts): Auth check → stream OpenAI response chunks → close. 3. tRPC documents router: generate mutation, getByApplication query, update mutation (save edits), export mutation (triggers PDF generation). ``` --- **Prompt 5 — UI & Design System (Use in: Cursor / v0.dev for initial components)** ``` Build the complete frontend UI for Rolefit's core application workspace using Next.js 14 App Router, shadcn/ui, and Tailwind CSS. DESIGN TOKENS (add to globals.css): - Primary: #2563EB, Secondary: #0F172A, Accent: #10B981, Warning: #F59E0B - Border radius: 8px standard, 12px cards - Font: Inter (Google Fonts) - 8px grid spacing system COMPONENTS TO BUILD: 1. SIDEBAR LAYOUT (/components/layout/Sidebar.tsx): - Logo top-left, nav items with icons (lucide-react): Dashboard, Applications, New Application (highlighted CTA), Profile, Settings - User avatar + name + plan badge (FREE / PRO / CAREER) at bottom - Upgrade CTA card for free users: "Unlock unlimited applications" with gradient border 2. APPLICATION WORKSPACE (/app/(dashboard)/applications/[id]/page.tsx): - Left panel (30%): JD summary card showing role, company, ATS match score (animated circular progress, color: red<50 / amber 50-70 / green>70), extracted keywords as chips (matched=green, missing=amber) - Right panel (70%): Tab bar (Resume | Cover Letter | LinkedIn) - Resume tab: Work experience sections, each bullet showing original text with "AI suggestion" below it (different background), Accept ✓ / Reject ✗ / Edit ✏️ action buttons - ATS score updates via Zustand store as user accepts suggestions (optimistic) - Sticky action bar at bottom: "Export PDF" primary button + "Export DOCX" secondary + "Save" tertiary 3. JD INPUT PAGE (/app/(dashboard)/applications/new/page.tsx): - Large centered card: Textarea (paste JD) + URL input with "or" divider - Animated analyze button with loading state (Lucide Loader2 spin) - Supported sources list: LinkedIn, Indeed, Greenhouse, Lever, Workday 4. UPGRADE MODAL (/components/billing/UpgradeModal.tsx): - Sheet/Dialog with side-by-side Free vs Pro comparison (max 4 rows) - Price display: "$19/month" with "or $149/year (save 35%)" toggle - Stripe checkout trigger button - "Less than one coffee per week" subtext 5. ONBOARDING FLOW (/app/onboarding/page.tsx): - Step indicator (1 of 4) at top - Step 1: Welcome + goal selection (3 cards with icons) - Step 2: Resume upload (drag-drop zone using react-dropzone) or "build from scratch" link - Step 3: Target role multi-select with tag input - Animated transitions between steps using framer-motion slide Make all components fully TypeScript typed, use shadcn/ui primitives, and ensure mobile-responsive at 375px breakpoint. ``` --- ### 10.2 Vibe Coding Rules File (CLAUDE.md / .cursorrules) ```markdown # ROLEFIT — VIBE CODING RULES # Drop this file in project root. Claude/Cursor must follow all rules below. ## PROJECT CONTEXT TypeScript monorepo: Next.js 14 App Router, tRPC v11, Prisma + PostgreSQL, Clerk auth, Tailwind + shadcn/ui, Inngest for background jobs, OpenAI for AI generation. ## CODE STYLE - TypeScript strict mode ALWAYS. No `any` types — use `unknown` + type guards - All async functions must have explicit return types - No default exports except Next.js pages/layouts and Inngest functions - Named exports preferred for all utilities, components, and hooks - File naming: PascalCase for components, camelCase for utilities, kebab-case for routes - Max function length: 50 lines. Extract helpers aggressively. - Comments: JSDoc on all exported functions; inline comments only for non-obvious logic ## ARCHITECTURE - Server components by default; add "use client" only when needed (event handlers, hooks, browser APIs) - All DB queries via Prisma through tRPC procedures ONLY — no direct Prisma calls in components - Business logic lives in /server/routers or /lib — never in components - All form validation via Zod — reuse schema between client and server - Environment variables: access only via /lib/env.ts (validated with zod) — never process.env directly in code ## tRPC RULES - Every mutation must validate input with Zod schema - Every protected procedure must use `protectedProcedure` or `planProcedure` - Return types must be explicit — never infer complex return types - Error handling: use `TRPCError` with appropriate codes (UNAUTHORIZED, FORBIDDEN, NOT_FOUND, INTERNAL_SERVER_ERROR) ## AI INTEGRATION RULES - All OpenAI calls in /server/ai/*.ts — never inline in routers - Always set max_tokens explicitly - System prompts in /server/ai/prompts.ts as const strings — never inline - Always handle OpenAI errors gracefully; surface user-friendly message via TRPCError - Log token usage in Axiom for cost monitoring - Never send full profile data to OpenAI — always select minimum required fields ## DATABASE RULES - All writes go through transactions when affecting multiple tables - Never delete records — use soft deletes (deletedAt timestamp) - Every query must filter by userId to prevent cross-tenant data access - Pagination: cursor-based (not offset) for all list queries ## SECURITY NON-NEGOTIABLES - Never trust client-provided userId — always use ctx.user.id from Clerk session - Rate limit all AI-triggering endpoints via Upstash before hitting OpenAI - Sanitize all user-provided text before inserting into AI prompts (strip prompt injection patterns) - Never log PII (email, resume content, cover letters) — use redacted placeholders ## TESTING - Unit test all functions in /lib with Vitest - Every tRPC mutation must have at least one integration test - E2E tests for: onboarding flow, document generation, upgrade flow - No code merged to main without CI passing (lint + type-check + unit tests) ## ANTI-PATTERNS — NEVER DO THESE - No `useEffect` for data fetching — use React Query via tRPC - No localStorage for auth tokens — Clerk handles sessions - No client-side plan enforcement as the only gate — always enforce server-side - No inline styles — Tailwind only - No moment.js — use date-fns - No `console.log` in production code — use structured logging via Axiom - No AI calls directly in tRPC routers — route through Inngest for anything > 2s ``` --- ### 10.3 Recommended Vibe Coding Tool Per Phase | Phase | Tool | Why | |---|---|---| | **Wireframing** | Figma + FigJam | Create low-fidelity flows in FigJam (fast), then refine key screens in Figma before coding; share with AI: "Build this component from this Figma screenshot" | | **Component generation** | v0.dev (Vercel) | Describe UI components in natural language → get shadcn/Tailwind code instantly; ideal for the application workspace, onboarding steps, and upgrade modal | | **Full app scaffolding** | Claude Code (claude-sonnet-4-20250514) | Best for long-context, multi-file generation; use Prompts 1–5 above sequentially; handles tRPC + Prisma schema generation better than competitors | | **Debugging & refactoring** | Cursor (with Claude claude-sonnet-4-20250514 model) | Tab autocomplete + inline chat; best for iterative debugging of Inngest jobs, OpenAI streaming issues, and Stripe webhook logic | | **Deployment** | Vercel + Supabase (CLI) | `vercel deploy` + `supabase db push` — zero-config, both have free tiers sufficient for MVP; use Railway as alternative for simpler unified dashboard | --- ## EXECUTIVE SUMMARY (1-Page Version) ### ROLEFIT — AI-Powered Career Optimization Platform **Product:** Rolefit is a web application that analyzes any job description and automatically generates a tailored resume, cover letter, and LinkedIn profile — optimized for ATS filters and human readers — in under 5 minutes. **Problem:** 98% of Fortune 500 companies use ATS software that rejects up to 75% of resumes before a human sees them. Job seekers spend 2–4 hours per application manually rewriting documents with no guarantee of results. Career switchers lack the vocabulary to reframe their transferable experience. The process is opaque, exhausting, and demoralizing — and raw ChatGPT prompting produces generic output that compounds the problem. **Solution:** Rolefit's core loop: (1) User imports their career history once. (2) Paste a job description URL or text. (3) AI extracts required skills and keywords, scores your current resume against the JD, and rewrites bullets — showing before/after with accept/reject control. (4) Cover letter and LinkedIn section generated in one click. (5) ATS-safe PDF exported in under 8 seconds. Every output is job-specific, not generic. **Market:** TAM: $28B global career services market. SAM: 45M English-speaking digital job seekers annually (~$2.7B). Year 2 SOM target: 45,000 paying users = ~$10.8M ARR. Market timing is ideal: ATS adoption is universal, AI writing is normalized, and career switching is at a 20-year high post-2022 tech disruption. **Tech:** Next.js 14 + tRPC + PostgreSQL (Supabase) + OpenAI GPT-4o + Inngest. Modular monolith architecture deployable on Vercel in hours. Redis caching of JD analyses reduces AI costs by ~60% at scale. Stripe for subscriptions. Full TypeScript end-to-end. **Roadmap:** - Week 8: MVP launch (ProductHunt + Reddit) — resume optimizer + cover letter + LinkedIn + Stripe billing - Month 3–6: Application tracker, keyword gap analytics, referral program, SEO content engine - Month 7–12: Interview prep module, Chrome extension, career coach affiliate channel, $25K MRR target **Ask / Traction Goal:** Targeting $25K MRR and 1,200 paying users by Month 12 at a CAC < $25 and LTV:CAC ratio of 3:1. Freemium model with $19/month Pro plan, anchored against LinkedIn Premium ($39) and career coaching ($150+/session). Initial funding need: $120K (12 months runway for 1 founder + infrastructure + marketing) to reach default alive MRR threshold.