convez.ai
PluginAutomaçãoAvançado
oluwatimilehinawoniyi

Paladin - Assistente de Candidaturas com IA

oluwatimilehinawoniyi/paladin-be

Automatize candidaturas: análise de CV + carta de apresentação + envio por email

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema backend completo que automatiza candidaturas a vagas analisando CVs com Claude AI, gerando cartas de apresentação personalizadas e enviando candidaturas via Gmail. Gerencia múltiplos perfis profissionais com armazenamento seguro em S3 e rastreamento de status de aplicações.

Instalação

$npx convez-ai oluwatimilehinawoniyi/paladin-be

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 10 meses
Versão
—
Issues abertas
0
Contribuidores
3

Casos de uso

  • Candidatos em busca ativa gerenciando múltiplas aplicações simultaneamente
  • Geração automática de cartas de apresentação personalizadas por vaga
  • Rastreamento centralizado de status de candidaturas (enviado, entrevista, rejeitado, aceito)

Veredito

Solução robusta para automação de candidaturas com padrões production-grade (circuit breakers, retry exponencial, fallbacks inteligentes). Excelente para quem precisa escalar processos de seleção ou gerenciar múltiplas candidaturas com consistência.

README

A tradução para o português deste README ainda está na fila.

Paladin - AI-Powered Job Application Assistant

A comprehensive backend system that streamlines job applications by leveraging AI to analyze CVs, generate tailored cover letters, and manage job application workflows with automated email submission.

Features

Core Functionality

  • OAuth2 Authentication - Secure Google OAuth2 integration with token management
  • Profile Management - Create and manage multiple professional profiles with CVs
  • CV Storage - Secure S3-based CV storage with upload, download, and deletion
  • AI Job Analysis - Claude AI integration for intelligent CV-job description matching
  • Smart Cover Letter Generation - AI-powered personalized cover letters
  • Automated Email Sending - Direct job application submission via Gmail API
  • Application Tracking - Track application status (SENT, INTERVIEW, REJECTED, ACCEPTED, FOLLOW_UP)

Technical Highlights

  • Spring Boot 3.x with modern Java practices
  • JPA/Hibernate for robust data management
  • AWS S3 integration for file storage
  • Anthropic Claude AI for intelligent analysis
  • Gmail API for automated email sending
  • Scheduled token refresh to maintain OAuth2 sessions
  • RESTful API design with comprehensive error handling

Resilience & Reliability Features

Built with production-grade resilience patterns to handle external service failures gracefully:

Async Processing

  • Non-blocking email sending with custom thread pool (5-10 threads)
  • Instant API responses while operations complete in background
  • Configurable queue capacity (50 tasks) for load management

Automatic Retry Logic

  • Gmail API: 3 retries with exponential backoff (2s → 4s → 8s)
  • Claude AI: 3 retries with exponential backoff (1s → 2s → 4s)
  • Intelligent exception classification (retry transient failures only)

Circuit Breakers (Resilience4j)

  • Gmail Service Circuit:
    • Opens after 50% failure rate (10 call sliding window)
    • 30s recovery wait period
    • Automatic half-open testing (3 calls)
  • Claude AI Service Circuit:
    • Opens after 60% failure rate (10 call sliding window)
    • 60s recovery wait period (AI services need more time)
    • Automatic half-open testing (2 calls)
  • Fast-fail when services are down (no wasted retries)
  • Automatic recovery detection

Production-Ready Fallbacks

  • Gmail Failures: Updates job application status to FAILED_TO_SEND
    • Users see failed applications in dashboard
    • Manual retry available when service recovers
    • No silent failures
  • AI Failures: Returns professional template cover letter
    • Users can still submit applications
    • Clear warning message about AI unavailability
    • Customizable template response

Monitoring & Observability

  • Circuit breaker health indicators via Spring Actuator
  • Real-time circuit state monitoring
  • Circuit breaker events tracking
  • Detailed metrics for failure rates and response times
  • Comprehensive logging

Status Tracking

Application statuses include:

  • SENT - Successfully delivered
  • FAILED_TO_SEND - Delivery failed (circuit open or retries exhausted)
  • INTERVIEW - Interview scheduled
  • REJECTED - Application rejected
  • ACCEPTED - Offer received
  • FOLLOW_UP - Awaiting response

Prerequisites

  • Java 17 or higher
  • Maven 3.6+
  • PostgreSQL (or your preferred database)
  • AWS Account (for S3)
  • Google Cloud Console project (for OAuth2 and Gmail API)
  • Anthropic API key (for Claude AI)

