Portfolio Project: A production-grade SaaS job board platform demonstrating full-stack development capabilities, modern authentication & payment systems, and professional development practices.

Live Demo: shopmatch-pro.vercel.app | Portfolio: View Showcase →

Portfolio Demonstration Project - Built to showcase professional-level full-stack development skills

Status: ✅ Production-Ready MVP (Test Mode) - Fully functional and deployed

• ✅ Full-Stack Development: Complete MERN-equivalent stack (Next.js + Firebase + Stripe)
• ✅ Production-Grade Architecture: Secure, scalable, and maintainable code
• ✅ Modern Best Practices: TypeScript strict mode, security rules, comprehensive testing
• ✅ Complex Integrations: Authentication (Firebase), Payments (Stripe), Real-time data
• ✅ Professional Workflow: Git, CI/CD, documentation, code review process
• ✅ AI-Assisted Development: Effective orchestration of modern AI development tools
• ✅ Always-On Monitoring: Automated production smoke tests verify critical flows on every push to main

• ⚡ Performance: 176.9 KB first-load JS (41% under budget), ~3s builds with Turbopack
• 🔒 Security: Zero npm vulnerabilities (verified 2025-11-16), Firebase security rules, Stripe webhook verification, RBAC, type-safe APIs
• 🛡️ CI/CD: 6-job automated pipeline (build, lint, test, a11y, smoke tests, security scan), branch protection, conventional commits
• 🎨 Modern Stack: Next.js 15, TypeScript 5.7, Tailwind v4, shadcn/ui
• 🧪 Quality: Zero ESLint errors, TypeScript strict mode, Playwright E2E tests, accessibility verified
• 📚 Documentation: Architecture diagrams, API docs, runbooks, AI development guide (CLAUDE.md)
• 🚀 Deployed: Vercel with auto-deployment, production smoke tests on every main push

• 🌟 Full Portfolio Showcase → - Detailed project overview
• 🏗️ Architecture Documentation → - System design & data flows
• 🔐 Security Documentation → - Security model & threat analysis
• 📖 Complete Documentation → - All technical docs

Get started in 5 minutes:

1. Install Dependencies

   npm install

2. Configure Environment Variables

   cp .env.local.template .env.local
   # Edit .env.local with your Firebase and Stripe credentials
   # See docs/ENVIRONMENT_VARIABLES.md for detailed instructions

3. Validate Configuration

   npm run validate-env

4. Start Development Server

   npm run dev
   # Open http://localhost:3000

📖 New to the project? See Quick Start Guide | Full Documentation →

• 🔍 Browse and search job listings
• 📝 Apply to jobs with cover letters
• 📊 Track application status
• 🎯 Personalized dashboard

• ✍️ Post unlimited job listings
• 📋 Manage applications
• 📈 View application analytics
• 🎛️ Edit and close job postings

• 🔐 Secure authentication (Email/Password + Google OAuth)
• 💳 Stripe subscription integration
• 🔄 Real-time updates with Firebase
• 📱 Fully responsive design
• ⚡ Built with Next.js 15 + Turbopack

Show clients how you reason about hiring performance with the new Analytics & Insights dashboard:

• Portfolio-ready KPIs: Jobs posted, matches generated, time-to-match, and interview rate (seeded data for demos)
• Conversion funnel: Visualizes drop-off from job views through hires, making it easy to discuss optimization ideas
• Narrative insights: Highlight top-performing roles, competitive markets, and overall pipeline health—perfect for executive summaries
• Navigation: Dashboard → Analytics (or visit /dashboard/analytics directly)

View	Screenshot
Desktop overview
Mobile summary

💡 Client hand-off tip: Swap the seeded data with live metrics by wiring the cards and charts to your analytics warehouse (BigQuery, Firestore, Supabase, etc.) or marketing tracking tools. The layout is fully responsive and uses the same design tokens as the rest of the dashboard, so it’s production-ready once you connect real data sources.

