codenuk_backend_mine/services/unified-tech-stack-service/README.md

Unified Tech Stack Service

A comprehensive service that combines recommendations from both the Template Manager and Tech Stack Selector services to provide unified, intelligent tech stack recommendations.

🎯 Overview

The Unified Tech Stack Service acts as a unison between two powerful recommendation engines:

1. Template Manager Service - Provides permutation and combination-based recommendations
2. Tech Stack Selector Service - Provides domain and budget-based recommendations

🚀 Features

Core Capabilities

• Unified Recommendations: Combines both template-based and domain-based recommendations
• Intelligent Analysis: Analyzes and compares recommendations from both services
• Hybrid Approach: Provides the best of both worlds in a single response
• Service Health Monitoring: Monitors both underlying services
• Flexible Configuration: Configurable endpoints and preferences

API Endpoints

1. Comprehensive Recommendations (NEW - Includes Claude AI)

POST /api/unified/comprehensive-recommendations

Request Body:

{
  "template": {
    "id": "template-uuid",
    "title": "E-commerce Platform",
    "description": "A comprehensive e-commerce solution",
    "category": "E-commerce",
    "type": "web-app"
  },
  "features": [
    {
      "id": "feature-1",
      "name": "User Authentication",
      "description": "Secure user login and registration",
      "feature_type": "essential",
      "complexity": "medium",
      "business_rules": ["Users must verify email"],
      "technical_requirements": ["JWT tokens", "Password hashing"]
    }
  ],
  "businessContext": {
    "questions": [
      {
        "question": "What is your target audience?",
        "answer": "Small to medium businesses"
      }
    ]
  },
  "projectName": "E-commerce Platform",
  "projectType": "E-commerce",
  "templateId": "template-uuid",
  "budget": 15000,
  "domain": "ecommerce",
  "includeClaude": true,
  "includeTemplateBased": true,
  "includeDomainBased": true
}

Response:

{
  "success": true,
  "data": {
    "claude": {
      "success": true,
      "data": {
        "claude_recommendations": {
          "technology_recommendations": {
            "frontend": {
              "framework": "React",
              "libraries": ["TypeScript", "Tailwind CSS"],
              "reasoning": "Modern, scalable frontend solution"
            },
            "backend": {
              "language": "Node.js",
              "framework": "Express.js",
              "libraries": ["TypeScript", "Prisma"],
              "reasoning": "JavaScript ecosystem consistency"
            }
          },
          "implementation_strategy": {...},
          "business_alignment": {...},
          "risk_assessment": {...}
        },
        "functional_requirements": {...}
      }
    },
    "templateBased": {...},
    "domainBased": {...},
    "unified": {
      "techStacks": [...],
      "technologies": [...],
      "recommendations": [...],
      "confidence": 0.9,
      "approach": "comprehensive",
      "claudeRecommendations": {...},
      "templateRecommendations": {...},
      "domainRecommendations": {...}
    },
    "analysis": {
      "claude": {
        "status": "success",
        "hasRecommendations": true,
        "hasFunctionalRequirements": true
      },
      "templateManager": {...},
      "techStackSelector": {...},
      "comparison": {
        "comprehensiveScore": 0.9,
        "recommendationQuality": "excellent"
      }
    }
  }
}

2. Unified Recommendations (Legacy)

POST /api/unified/recommendations

Request Body:

{
  "templateId": "template-uuid",
  "budget": 10000,
  "domain": "finance",
  "features": ["feature1", "feature2"],
  "preferences": {
    "includePermutations": true,
    "includeCombinations": true,
    "includeDomainRecommendations": true
  }
}

Response:

{
  "success": true,
  "data": {
    "templateBased": {
      "permutations": {...},
      "combinations": {...},
      "template": {...}
    },
    "domainBased": {
      "recommendations": [...],
      "confidence": 0.85
    },
    "unified": {
      "techStacks": [...],
      "technologies": [...],
      "recommendations": [...],
      "confidence": 0.9,
      "approach": "hybrid"
    },
    "analysis": {
      "templateManager": {...},
      "techStackSelector": {...},
      "comparison": {...}
    }
  }
}

2. Template-Based Recommendations

POST /api/unified/template-recommendations

3. Domain-Based Recommendations

POST /api/unified/domain-recommendations

4. Analysis Endpoint

POST /api/unified/analyze

