HexcAI

Hire Smarter. Hire by Code.

AI-powered developer evaluation & hiring platform that assesses real GitHub code, not resumes.

Features • Tech Stack • Getting Started • Project Structure • Contributing

---

📋 Overview

HexcAI transforms the developer hiring process by evaluating candidates based on their real GitHub repositories using AI-powered code analysis. The platform generates transparent Developer Scores (0-100) across multiple dimensions while respecting developer privacy and consent.

🎯 Key Benefits

For Developers:

• 📊 Get AI-evaluated Developer Score based on real code quality
• 🎓 Understand strengths and areas for improvement
• 🔒 Control visibility and recruiter access (opt-in only)
• 💼 Get discovered by recruiters without spam

For Recruiters:

• ⚡ Find top-tier developers faster
• 🔍 See real code quality before contacting
• 🎯 Filter by tech stack and skill levels
• 📈 Make data-driven hiring decisions

---

✨ Features

🧠 AI-Powered Code Analysis

• Code Quality (30%): Clean code practices, maintainability, complexity
• Architecture (20%): Design patterns, structure, scalability
• Security (20%): Vulnerability detection, best practices
• Git Practices (15%): Commit quality, branching, collaboration
• Documentation (15%): README quality, inline comments, API docs

👨‍💻 Developer Dashboard

• Analyze GitHub repositories with one-click
• View detailed score breakdowns with explanations
• Control recruiter visibility with "Open to Recruiters" toggle
• Manage incoming contact requests (accept/reject)
• Privacy-first: Contact info shared only after approval

🧑‍💼 Recruiter Discovery

• Browse high-scoring developers (≥80 score)
• Filter by technologies, frameworks, and score ranges
• View public developer profiles with code insights
• Send personalized contact requests
• Consent-based outreach system

🏆 Developer Score System

Score Range	Label	Description
90-100	🌟 Excellent	Outstanding code quality and practices
80-89	💪 Strong	Solid developer with great fundamentals
60-79	⚡ Average	Good foundation, room for growth
<60	📚 Needs Improvement	Focus on core skills development

---

🛠️ Tech Stack

Frontend

• Framework: Next.js 16.1 (App Router)
• Language: TypeScript 5.9
• Styling: Tailwind CSS 4.0
• UI Components: Radix UI, shadcn/ui
• State Management: Jotai
• Data Fetching: TanStack Query
• Forms: React Hook Form + Zod
• Animations: Motion
• Icons: Lucide React, Tabler Icons

Backend & Database

• ORM: Drizzle ORM
• Database: Neon Serverless Postgres
• Authentication: Better Auth
• API: Elysia

AI & Analytics

• AI SDK: Vercel AI SDK
• LLM Provider: Groq
• Charts: Recharts
• Flow Diagrams: XYFlow

Development Tools

• Build System: Turborepo
• Package Manager: Bun
• Linting: ESLint 9
• Formatting: Prettier
• Git Hooks: Husky + lint-staged

---

🚀 Getting Started

Prerequisites

• Node.js: >=18.0.0
• Bun: 1.2.22 or higher
• Git: Latest version
• Docker & Docker Compose: For local database and object storage

Quick Start

1. Clone the repository

   git clone https://github.com/dev0jha/HexcAI.git
   cd HexcAI

2. Start local infrastructure (PostgreSQL + MinIO)

   cd apps/web
   docker-compose up -d

   This starts:

   • PostgreSQL on port 5432 (credentials: hirexai / hirexai_password)
   • MinIO (Rustfs) on port 9000 (console on 9001)

3. Install dependencies

   bun install

4. Set up environment variables

   The .env file is already configured with default values:

   NEXT_PUBLIC_APP_URL=http://localhost:3000
   DATABASE_URL=postgresql://hirexai:hirexai_password@localhost:5432/hirexai_db
   NODE_ENV=development
   GROQ_API_KEY=your-groq-api-key
   OBJECT_STORAGE_ENDPOINT=http://localhost:9000

   Note:

   • Get a free Groq API key at groq.com
   • Replace your-groq-api-key in .env with your actual key