Config-driven datasets: The analytics view reads from src/app/dashboard/analytics/demo-metrics.ts. Flip ACTIVE_METRIC_DATASET (e.g., jobBoard, courseMarketplace) or add your own vertical to instantly change every KPI/funnel/insight card.

• Framework: Next.js 15.5.4 (App Router, Server Components, Turbopack)
• Language: TypeScript 5.7 (strict mode)
• Styling: Tailwind CSS v4 + shadcn/ui component library
• Forms: React Hook Form + Zod validation
• State: React Context API for auth and global state

• Authentication: Firebase Auth (Email/Password + Google OAuth)
• Database: Cloud Firestore with custom security rules
• Payments: Stripe API (Checkout, Subscriptions, Webhooks)
• Hosting: Vercel (Edge Functions, Auto-scaling)
• Monitoring: Sentry error tracking

• Version Control: Git + GitHub with branch protection
• CI/CD: GitHub Actions (6-job pipeline: branch/commit validation, build & quality checks, accessibility tests, local smoke tests, Snyk security scan, production smoke tests)
• Package Manager: npm
• Linting: ESLint + Prettier
• Testing: Playwright E2E (smoke tests, accessibility), Jest unit tests, Firebase Emulator
• Security: Snyk scanning, npm audit (0 vulnerabilities), FOSSA license compliance
• Guardrails: Branch naming enforced as type/ID-slug (feat|fix|perf|sec|docs|test|refactor|ci|build); use ci for infrastructure changes

• src/ – Next.js 15 App Router source (routes, components, providers, utilities)
• e2e/ – Playwright suites (login, demo-diagnostics, verify-demo-login smoke tests run in CI)
• docs/ – Comprehensive documentation (architecture, security, runbooks, checklists, ADRs)
• .github/workflows/ci.yml – All CI jobs (branch naming + commit checks, build, accessibility, production smoke tests)
• scripts/ – Automation scripts (e.g., create-demo-users.js, CI helpers)
• public/ – Static assets and integrations, including Google Search Console verifier googlee573592846ba27d6.html
• playwright-report/ – Latest local Playwright artifacts (ignored in CI unless tests fail)
• vercel.json & lighthouse-budgets.json – Deployment routing and performance budgets

# Start development server (default port 3000)
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Lint code
npm run lint

# Validate environment variables
npm run validate-env

# Create test users (after env setup)
npm run create-user

# Webhook Testing & Monitoring (requires Stripe CLI)
npm run webhook:test           # Trigger test webhook event
npm run webhook:monitor        # Monitor live events in real-time
npm run webhook:events         # Show recent webhook events
npm run webhook:events:watch   # Watch webhook events (auto-refresh)

💡 Tip: For complete webhook testing guide, see docs/runbooks/STRIPE_WEBHOOK_RUNBOOK.md

This repository includes a safe, local demo of a data extraction and enrichment pipeline. Perfect for showcasing web scraping, data processing, and AI integration patterns.

• Sample Data: 5 dummy products with HTML files in examples/html/
• CSV Input: examples/products.csv with product metadata
• CLI Script: scripts/scrape-and-enrich-products.js that:
  • Reads CSV product data
  • Loads corresponding HTML files
  • Extracts title, price, and description using pattern matching
  • Calls generateEnrichedDescription() stub (ready for LLM integration)
  • Writes enriched output to output/enriched_products.csv

# Run the demo pipeline
npm run demo:scrape

# Or with custom paths
node scripts/scrape-and-enrich-products.js <input_csv> <output_csv>

title,price,enriched_description
Premium Wireless Headphones,$79.99,"Experience crystal-clear audio with advanced noise cancellation..."
Durable USB-C Cable 2m,$12.99,"High-quality USB-C cable with reinforced connectors..."

The script includes a stub function generateEnrichedDescription() ready for AI integration:

// TODO: Replace with actual LLM API call:
// - OpenAI API (gpt-4, gpt-3.5-turbo)
// - Anthropic Claude API
// - Google Vertex AI / PaLM
// - Local LLM (Ollama, LM Studio)
// - Hugging Face Inference API

