# Unison Service - Complete Workflow Analysis

## 🏗️ Architecture Overview

The Unison service acts as a **unified orchestration layer** that combines recommendations from multiple sources and uses Claude AI to generate optimized tech stack recommendations.

## 🔄 Complete Workflow Diagram

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           UNISON SERVICE WORKFLOW                              │
└─────────────────────────────────────────────────────────────────────────────────┘

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Client App    │───▶│   Unison Service │───▶│ Claude AI API   │
│                 │    │   (Port 8014)    │    │                 │
└─────────────────┘    └─────────┬────────┘    └─────────────────┘
                                 │
                    ┌────────────┼────────────┐
                    │            │            │
            ┌───────▼──────┐ ┌───▼────┐ ┌────▼──────┐
            │ Tech Stack   │ │Template│ │Template   │
            │ Selector     │ │Manager │ │Manager AI │
            │ (Port 8002)  │ │(8009)  │ │(Port 8013)│
            └──────────────┘ └────────┘ └───────────┘
```

## 📋 Detailed Workflow Steps

### 1. **Request Reception & Validation**
```
Client Request → Unison Service → Middleware Stack
```

**Components:**
- **Express Server** (Port 8014)
- **Security Middleware** (Helmet, CORS)
- **Rate Limiting** (100 req/15min per IP)
- **Request Validation** (Joi schema validation)
- **Body Parsing** (JSON, URL-encoded)

**Validation Rules:**
- Domain: 1-100 characters
- Budget: Positive number
- Preferred Technologies: Array of strings (1-50 chars each)
- Template ID: Valid UUID format
- Boolean flags: includeSimilar, includeKeywords, forceRefresh

### 2. **Route Processing**
```
POST /api/recommendations/unified → Unified Recommendation Handler
GET /api/recommendations/tech-stack → Tech Stack Only Handler
GET /api/recommendations/template/:id → Template Only Handler
GET /health → Health Check Handler
```

### 3. **Unified Recommendation Workflow** (Main Flow)

#### 3.1 **Input Validation**
```javascript
// Validate tech stack request parameters
const techStackRequest = { domain, budget, preferredTechnologies };
const techStackValidation = schemaValidator.validateTechStackRequest(techStackRequest);

// Validate template request if templateId provided
if (templateId) {
  const templateRequest = { templateId, includeSimilar, includeKeywords, forceRefresh };
  const templateValidation = schemaValidator.validateTemplateRequest(templateRequest);
}
```

#### 3.2 **Parallel Service Calls**
```javascript
// Always fetch from tech-stack-selector
const techStackPromise = techStackService.getRecommendations({
  domain, budget, preferredTechnologies
}).catch(error => ({ success: false, error: error.message, source: 'tech-stack-selector' }));

// Fetch from template-manager if templateId provided
const templatePromise = templateId ? 
  templateService.getAIRecommendations(templateId, { forceRefresh })
    .catch(error => ({ success: false, error: error.message, source: 'template-manager' })) :
  Promise.resolve({ success: false, error: 'No template ID provided', source: 'template-manager' });

// Execute both calls in parallel
const [techStackResult, templateResult] = await Promise.all([techStackPromise, templatePromise]);
```

#### 3.3 **Service Integration Details**

**Tech Stack Selector Integration:**
- **Endpoint**: `POST /recommend/best`
- **Data Source**: PostgreSQL + Neo4j (migrated data)
- **Features**: Price-based relationships, Claude AI recommendations
- **Response**: Array of tech stack recommendations with costs, team sizes, etc.

**Template Manager Integration:**
- **Endpoint**: `GET /api/templates/{id}/ai-recommendations`
- **Data Source**: Template database with AI analysis
- **Features**: Template-based recommendations, feature learning
- **Response**: Template-specific tech stack recommendations

#### 3.4 **Decision Logic & Fallback Strategy**

```javascript
// Check if we have at least one successful recommendation
if (!techStackResult.success && !templateResult.success) {
  return res.status(500).json({
    success: false,
    error: 'Failed to fetch recommendations from both services'
  });
}

