377 lines
14 KiB
Markdown
377 lines
14 KiB
Markdown
# 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*
|