async function generateEnrichedDescription(rawDescription) {
  const response = await openai.chat.completions.create({
    model: "gpt-4",
    messages: [{
      role: "user",
      content: `Enhance this product description with compelling marketing copy: "${rawDescription}"`
    }]
  });
  return response.choices[0].message.content;
}

⚠️ Important: When scraping real websites, always:

1. Check robots.txt - Respect crawling rules: https://example.com/robots.txt
2. Review Terms of Service - Verify scraping is permitted
3. Implement Rate Limiting - Don't hammer servers; use delays between requests
4. Set User-Agent - Identify your bot in HTTP headers
5. Cache Results - Don't re-scrape the same content repeatedly
6. Handle Errors Gracefully - Catch 429 (rate limit), 403 (forbidden), 500 (server errors)
7. Use Official APIs - Prefer APIs over scraping when available

Related Resources:

• robots.txt Standard
• Web Scraping Best Practices
• Cheerio Documentation - HTML parsing library for Node.js
• Playwright Guide - Browser automation for dynamic content

AI Workflow Quick Links:

• Persona Prompts - Copy-paste ready prompts for 6 AI personas
• Workflow Order - AIM → Plan → Build → Wrench → Gate → SKIN
• Playbook - Standard Operating Procedures for each task
• Architecture Decisions - ADRs explaining why we chose each technology
• Runbooks - Operational procedures for common issues

Use Persona Prompts to Simulate a Full Team:

• 🎯 Product Manager - "Why this way?" business rationale and acceptance criteria
• 🏗️ Tech Lead - "Build on existing" minimal architectural changes
• 🧪 QA Engineer - Complete test plans across the test pyramid
• 🔒 Security Engineer - Threat modeling and vulnerability analysis
• 👥 Pair Programmer - Step-by-step implementation with code snippets
• 🔬 Researcher - Technology landscape monitoring for Decision Matrix updates

See CLAUDE.md for complete workflow documentation and copy-paste ready prompts.

┌──────────────────────────────────────────────────────────┐
│                   CLIENT (Next.js App)                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
│  │    Auth     │  │  Job Board  │  │  Subscriptions  │  │
│  │   Pages     │  │  Features   │  │   & Payments    │  │
│  └─────────────┘  └─────────────┘  └─────────────────┘  │
└────────────────────────┬─────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
         ▼               ▼               ▼
  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
  │   Firebase   │ │  Next.js API │ │    Stripe    │
  │     Auth     │ │    Routes    │ │   Checkout   │
  └──────────────┘ └──────┬───────┘ └──────┬───────┘
                          │                │
                          ▼                │
                   ┌──────────────┐        │
                   │  Firestore   │        │
                   │   Database   │        │
                   └──────────────┘        │
                          ▲                │
                          │                │
                          └────────────────┘
                       Webhook Events

For Job Seekers:

• Browse and search job listings
• Apply to jobs with cover letters
• Track application status
• Personalized dashboard

For Employers: (Requires Pro Subscription)

• Post unlimited job listings
• Manage applications
• View application analytics
• Edit and close job postings

Platform Features:

• Secure authentication (Email/Password + Google OAuth)
• Stripe subscription integration
• Real-time updates with Firebase
• Fully responsive design
• Role-based access control (RBAC)

This project showcases a comprehensive skill set:

• ✅ Full-Stack Development: Frontend (React/Next.js) + Backend (API Routes) + Database (Firestore)
• ✅ TypeScript Mastery: Strict mode, advanced types, type-safe APIs
• ✅ Authentication & Authorization: JWT, OAuth 2.0, RBAC, custom claims
• ✅ Payment Integration: Stripe API, webhooks, subscription management
• ✅ Database Design: NoSQL data modeling, security rules, composite indexes
• ✅ API Development: RESTful endpoints, error handling, input validation
• ✅ Security: OWASP best practices, input sanitization, secure authentication
• ✅ DevOps: CI/CD pipelines, environment management, production deployment