// If only one service succeeded, return its result
if (!techStackResult.success || !templateResult.success) {
  const successfulResult = techStackResult.success ? techStackResult : templateResult;
  return res.json({
    success: true,
    data: successfulResult.data,
    source: successfulResult.source,
    message: 'Single service recommendation (other service unavailable)'
  });
}
```

#### 3.5 **Claude AI Unification** (When Both Services Succeed)

**Claude AI Integration:**
- **Model**: claude-3-sonnet-20240229
- **Max Tokens**: 4000
- **Timeout**: 30 seconds
- **API**: Anthropic Claude API

**Prompt Engineering:**
```javascript
const prompt = `You are an expert tech stack architect. I need you to analyze two different tech stack recommendations and create a single, optimized recommendation that balances cost, domain requirements, and template-feature compatibility.

## Original Request Parameters:
- Domain: ${requestParams.domain}
- Budget: $${requestParams.budget}
- Preferred Technologies: ${requestParams.preferredTechnologies?.join(', ')}
- Template ID: ${requestParams.templateId}

## Tech Stack Selector Recommendation:
${JSON.stringify(techStackRecommendation.data, null, 2)}

## Template Manager Recommendation:
${JSON.stringify(templateRecommendation.data, null, 2)}

## Your Task:
Analyze both recommendations and create a single, optimized tech stack recommendation that:
1. Balances cost-effectiveness with the budget constraint
2. Matches the domain requirements
3. Incorporates the best features from the template recommendation
4. Considers the preferred technologies when possible
5. Provides realistic team size, development time, and success metrics

## Required Output Format:
[Detailed JSON schema requirements...]`;
```

**Response Processing:**
```javascript
// Parse Claude's response
const claudeResponse = response.data.content[0].text;
const unifiedRecommendation = this.parseClaudeResponse(claudeResponse);

// Validate the unified recommendation
const validation = schemaValidator.validateUnifiedRecommendation(unifiedRecommendation);
if (!validation.valid) {
  // Fallback to tech-stack-selector recommendation
  return res.json({
    success: true,
    data: techStackResult.data,
    source: 'tech-stack-selector (fallback)',
    message: 'Claude generated invalid recommendation, using tech-stack-selector as fallback'
  });
}
```

### 4. **Response Generation & Validation**

**Schema Validation:**
- **Unified Recommendation Schema**: 18 required fields with strict validation
- **Numeric Ranges**: Monthly cost (0-10000), Setup cost (0-50000), etc.
- **String Constraints**: Team size pattern, length limits
- **Required Fields**: stack_name, monthly_cost, setup_cost, team_size, development_time, satisfaction, success_rate, frontend, backend, database, cloud, testing, mobile, devops, ai_ml, recommended_tool, recommendation_score, message

**Response Format:**
```json
{
  "success": true,
  "data": {
    "stack_name": "Optimized E-commerce Stack",
    "monthly_cost": 150,
    "setup_cost": 2000,
    "team_size": "3-5",
    "development_time": 8,
    "satisfaction": 92,
    "success_rate": 88,
    "frontend": "React",
    "backend": "Node.js",
    "database": "PostgreSQL",
    "cloud": "AWS",
    "testing": "Jest",
    "mobile": "React Native",
    "devops": "Docker",
    "ai_ml": "TensorFlow",
    "recommended_tool": "Vercel",
    "recommendation_score": 94,
    "message": "Balanced solution combining cost-effectiveness with modern tech stack"
  },
  "source": "unified",
  "message": "Unified recommendation generated successfully",
  "processingTime": 1250,
  "services": {
    "techStackSelector": "available",
    "templateManager": "available",
    "claudeAI": "available"
  },
  "claudeModel": "claude-3-sonnet-20240229"
}
```

### 5. **Error Handling & Logging**

**Error Types:**
- **Validation Errors**: Invalid input parameters
- **Service Errors**: External service failures
- **Claude AI Errors**: API failures or invalid responses
- **Schema Validation Errors**: Invalid output format
- **Network Errors**: Timeout or connection issues

**Logging Strategy:**
- **Winston Logger**: Structured JSON logging
- **Log Levels**: error, warn, info, debug
- **Log Files**: error.log, combined.log
- **Console Logging**: Development mode
- **Request Tracking**: Unique request IDs

**Fallback Mechanisms:**
1. **Single Service Fallback**: If one service fails, use the other
2. **Claude AI Fallback**: If Claude fails, use tech-stack-selector
3. **Schema Validation Fallback**: If Claude output is invalid, use tech-stack-selector
4. **Graceful Degradation**: Always return some recommendation

### 6. **Health Monitoring**

**Health Check Endpoints:**
- **Basic Health**: `/health` - Service status with external service checks
- **Detailed Health**: `/health/detailed` - Comprehensive system information

**External Service Monitoring:**
- **Tech Stack Selector**: `http://pipeline_tech_stack_selector:8002/health`
- **Template Manager**: `http://pipeline_template_manager:8009/health`
- **Response Time Tracking**: Individual service response times
- **Status Aggregation**: Overall service health status

