aihr

README

AI-HR

An intelligent AI interview platform that revolutionizes the interview process through advanced neural network models and web-based services.

Overview

AI-HR provides a comprehensive web-based solution for:

• Interview Preparation: Help candidates practice and prepare for job interviews with realistic scenarios
• Automated Interviews: Conduct interviews with applicants using AI-powered conversation and analysis
• Real-time Speech Processing: Voice-to-text and text-to-voice capabilities via WebSocket connections
• CV-based Question Generation: Generate targeted interview questions based on user resumes

Architecture

Backend Services

The solution leverages 4 specialized AI models integrated with Yandex Cloud:

1. Speech-to-Text (STT) - Real-time voice recognition via WebSocket
2. Large Language Model (LLM) - Interview question generation and answer evaluation
3. Text-to-Speech (TTS) - Natural voice synthesis for questions
4. CV Parser - Extracts information from resumes to generate targeted questions

Frontend

• Vue.js 3 - Modern reactive frontend framework
• Real-time WebSocket - For speech recognition and audio playback
• Responsive Design - Mobile-friendly interview interface

Database

• PostgreSQL - User management, interview storage, and session tracking
• SQLC - Type-safe SQL query generation

Features

• User Authentication - JWT-based auth with email/OAuth support
• Interview Management - Create, track, and review interview sessions
• Multi-modal Questions - Both text and voice-based questions
• Real-time Speech Recognition - WebSocket-based voice processing
• AI-powered Evaluation - Automated scoring and feedback
• Premium Subscriptions - Tiered access with interview limits
• Progress Tracking - Step-by-step interview progression
• Responsive UI - Works on desktop and mobile devices

Setup

Prerequisites

• Go 1.19+ installed
• PostgreSQL database
• Yandex Cloud account with IAM token
• Node.js 16+ (for frontend development)

Installation

1. Clone the repository

   git clone https://github.com/d1nch8g/aihr
   cd aihr
   

2. Install Go dependencies

   go mod download
   

3. Set up the database

   Create a PostgreSQL database and run migrations:

   # Update database connection in .env file
   # Run database migrations (adjust path as needed)
   psql -d your_database -f migrations/schema.sql
   

4. Configure environment variables

   Create a .env file in the project root:

   # Required Yandex Cloud settings
   AIHR_IAM_TOKEN="your-yandex-iam-token"
   AIHR_FOLDER_ID="your-yandex-folder-id"
   
   # Server configuration
   AIHR_HOST="localhost"
   AIHR_PORT="8080"
   AIHR_DATABASE="postgresql://user:password@localhost:5432/aihr?sslmode=disable"
   
   # Authentication
   AIHR_AUTH_MODE="dev"  # or "prod"
   AIHR_JWT_SECRET="your-secure-jwt-secret"
   AIHR_JWT_EXPIRY="24"  # hours
   
   # Optional: Production email settings
   AIHR_SMTP_HOST="smtp.gmail.com"
   AIHR_SMTP_PORT="587"
   AIHR_SMTP_USER="your-email@gmail.com"
   AIHR_SMTP_PASSWORD="your-app-password"
   AIHR_FROM_EMAIL="your-email@gmail.com"
   
   # Optional: Yandex OAuth (for production)
   AIHR_YANDEX_CLIENT_ID="your-yandex-client-id"
   AIHR_YANDEX_CLIENT_SECRET="your-yandex-client-secret"
   AIHR_YANDEX_REDIRECT_URL="https://yourdomain.com/auth/callback"
   
   # AI Service Configuration
   AIHR_STT_SAMPLE_RATE="16000"
   AIHR_STT_LANGUAGE="ru-RU"  # or "en-US"
   AIHR_STT_PAUSE_TIMEOUT="3"
   AIHR_STT_TIMEOUT="30"
   
   AIHR_TTS_VOICE="marina"  # or "alena", "jane", etc.
   AIHR_TTS_SPEED="1.0"
   AIHR_TTS_VOLUME="0.0"
   AIHR_TTS_SAMPLE_RATE="22050.0"
   AIHR_TTS_TIMEOUT="30"
   
   AIHR_GPT_MAX_TOKENS="2000"
   AIHR_GPT_TEMPERATURE="0.6"
   AIHR_GPT_TIMEOUT="30"
   
   # Optional settings
   AIHR_LOG_LEVEL="info"  # debug, info, warn, error
   AIHR_DEV_MODE="true"   # enables development features
   