5. Run database migrations

   bun run db:migrate

6. Seed the database with mock data

   bun run db:seed

7. Start the development server

   bun dev

8. Open your browser

   Navigate to http://localhost:3000

---

🔐 Test Accounts

After running bun run db:seed, you can log in with:

Role	Email	Password
Candidate	john.doe@example.com	password123
Candidate	jane.smith@example.com	password123
Candidate	alex.j@example.com	password123
Candidate	sarah.w@example.com	password123
Candidate	michael.b@example.com	password123
Recruiter	hr@techcorp.com	password123
Recruiter	hiring@startupxyz.io	password123
Recruiter	recruit@enterprisesol.com	password123

---

🪣 MinIO Bucket Setup

The application automatically creates the profile-pics bucket when you first upload an image. No manual setup required.

If you want to access the MinIO console:

1. Open http://localhost:9001
2. Login with: rustfsadmin / rustfsadmin

---

Available Scripts

# Development
bun dev              # Start all apps in dev mode
bun run dev:web      # Start only web app

# Building
bun build            # Build all apps
bun run build:web    # Build only web app

# Code Quality
bun lint             # Run ESLint across all packages
bun format           # Format code with Prettier
bun format:check     # Check code formatting
bun check-types      # Type-check all packages

# Database
bun run db:generate  # Generate Drizzle migrations
bun run db:migrate   # Run database migrations
bun run db:studio    # Open Drizzle Studio
bun run db:seed      # Seed database with mock data

Seeding the Database

To populate the database with mock data for development:

bun run db:seed

This creates:

• 5 candidate users with profile data, scores, and tech stacks
• 3 recruiter users with company information
• Sample analysis results
• Sample contact requests (some accepted, some pending, some rejected)

All users have the password: password123

---

📁 Project Structure

HexcAI/
├── apps/
│   └── web/                    # Next.js 16 application
│       ├── app/                # App Router pages
│       │   ├── (auth)/        # Authentication routes
│       │   ├── dashboard/     # Developer dashboard
│       │   ├── recruiter/     # Recruiter portal
│       │   ├── profile/       # Public profiles
│       │   └── page.tsx       # Landing page
│       ├── components/         # React components
│       │   ├── ui/            # shadcn/ui components
│       │   ├── layout/        # Navbar, Footer, Sidebar
│       │   ├── developer/     # Developer-specific UI
│       │   ├── recruiter/     # Recruiter-specific UI
│       │   └── analysis/      # Score visualization
│       ├── hooks/             # Custom React hooks
│       ├── lib/               # Utilities & configs
│       ├── store/             # Jotai state atoms
│       ├── types/             # TypeScript definitions
│       └── public/            # Static assets
│
├── packages/
│   ├── ui/                    # Shared UI components
│   ├── eslint-config/         # ESLint configurations
│   └── typescript-config/     # TypeScript configs
│
├── turbo.json                 # Turborepo config
├── package.json               # Root dependencies
└── README.md                  # You are here!

---

🔧 Troubleshooting

Database Connection Issues

If you get connection errors:

# Check if PostgreSQL container is running
docker ps | grep postgres

# Restart the container
docker-compose restart postgres

MinIO Connection Issues

If image uploads fail:

# Check if MinIO container is running
docker ps | grep rustfs

# Restart the container
docker-compose restart rustfs

Reset Database

To completely reset and reseed:

docker-compose down -v     # Remove volumes
docker-compose up -d     # Restart containers
bun run db:migrate        # Run migrations
bun run db:seed          # Seed data

---

🤝 Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Commit your changes

   git commit -m "Add some amazing feature"

4. Push to the branch

   git push origin feature/amazing-feature

5. Open a Pull Request

Development Guidelines

• Follow the existing code style (enforced by ESLint/Prettier)
• Write meaningful commit messages
• Add tests for new features
• Update documentation as needed
• Ensure bun lint and bun check-types pass

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.