️ Installation & Setup

1. Clone the Repository

git clone https://github.com/oluwatimilehinawoniyi/paladin-be.git
cd paladin-be

2. Configure Environment Variables

Create application.yml in src/main/resources/:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/paladin_db
    username: your_db_username
    password: your_db_password
    
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: ${GOOGLE_CLIENT_ID}
            client-secret: ${GOOGLE_CLIENT_SECRET}
            redirect-uri: "{baseUrl}/oauth2/callback/google"
            scope:
              - email
              - profile
              - https://www.googleapis.com/auth/gmail.send

  ai:
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}
      chat:
        options:
          model: claude-sonnet-4-5-20250929

aws:
  access-key-id: ${AWS_ACCESS_KEY}
  secret-access-key: ${AWS_SECRET_KEY}
  s3:
    bucket-name: ${AWS_S3_BUCKET}
    region: ${AWS_REGION}

app:
  frontend:
    url: http://localhost:5173

3. Set Up Google OAuth2

  1. Go to Google Cloud Console
  2. Create a new project or select existing
  3. Enable Google+ API and Gmail API
  4. Create OAuth 2.0 credentials
  5. Add authorized redirect URIs:
    • http://localhost:8080/oauth2/callback/google
    • Your production URL

4. Set Up AWS S3

  1. Create an S3 bucket
  2. Configure CORS policy:
[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": []
  }
]

5. Build & Run

# Build the project
mvn clean install

# Run the application
mvn spring-boot:run

The API will be available at http://localhost:8080

API Documentation

Authentication Endpoints

Login via Google

GET /oauth2/authorization/google

Get Current User

GET /api/auth/me

Logout

POST /api/auth/logout

Profile Management

Create Profile with CV

POST /api/v1/profiles
Content-Type: multipart/form-data

{
  "title": "Senior Software Engineer",
  "summary": "Experienced developer...",
  "skills": ["Java", "Spring Boot", "AWS"],
  "file": <CV_FILE>
}

Get User's Profiles

GET /api/v1/profiles/me

Get Profile by ID

GET /api/v1/profiles/{profileId}

Update Profile

PATCH /api/v1/profiles/{profileId}
Content-Type: application/json

{
  "title": "Updated Title",
  "summary": "Updated summary",
  "skills": ["New", "Skills"]
}

Delete Profile

DELETE /api/v1/profiles/{profileId}

CV Management

Upload CV

POST /api/v1/cv/upload
Content-Type: multipart/form-data

{
  "file": <CV_FILE>,
  "profileId": "uuid"
}

Download CV

GET /api/v1/cv/{cvId}/download

Update CV

PUT /api/v1/cv/{cvId}
Content-Type: multipart/form-data

{
  "file": <NEW_CV_FILE>
}

Delete CV

DELETE /api/v1/cv/{cvId}

Job Application

Analyze Job Application (AI-Powered)

POST /api/v1/job-applications/analyze-application
Content-Type: application/json

{
  "profileId": "uuid",
  "jobDescription": "Full job posting text..."
}

Response:

{
  "jobDetails": {
    "company": "Tech Corp",
    "position": "Senior Developer",
    "jobEmail": "hr@techcorp.com"
  },
  "coverLetter": "Dear Hiring Manager...",
  "matchAnalysis": {
    "overallMatchPercentage": 85,
    "strengths": ["Strong backend experience", "AWS expertise"],
    "gaps": ["Limited frontend experience"],
    "recommendation": "Highly recommended to apply",
    "confidenceLevel": "High"
  }
}

Send Job Application

POST /api/v1/job-applications/send
Content-Type: application/json

{
  "profileId": "uuid",
  "company": "Tech Corp",
  "jobTitle": "Senior Developer",
  "jobEmail": "hr@techcorp.com",
  "subject": "Application for Senior Developer",
  "bodyText": "Cover letter content..."
}

Get My Applications

GET /api/v1/job-applications/me

Update Application Status

PATCH /api/v1/job-applications/{applicationId}/status
Content-Type: application/json

"INTERVIEW"

Cover Letter Generation

Generate Cover Letter Template

GET /api/v1/cover-letters/generate/{category}?candidateName=John&companyName=TechCorp&position=Developer

Categories: professional, enthusiastic, results, conversational

User Management

Get Current User Details

GET /api/v1/users/me

Delete Account

DELETE /api/v1/users/me

This permanently deletes all user data including profiles, CVs, and applications

Monitoring & Health Checks

Check Application Health & Circuit Breaker Status

