Skip to content

README.md

Latest commit

 

History

History
311 lines (235 loc) · 10 KB

README.md

File metadata and controls

311 lines (235 loc) · 10 KB

ClueFind - Developer Portfolio Platform

ClueFind Next.js TypeScript Prisma PostgreSQL

Build Your Developer Portfolio. No Nonsense. Pure Impact.

Live Demo • Documentation • Report Bug

🎯 Overview

ClueFind is a modern developer portfolio platform that helps developers showcase their skills, projects, and achievements. Built with Next.js 15, TypeScript, and PostgreSQL, it provides a complete solution for developers to build their online presence and connect with recruiters.

Key Differentiators

  • AI-Powered Profile Builder - Generate professional summaries and project descriptions
  • Skill Endorsement Network - Get verified vouches from colleagues
  • GitHub Integration - Automatic repository syncing and activity tracking
  • Brutalist Design - Clean, professional, no-nonsense UI
  • Recruiter Dashboard - Special features for talent discovery

✨ Features

For Developers

  • Portfolio Builder - Drag-and-drop project showcases with AI-generated descriptions
  • GitHub Integration - Auto-sync profile data and activity tracking
  • Skill Management - Add skills and receive peer endorsements
  • Resume AI Review - Get brutally honest feedback from AI-powered senior engineers
  • Public Profiles - Custom cluefind.software/{username} URLs
  • Leaderboard - Compete and showcase achievements
  • Social Links - Connect GitHub, LinkedIn, and other platforms

For Recruiters

  • Advanced Search - Filter by skills, experience, location
  • Candidate Profiles - Complete developer portfolios with verified skills
  • GitHub Analytics - Profile quality and activity metrics
  • Skill Verification - Peer-endorsed technical skills
  • Contact Integration - Direct communication channels

🛠 Tech Stack

Frontend

  • Framework: Next.js 15.0.3 (App Router)
  • Language: TypeScript 5.0
  • Styling: Tailwind CSS 3.3 + Custom Brutalist Design System
  • UI Components: Radix UI + Custom Components
  • Forms: React Hook Form + Zod Validation
  • Icons: Lucide React
  • Animations: React PowerGlitch + Custom CSS
  • Notifications: React Hot Toast

Backend

  • Runtime: Node.js 18
  • Framework: Next.js API Routes
  • Database: PostgreSQL
  • ORM: Prisma 5.7
  • Authentication: Google OAuth 2.0
  • File Upload: Multer + Cloudinary
  • AI Integration: OpenAI GPT-4

External Services

  • Image Storage: Cloudinary CDN
  • GitHub API: GitHub REST API v3
  • AI Services: OpenAI API
  • Authentication: Google OAuth

DevOps & Deployment

  • Containerization: Docker + Multi-stage builds
  • CI/CD: GitHub Actions
  • Container Registry: Docker Hub
  • Hosting: AWS EC2
  • Reverse Proxy: Nginx (optional)

🏗 Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Client (Browser)                      │
└────────────────────┬────────────────────────────────────────┘
                     │ HTTPS
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                    Next.js Application                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Frontend   │  │   API Routes │  │  Middleware  │      │
│  │   (React)    │  │   (Server)   │  │   (Auth)     │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└────────────────────┬────────────────────────────────────────┘
                     │
         ┌───────────┼───────────┐
         │           │           │
         ▼           ▼           ▼
┌─────────────┐ ┌──────────┐ ┌──────────┐
│ PostgreSQL  │ │ GitHub   │ │Cloudinary│
│  Database   │ │   API    │ │   CDN    │
└─────────────┘ └──────────┘ └──────────┘

📁 Project Structure