5. Service Status

GET /api/unified/status

🔧 Architecture

Service Components

┌─────────────────────────────────────────────────────────────┐
│                    Unified Tech Stack Service               │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │ Template Manager│  │ Tech Stack      │  │ Unified     │ │
│  │ Client          │  │ Selector Client │  │ Service     │ │
│  └─────────────────┘  └─────────────────┘  └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │ Template        │  │ Domain-Based    │  │ Analysis    │ │
│  │ Recommendations │  │ Recommendations │  │ Engine      │ │
│  └─────────────────┘  └─────────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────┘

Data Flow

1. Request Processing: Receives unified request with template ID, budget, domain, and features
2. Parallel Service Calls: Calls both Template Manager and Tech Stack Selector services
3. Data Aggregation: Combines responses from both services
4. Intelligent Merging: Merges technologies and recommendations intelligently
5. Analysis: Performs comparative analysis between both approaches
6. Unified Response: Returns comprehensive unified recommendations

🛠️ Installation & Setup

Prerequisites

• Node.js 18+
• Docker (optional)
• Access to Template Manager Service (port 8009)
• Access to Tech Stack Selector Service (port 8002)

Local Development

1. Clone and Install

cd services/unified-tech-stack-service
npm install

2. Environment Setup

# Run the setup script
./setup-env.sh

# Or manually copy and configure
cp env.example .env
# Edit .env with your configuration

3. Configure Claude AI API Key

# Get your API key from: https://console.anthropic.com/
# Add to .env file:
CLAUDE_API_KEY=your_actual_api_key_here

4. Start Service

npm start
# or for development
npm run dev

5. Test the Service

node test-comprehensive-integration.js

Docker Deployment

1. Build Image

docker build -t unified-tech-stack-service .

2. Run Container

docker run -p 8010:8010 \
  -e TEMPLATE_MANAGER_URL=http://host.docker.internal:8009 \
  -e TECH_STACK_SELECTOR_URL=http://host.docker.internal:8002 \
  unified-tech-stack-service

📊 Usage Examples

Example 1: Complete Unified Recommendation

curl -X POST "http://localhost:8010/api/unified/recommendations" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "0163731b-18e5-4d4e-86a1-aa2c05ae3140",
    "budget": 15000,
    "domain": "finance",
    "features": ["trading", "analytics", "security"],
    "preferences": {
      "includePermutations": true,
      "includeCombinations": true,
      "includeDomainRecommendations": true
    }
  }'

Example 2: Template-Only Recommendations

curl -X POST "http://localhost:8010/api/unified/template-recommendations" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "0163731b-18e5-4d4e-86a1-aa2c05ae3140",
    "recommendationType": "both"
  }'

Example 3: Domain-Only Recommendations

curl -X POST "http://localhost:8010/api/unified/domain-recommendations" \
  -H "Content-Type: application/json" \
  -d '{
    "budget": 10000,
    "domain": "ecommerce",
    "features": ["payment", "inventory", "shipping"]
  }'

Example 4: Service Analysis

curl -X POST "http://localhost:8010/api/unified/analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "0163731b-18e5-4d4e-86a1-aa2c05ae3140",
    "budget": 12000,
    "domain": "healthcare",
    "features": ["patient-management", "billing", "analytics"]
  }'

🔍 How It Works

1. Claude AI Recommendations (NEW - Intelligence Matters)

• AI-Powered: Uses Claude AI to analyze template, features, and business context
• Context-Aware: Considers business questions and answers for personalized recommendations
• Comprehensive: Provides detailed reasoning for each technology choice
• Source: Claude AI (Anthropic)
• Use Case: When you need intelligent, context-aware recommendations

2. Template-Based Recommendations (Order Matters)

• Permutations: [Feature A, Feature B, Feature C] ≠ [Feature C, Feature A, Feature B]
• Combinations: {Feature A, Feature B, Feature C} = {Feature C, Feature A, Feature B}
• Source: Template Manager Service
• Use Case: When user selects features in specific order or as unordered sets

3. Domain-Based Recommendations (Context Matters)

• Budget-Aware: Recommendations based on budget constraints
• Domain-Specific: Tailored for specific business domains (finance, healthcare, etc.)
• Source: Tech Stack Selector Service
• Use Case: When user has budget and domain requirements

4. Comprehensive Approach (Best of All Three)