5. Build and run the application

   # Generate code (if needed)
   go generate ./...
   
   # Run the server
   go run main.go
   

6. Access the application

   Open your browser and navigate to http://localhost:8080

API Documentation

The API documentation is available via Swagger UI at /swagger/ when the server is running.

Key Endpoints

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• GET /api/auth/me - Get current user info
• POST /api/interviews/generate - Generate new interview
• GET /api/interviews - List user interviews
• POST /api/interviews/{uuid}/answer - Submit interview answer
• POST /api/interviews/{uuid}/finish - Complete interview and get results
• GET /api/interviews/speech-recognition - WebSocket for speech recognition
• GET /api/interviews/text-to-speech - WebSocket for text-to-speech

Usage

For Job Seekers

1. Register/Login - Create an account or sign in
2. Update CV - Upload your resume in the account settings
3. Generate Interview - Create a new interview with 1-20 questions
4. Take Interview - Answer questions via text or voice
5. Review Results - Get AI-powered feedback and scoring

For Developers

The platform provides WebSocket APIs for real-time speech processing:

Speech Recognition WebSocket

const ws = new WebSocket(
  "ws://localhost:8080/api/interviews/speech-recognition?token=your_jwt_token"
);

// Send configuration
ws.send(
  JSON.stringify({
    type: "config",
    config: { sampleRate: 16000 },
  })
);

// Send audio data
ws.send(
  JSON.stringify({
    type: "audio",
    data: audioByteArray,
  })
);

// Receive recognized text
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === "text") {
    console.log("Recognized:", data.text);
  }
};

Text-to-Speech WebSocket

const ws = new WebSocket(
  "ws://localhost:8080/api/interviews/text-to-speech?token=your_jwt_token"
);

// Send text for synthesis
ws.send(
  JSON.stringify({
    type: "text",
    text: "Hello, this is a test message",
  })
);

// Receive audio data
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === "audio") {
    // Play audio data
    playAudioData(data.data);
  }
};

Frontend Development

The frontend is built with Vue.js 3 and is embedded in the Go binary using go-bindata.

Development Setup

# Install Node.js dependencies (if developing frontend)
npm install

# Build frontend assets
npm run build

# Generate Go bindata (if frontend changed)
go-bindata -pkg public -o gen/public/bindata.go -prefix "dist/" dist/...

Key Frontend Features

• Responsive Design - Works on desktop and mobile
• Real-time Audio - WebSocket-based speech processing
• Progress Tracking - Visual interview progress indicators
• Multi-language Support - i18n ready
• Premium Features - Interview limits and subscription handling

Deployment

Production Configuration

1. Set AIHR_AUTH_MODE="prod" in environment
2. Configure secure JWT secret
3. Set up SMTP or OAuth for authentication
4. Use HTTPS with proper SSL certificates
5. Configure production database

Docker Deployment

FROM golang:1.19-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod download
RUN go build -o aihr main.go

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/aihr .
CMD ["./aihr"]

Troubleshooting

Common Issues

• Database Connection: Ensure PostgreSQL is running and connection string is correct
• Yandex Cloud Access: Verify IAM token and folder ID are valid
• WebSocket Connections: Check firewall settings and CORS configuration
• Audio Issues: Ensure browser has microphone permissions
• Build Errors: Run go mod tidy and go generate ./...

Debug Mode

Set AIHR_LOG_LEVEL="debug" for detailed logging:

AIHR_LOG_LEVEL="debug" go run main.go

Health Check

Check if the service is running:

curl http://localhost:8080/health

Contributing

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

Development Guidelines

• Follow Go best practices and use gofmt
• Write tests for new features
• Update API documentation for new endpoints
• Ensure frontend builds without errors
• Test WebSocket connections thoroughly

License

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

Support

For support and questions:

• Create an issue on GitHub
• Check the API documentation at /swagger/
• Review the troubleshooting section above

Roadmap

• Move to tag system, questions will be generated for tags and stored in database, not to regenerate every time
• Multi-language interview support
• Company dashboard for HR teams