• ✅ Version Control: Git workflow, meaningful commits, PR process
• ✅ Code Quality: Linting, formatting, type checking, zero errors
• ✅ Documentation: Technical writing, architecture diagrams, API docs
• ✅ Testing: Manual E2E testing, security rule testing, webhook simulation
• ✅ Problem Solving: Debugging, researching solutions, implementing fixes
• ✅ AI Collaboration: Using AI tools strategically while maintaining code quality

shopmatch-pro/
├── src/
│   ├── app/                    # Next.js App Router pages and API routes
│   │   ├── (auth)/            # Authentication pages
│   │   ├── dashboard/         # Owner and seeker dashboards
│   │   ├── jobs/              # Job listing, detail, create, edit
│   │   ├── subscribe/         # Stripe subscription page
│   │   └── api/               # Backend API routes
│   ├── components/            # React components
│   │   ├── ui/               # shadcn/ui components
│   │   ├── job-card.tsx      # Job display card
│   │   ├── job-form.tsx      # Job creation/edit form
│   │   └── application-card.tsx
│   ├── lib/                   # Shared utilities
│   │   ├── firebase/         # Firebase client and admin
│   │   ├── stripe/           # Stripe configuration
│   │   └── contexts/         # React contexts
│   └── types/                 # TypeScript type definitions
├── public/                    # Static assets
├── scripts/                   # Utility scripts
│   ├── validate-env.js       # Environment validation
│   └── create-user.js        # Test user creation
├── firestore.rules           # Firestore security rules
├── .env.local                # Environment variables (YOU NEED TO FILL THIS)
└── package.json              # Dependencies and scripts

Required Environment Variables:

See .env.local.template for complete list.

Quick Setup:

1. Copy .env.local.template to .env.local (already done)
2. Fill in Firebase credentials from Firebase Console
3. Fill in Stripe credentials from Stripe Dashboard
4. Run npm run validate-env to verify
5. Restart dev server if needed

Detailed instructions: QUICK_START.md

• Configure environment variables
• Sign up as Owner account
• Subscribe to Pro plan (Stripe test mode)
• Create a job posting
• Sign up as Seeker account (incognito window)
• Browse jobs and view details
• Submit application
• Review application as Owner
• Update application status

Detailed test flows: TESTING.md

To test the complete subscription flow with real Stripe webhook events:

Prerequisites:

• Stripe CLI installed
• .env.local configured with Stripe keys
• Dev server running on localhost:3000

Steps:

1. Start Stripe webhook forwarding (in a new terminal):

   stripe listen --forward-to localhost:3000/api/stripe/webhook

   Copy the webhook signing secret (whsec_...) and update STRIPE_WEBHOOK_SECRET in .env.local

2. Trigger a test checkout session completed event:

   stripe trigger checkout.session.completed

3. Watch the logs to see:

   • Stripe CLI forwarding the webhook
   • Your app at /api/stripe/webhook processing the event
   • Firebase custom claims being updated
   • Console logs showing subscription activation

What happens:

• Stripe sends a webhook event to your local endpoint
• The webhook handler verifies the signature
• User subscription status is updated in Firebase (custom claims + Firestore)
• User gains access to Pro features instantly

For production: Configure webhook endpoints in Stripe Dashboard pointing to your deployed URL.

Verify all systems are operational:

# 1. Check health endpoint (all services should return true)
curl http://localhost:3000/api/health

# Expected: {"status":"ok","checks":{"firebase":true,"stripe":true,"environment":true}}

# 2. Verify Stripe webhook endpoint
curl http://localhost:3000/api/stripe/webhook

# Expected: {"message":"Stripe webhook endpoint ready","timestamp":"...","note":"Use POST method for webhook events"}

# 3. Verify Stripe checkout endpoint
curl http://localhost:3000/api/stripe/checkout

# Expected: {"message":"Stripe checkout endpoint ready","note":"Use POST method to create checkout sessions","config":{"mode":"subscription","tier":"ShopMatch Pro"}}

All endpoints returning JSON? ✅ Your Stripe integration is working!

⚠️ Webhook Security: The webhook endpoint uses raw body signature verification per Stripe's security best practices. This prevents spoofed events and ensures only genuine Stripe webhooks are processed.