• AI + Template + Domain: Combines all three approaches intelligently
• Technology Merging: Deduplicates and merges technologies from all sources
• Confidence Scoring: Calculates comprehensive confidence scores
• Quality Assessment: Analyzes recommendation quality from all services
• Fallback Mechanisms: Graceful degradation when services are unavailable

📈 Benefits

For Developers

• Single API: One endpoint for all tech stack recommendations
• Comprehensive Data: Gets Claude AI, template-based, and domain-based insights
• Intelligent Analysis: Built-in comparison and analysis across all sources
• Flexible Usage: Can use individual services or comprehensive approach
• AI-Powered: Leverages Claude AI for intelligent, context-aware recommendations

For Applications

• Better Recommendations: More comprehensive and accurate recommendations from multiple sources
• Reduced Complexity: Single service to integrate instead of multiple
• Improved Reliability: Fallback mechanisms if services fail
• Enhanced Analytics: Built-in analysis and comparison capabilities
• Context-Aware: Considers business context and requirements for personalized recommendations

🔧 Configuration

Environment Variables

Variable	Description	Default
PORT	Service port	8010
TEMPLATE_MANAGER_URL	Template Manager service URL	http://localhost:8009
TECH_STACK_SELECTOR_URL	Tech Stack Selector service URL	http://localhost:8002
CLAUDE_API_KEY	Claude AI API key	Required for AI recommendations
ANTHROPIC_API_KEY	Anthropic API key (alternative)	Required for AI recommendations
REQUEST_TIMEOUT	Request timeout in ms	30000
CACHE_TTL	Cache TTL in ms	300000

Feature Flags

• ENABLE_TEMPLATE_RECOMMENDATIONS: Enable template-based recommendations
• ENABLE_DOMAIN_RECOMMENDATIONS: Enable domain-based recommendations
• ENABLE_CLAUDE_RECOMMENDATIONS: Enable Claude AI recommendations
• ENABLE_ANALYSIS: Enable analysis features
• ENABLE_CACHING: Enable response caching

🚨 Error Handling

The service includes comprehensive error handling:

• Service Unavailability: Graceful degradation when one service is down
• Timeout Handling: Configurable timeouts for external service calls
• Data Validation: Input validation and sanitization
• Fallback Mechanisms: Fallback to available services when possible

📊 Monitoring

Health Checks

• Service Health: GET /health
• Service Status: GET /api/unified/status
• Individual Service Health: Monitors both underlying services

Metrics

• Request count and response times
• Service availability status
• Recommendation quality scores
• Error rates and types

🔮 Future Enhancements

• Machine Learning Integration: ML-based recommendation scoring
• Caching Layer: Redis-based caching for improved performance
• Rate Limiting: Built-in rate limiting and throttling
• WebSocket Support: Real-time recommendation updates
• GraphQL API: GraphQL endpoint for flexible data querying

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

---

The Unified Tech Stack Service provides the perfect unison between Claude AI, template-based, and domain-based tech stack recommendations, giving you the best of all worlds in a single, intelligent service. 🚀

🧪 Testing

Test Comprehensive Integration

Run the test script to verify the new comprehensive endpoint:

# Make sure the unified service is running
npm start

# In another terminal, run the test
node test-comprehensive-integration.js

This will test the new comprehensive endpoint that combines Claude AI, template-based, and domain-based recommendations.

🔧 Troubleshooting

Claude AI Not Working

Problem: Claude AI recommendations are not working Solution:

1. Check if API key is configured: grep CLAUDE_API_KEY .env
2. Get API key from: https://console.anthropic.com/
3. Add to .env: CLAUDE_API_KEY=your_key_here
4. Restart service: npm start

Service Not Starting

Problem: Service fails to start Solution:

1. Check if port 8013 is available: lsof -i :8013
2. Install dependencies: npm install
3. Check environment: ./setup-env.sh

Template/Domain Services Not Available

Problem: Template-based or domain-based recommendations fail Solution:

1. Ensure Template Manager is running on port 8009
2. Ensure Tech Stack Selector is running on port 8002
3. Check service URLs in .env file

Frontend Integration Issues

Problem: Frontend can't connect to unified service Solution:

1. Ensure unified service is running on port 8013
2. Check CORS configuration
3. Verify API endpoint: /api/unified/comprehensive-recommendations