## 🔧 Service Dependencies

### External Services
1. **Tech Stack Selector** (Port 8002)
   - **Purpose**: Budget and domain-based recommendations
   - **Data Source**: PostgreSQL + Neo4j
   - **Features**: Price analysis, Claude AI integration
   - **Health Check**: `/health`

2. **Template Manager** (Port 8009)
   - **Purpose**: Template-based recommendations
   - **Data Source**: Template database
   - **Features**: Feature learning, usage tracking
   - **Health Check**: `/health`

3. **Template Manager AI** (Port 8013)
   - **Purpose**: AI-powered template analysis
   - **Features**: Claude AI integration for templates
   - **Health Check**: `/health`

4. **Claude AI** (External API)
   - **Purpose**: Intelligent recommendation unification
   - **Model**: claude-3-sonnet-20240229
   - **Features**: Natural language processing, optimization

### Internal Components
1. **Schema Validator**: JSON schema validation using Ajv
2. **Logger**: Winston-based structured logging
3. **Error Handler**: Comprehensive error handling
4. **Request Validator**: Joi-based input validation
5. **Health Check Middleware**: External service monitoring

## 📊 Performance Characteristics

### Response Times
- **Health Check**: ~12ms
- **Tech Stack Only**: ~50ms
- **Template Only**: ~15ms
- **Unified Recommendation**: ~11ms (with fallback)
- **Claude AI Unification**: ~2-5 seconds

### Memory Usage
- **Base Memory**: ~16MB
- **Peak Memory**: ~18MB
- **External Memory**: ~3MB

### Throughput
- **Rate Limit**: 100 requests per 15 minutes per IP
- **Concurrent Requests**: Handled by Express.js
- **Timeout**: 30 seconds per external service call

## 🛡️ Security & Reliability

### Security Features
- **Helmet**: Security headers
- **CORS**: Cross-origin resource sharing
- **Rate Limiting**: Abuse prevention
- **Input Validation**: XSS and injection prevention
- **Error Sanitization**: No sensitive data in error messages

### Reliability Features
- **Graceful Fallbacks**: Multiple fallback strategies
- **Circuit Breaker Pattern**: Service failure handling
- **Timeout Management**: Prevents hanging requests
- **Health Monitoring**: Proactive service monitoring
- **Structured Logging**: Comprehensive debugging

## 🚀 Deployment & Scaling

### Docker Configuration
- **Base Image**: Node.js 18 Alpine
- **Port Mapping**: 8014:8010
- **Health Check**: Built-in health check endpoint
- **Logging**: JSON file logging with rotation

### Environment Variables
- **Service URLs**: External service endpoints
- **Claude API Key**: AI integration
- **Database URLs**: Connection strings
- **Security Keys**: JWT secrets, API keys
- **Performance Tuning**: Timeouts, limits

## 📈 Monitoring & Observability

### Metrics Tracked
- **Response Times**: Per endpoint and service
- **Error Rates**: By error type and service
- **Service Availability**: External service health
- **Memory Usage**: Heap and external memory
- **Request Volume**: Rate limiting metrics

### Logging Strategy
- **Structured Logs**: JSON format for easy parsing
- **Log Levels**: Appropriate level for each event
- **Request Tracing**: Unique identifiers for requests
- **Error Context**: Detailed error information
- **Performance Metrics**: Response time tracking

---

## 🎯 Summary

The Unison service implements a **sophisticated orchestration workflow** that:

1. **Validates** incoming requests with strict schema validation
2. **Orchestrates** parallel calls to multiple recommendation services
3. **Unifies** recommendations using Claude AI for intelligent optimization
4. **Validates** outputs with comprehensive schema validation
5. **Provides** multiple fallback strategies for reliability
6. **Monitors** health and performance continuously
7. **Logs** everything for debugging and analysis

This creates a **robust, intelligent, and reliable** system that can provide high-quality tech stack recommendations even when individual services fail, while maintaining excellent performance and security standards.

---
*Generated on: 2025-09-22T05:01:45.120Z*
*Service Version: 1.0.0*
*Status: OPERATIONAL*