GET /actuator/health

Response:

{
  "status": "UP",
  "components": {
    "circuitBreakers": {
      "status": "UP",
      "details": {
        "gmailService": {
          "status": "UP",
          "state": "CLOSED",
          "failureRate": "0.0%",
          "slowCallRate": "0.0%",
          "bufferedCalls": 10,
          "failedCalls": 0
        },
        "claudeAIService": {
          "status": "UP",
          "state": "CLOSED",
          "failureRate": "0.0%",
          "slowCallRate": "0.0%",
          "bufferedCalls": 10,
          "failedCalls": 0
        }
      }
    },
    "db": {
      "status": "UP"
    }
  }
}

Circuit Breaker States:

  • CLOSED - Normal operation (service healthy) ✓
  • OPEN - Service failing, fast-failing requests ⊘
  • HALF_OPEN - Testing recovery after wait period
  • FORCED_OPEN - Manually disabled for maintenance

View Circuit Breaker Events

GET /actuator/circuitbreakerevents

Shows recent circuit breaker events including:

  • State transitions (CLOSED → OPEN → HALF_OPEN → CLOSED)
  • Success and failure events
  • Error details and timestamps

Example Response:

{
  "circuitBreakerEvents": [
    {
      "circuitBreakerName": "gmailService",
      "type": "SUCCESS",
      "creationTime": "2024-01-08T10:30:15.123Z"
    },
    {
      "circuitBreakerName": "claudeAIService",
      "type": "ERROR",
      "creationTime": "2024-01-08T10:31:20.456Z",
      "errorMessage": "Claude AI API call failed"
    }
  ]
}

View Detailed Metrics

GET /actuator/metrics/resilience4j.circuitbreaker.calls

Provides detailed metrics for circuit breaker calls:

  • Total calls
  • Successful calls
  • Failed calls
  • Call duration percentiles

Architecture

┌─────────────────┐
│   Frontend      │
│   (SvelteKit)   │
└────────┬────────┘
         │
         │ REST API
         │
┌────────▼───────────────────────────────────┐
│          Spring Boot Backend               │
│                                            │
│  ┌──────────────┐  ┌──────────────┐        │
│  │ Controllers  │  │   Services   │        │
│  └──────┬───────┘  └──────┬───────┘        │
│         │                 │                │
│  ┌──────▼─────────────────▼───────┐        │
│  │      Business Logic            │        │
│  │  - OAuth2 Management           │        │
│  │  - File Upload/Download        │        │
│  │  - AI Analysis                 │        │
│  │  - Email Automation            │        │
│  └──────┬─────────────────────────┘        │
│         │                                  │
│  ┌──────▼──────────┐  ┌─────────────┐      │
│  │   Repositories  │  │   Mappers   │      │
│  └──────┬──────────┘  └─────────────┘      │
└─────────┼──────────────────────────────────┘
          │
    ┌─────┴─────────────────────────┐
    │                               │
┌───▼────┐  ┌──────┐  ┌──────────┐ ┌▼─────┐
│   DB   │  │  S3  │  │ Gmail API│ │Claude│
└────────┘  └──────┘  └──────────┘ └──────┘

Security Features

  • OAuth2 Authentication with Google
  • Session Management with automatic token refresh
  • User Authorization - Users can only access their own data
  • Secure File Storage in AWS S3
  • CORS Configuration for frontend integration
  • CSRF Protection disabled for API-only backend
  • HTTPS Strict Transport Security headers

Database Schema

Users

  • OAuth2 user information
  • Token management (access token, refresh token, expiry)
  • Relationship to profiles

Profiles

  • Multiple profiles per user
  • Title, summary, skills
  • One-to-one relationship with CV

CVs

  • Stored in S3
  • Metadata in database (filename, URL, size, content type)

Job Applications

  • Track all applications
  • Status management
  • Linked to profiles

Deployment

Docker Deployment

FROM eclipse-temurin:17-jdk-alpine
WORKDIR /app
COPY target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
# Build
docker build -t paladin-be .

# Run
docker run -p 8080:8080 \
  -e GOOGLE_CLIENT_ID=your_client_id \
  -e GOOGLE_CLIENT_SECRET=your_secret \
  -e AWS_ACCESS_KEY=your_key \
  -e AWS_SECRET_KEY=your_secret \
  -e ANTHROPIC_API_KEY=your_key \
  paladin-backend

Contributing

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

Author

Your Name - Oluwatimilehin Awoniyi

Ver o original no GitHub

Bom para

Relacionados