src/
├── app/                        # Next.js App Router
│   ├── (dashboard)/            # Protected dashboard routes
│   ├── (onboarding)/           # User onboarding flow
│   ├── [username]/             # Public profile pages
│   ├── api/                    # API Routes
│   │   ├── auth/               # Authentication endpoints
│   │   ├── ai/                 # AI-powered features
│   │   ├── profiles/           # Profile management
│   │   ├── onboarding/         # Onboarding APIs
│   │   └── upload/             # File upload handling
│   ├── leaderboard/            # Leaderboard page
│   └── globals.css             # Global styles + Brutalist design
├── components/                 # React Components
│   ├── auth/                   # Authentication components
│   ├── forms/                  # Form components
│   ├── portfolio/              # Portfolio-specific components
│   └── ui/                     # Reusable UI components
├── lib/                        # Utility Libraries
│   ├── services/               # Business logic services
│   ├── validations/            # Zod schemas
│   └── ai.ts                   # AI integration
└── types/                      # TypeScript definitions

🗄 Database Schema

Core Models

  • User - Authentication, profile info, role (DEVELOPER/RECRUITER UI-facing; stored as STUDENT/RECRUITER)
  • Profile - Skills, projects, GitHub data, social links
  • Vouch - Skill endorsements with verification
  • VouchAction - Daily vouch limits and tracking

Key Relationships

  • User ↔ Profile (1:1)
  • Profile ↔ Vouch (1:N)
  • User ↔ Vouch (1:N)

🚀 Getting Started

Prerequisites

  • Node.js 18+
  • PostgreSQL 15+
  • Docker (optional)

Quick Start

# Clone repository
git clone https://github.com/yourusername/cluefind.git
cd cluefind

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env with your configuration

# Setup database
npm run db:generate
npm run db:migrate

# Start development server
npm run dev

Visit http://localhost:3000

Environment Variables

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/cluefind"

# Authentication
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-key"
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# External Services
CLOUDINARY_CLOUD_NAME="your-cloud-name"
CLOUDINARY_API_KEY="your-api-key"
CLOUDINARY_API_SECRET="your-api-secret"
OPENAI_API_KEY="your-openai-key"
GITHUB_TOKEN="your-github-token"

🐳 Docker Deployment

Build & Run

# Build image
docker build -t cluefind:latest .

# Run container
docker run -d \
  -p 3000:3000 \
  --name cluefind \
  --env-file .env \
  --restart unless-stopped \
  cluefind:latest

CI/CD Pipeline

Automated deployment via GitHub Actions:

  1. Push to main branch
  2. Build Docker image
  3. Push to Docker Hub
  4. Deploy to AWS EC2
  5. Update running container

📡 API Endpoints

Authentication

  • POST /api/auth/google - Google OAuth
  • GET /api/auth/me - Current user
  • POST /api/auth/signout - Sign out

Profiles

  • GET /api/profiles - List profiles (with search)
  • GET /api/profiles/[id] - Get profile
  • PUT /api/profiles/[id]/skills - Update skills
  • POST /api/profiles/[id]/vouches - Create vouch

AI Features

  • POST /api/ai/review - AI resume review
  • POST /api/ai/review-resume - Resume analysis

Onboarding

  • POST /api/onboarding/check-username - Username availability
  • POST /api/onboarding/generate-profile - AI profile generation
  • POST /api/onboarding/github-data - GitHub integration

🎨 Design System

Brutalist UI Components

  • Buttons: Primary, Secondary, Outline variants with hover effects
  • Cards: Brutalist cards with shadows and borders
  • Forms: Input fields with brutalist styling
  • Typography: Monospace fonts with uppercase styling
  • Colors: High contrast palette with accent colors
  • Animations: Glitch effects and smooth transitions

Key Design Principles

  • High Contrast - Black borders, bright accents
  • Monospace Typography - Technical, developer-focused
  • Brutalist Shadows - 3D effect with offset shadows
  • Minimal Color Palette - Primary, accent, and muted tones
  • Responsive Design - Mobile-first approach

🤝 Contributing

  1. Fork the repository
  2. Create feature branch (git checkout -b feature/amazing-feature)
  3. Commit changes (git commit -m 'Add amazing feature')
  4. Push to branch (git push origin feature/amazing-feature)
  5. Open Pull Request

Development Guidelines

  • Follow TypeScript best practices
  • Use ESLint and Prettier
  • Write meaningful commit messages
  • Update documentation for new features

📄 License

MIT License - see LICENSE file for details.