• ✅ Firebase security rules for Firestore
• ✅ Role-based access control (owner/seeker)
• ✅ Stripe webhook signature verification
• ✅ Server-side authentication with Firebase Admin
• ✅ Custom claims for subscription access
• ✅ Input validation with Zod schemas
• ✅ Protected API routes with token verification

✓ Compiled successfully
✓ All TypeScript checks passing
✓ Zero ESLint errors
✓ 19 routes (8 pages, 11 API endpoints)
✓ Bundle size: 245 kB shared chunks
✓ Build time: ~3 seconds with Turbopack

Production Site: shopmatch-pro.vercel.app

Test Accounts:

Employer Account (can subscribe):
Email: owner@test.com
Password: testtest123

Job Seeker Account:
Email: seeker@test.com
Password: testtest123

Stripe Test Card:
4242 4242 4242 4242 | Any future date | Any CVC

Deployment Details:

• Hosted on Vercel with auto-deployment from main branch
• Firebase Firestore for database with security rules
• Stripe integration in test mode (full functionality)
• CI/CD via GitHub Actions (lint, build, security scans)
• Environment variables securely configured

For deployment documentation, see DEPLOYMENT.md

Dev server won't start:

# Kill process on port 3001
lsof -ti:3001 | xargs kill -9
npm run dev

Firebase errors:

• Verify all NEXT_PUBLIC_FIREBASE_* variables are set
• Check FIREBASE_PRIVATE_KEY format (should include \n)
• Restart dev server after .env.local changes

Stripe errors:

• Verify STRIPE_SECRET_KEY starts with sk_test_
• Check STRIPE_PRICE_ID_PRO is correct
• Use test card 4242 4242 4242 4242 for testing

More troubleshooting: PRODUCTION_DEPLOYMENT_GUIDE.md

Development: Complete
Deployment: Live on Vercel
Testing: All user flows verified
Documentation: Comprehensive
Purpose: Portfolio demonstration

• ✅ User authentication (Email + Google OAuth)
• ✅ Role-based access (Employer vs Job Seeker)
• ✅ Job posting and management
• ✅ Application submission and tracking
• ✅ Stripe subscription integration
• ✅ Webhook processing
• ✅ Real-time database updates
• ✅ Responsive design
• ✅ Security rules enforced

• Automated test suite (Jest + Playwright)
• Email notifications
• Advanced search/filtering
• Analytics dashboard
• API rate limiting
• Resume parsing

See FUTURE_ROADMAP.md for complete feature roadmap.

This is a portfolio demonstration project built to showcase professional full-stack development capabilities.

Interested in working together?

• Review the Portfolio Showcase for detailed technical achievements
• Explore the Architecture Documentation to see system design
• Check out the live demo to see it in action

For Employers: This project demonstrates my ability to build production-grade applications from concept to deployment.

For Clients: I can build similar custom solutions for your business needs.

ShopMatch Pro is licensed under the MIT License. See LICENSE for the full license text.

This project uses various open-source packages. All dependencies have been reviewed for license compatibility with commercial use. See THIRD_PARTY_LICENSES.md for complete licensing information.

Key Points:

• ✅ All dependencies are permissively licensed (MIT, Apache-2.0, BSD, ISC)
• ✅ Compatible with commercial and proprietary software
• ✅ Dual-licensed packages use BSD option (node-forge)
• ✅ No strong copyleft licenses (GPL, AGPL) in distribution

FOSSA Configuration: License scanning policy is configured in .fossa.yml.

• Lines of Code: ~15,000+ (TypeScript, React, API routes)
• Build Size: 245 KB shared chunks (optimized)
• Build Time: ~3 seconds (Turbopack)
• API Endpoints: 11 RESTful routes
• Pages: 8 user-facing pages
• Components: 30+ reusable React components
• Security Rules: Comprehensive Firestore rules
• Documentation: 20+ technical documents

Built with ❤️ using Next.js 15, Firebase, and Stripe

Project Type: Portfolio Demonstration
Status: Production-Ready (Test Mode)
Last Updated: October 2025