# Interview Assistant - Documentation

## n8n Workflow Integration

### Overview
This directory contains n8n workflow templates for integrating AI-powered question generation with the Interview Assistant application.

### Files

#### `n8n-cv-analysis-workflow.json`
Complete n8n workflow for CV analysis and interview question generation.

**Features:**
- Receives CV data via webhook from Angular app
- Processes CV content for key information extraction
- Generates personalized interview questions using OpenAI/Claude
- Returns structured question bank with categories and difficulty levels
- Includes error handling and fallback questions

**Setup Instructions:**
1. **Import to n8n:**
   - Open your n8n instance
   - Go to "Import from File" or use Ctrl+I
   - Select `n8n-cv-analysis-workflow.json`

2. **Configure OpenAI API:**
   - Add your OpenAI API key to the "Generate Questions (OpenAI)" node
   - Or replace with Claude/other AI provider if preferred

3. **Test the Webhook:**
   - Copy the webhook URL from the imported workflow
   - Update Angular environment files if URL differs

4. **Authentication:**
   - Ensure webhook is protected by Authelia (as configured)
   - Test authentication flow with Angular app

### API Reference

#### Webhook Endpoint
- **URL:** `https://n8n.gm-tech.org/webhook/cv-analysis`
- **Method:** POST
- **Authentication:** Authelia session-based
- **Content-Type:** application/json

#### Request Format
```json
{
  "analysisId": "uuid-string",
  "cvProfile": {
    "personalInfo": {
      "fullName": "string",
      "email": "string"
    },
    "skills": [
      {
        "name": "string",
        "category": "technical|soft|language",
        "yearsOfExperience": number
      }
    ],
    "experience": [...],
    "education": [...],
    "parsedText": "full CV content as string"
  }
}
```

#### Response Format
```json
{
  "status": "completed|failed|processing",
  "analysisId": "uuid-string",
  "questionBankId": "generated-id",
  "questionsGenerated": number,
  "candidateName": "string",
  "questions": [
    {
      "id": number,
      "question": "string",
      "category": "technical|behavioral|scenario",
      "difficulty": "easy|medium|hard",
      "expectedSkills": ["skill1", "skill2"],
      "reasoning": "why this question is relevant"
    }
  ],
  "metadata": {
    "skillsAnalyzed": number,
    "experienceYears": number,
    "processingTime": "ISO timestamp"
  }
}
```

### Security Considerations

- **Authelia Protection:** All webhooks require valid authentication
- **CORS Configuration:** Properly configured for Angular app origin
- **Data Sanitization:** CV data is processed securely
- **No Data Persistence:** Workflow processes data in memory only
- **Error Handling:** Graceful fallbacks prevent data exposure

### Troubleshooting

**Common Issues:**
1. **401 Authentication Error:** Ensure user is logged into Authelia
2. **Workflow Not Found:** Check if workflow is imported and activated
3. **OpenAI API Errors:** Verify API key configuration and rate limits
4. **Webhook Timeout:** Check n8n server performance and AI response times

**Debug Mode:**
- Enable debug logging in n8n workflow nodes
- Check Angular console for detailed error messages
- Use test scripts provided in project root for debugging