prakash/codenuk_backend_mine

Fork 0

Pradeep de71743b61 implemented direct file passes

2025-10-17 10:33:14 +05:30

30 KiB

Raw Blame History

AI Analysis Service - Communication Architecture

System Architecture Overview
Service Components
Communication Flow
AI Analysis Service Details
API Gateway Integration
Git Integration Service
Frontend Integration
Request/Response Examples
Error Handling
Deployment Configuration

System Architecture Overview

The AI Analysis Service is part of a microservices architecture with the following components:

┌─────────────────────────────────────────────────────────────────┐
│                         FRONTEND                                 │
│                  (Next.js Application)                           │
│                  http://localhost:3000                           │
└────────────────────┬────────────────────────────────────────────┘
                     │
                     │ HTTP/REST
                     │
┌────────────────────▼────────────────────────────────────────────┐
│                      API GATEWAY                                 │
│              (Express.js Proxy Layer)                            │
│                  Port: 8000                                      │
│  Routes: /api/ai-analysis/*, /api/github/*, /api/ai/repository/*│
└──────────┬─────────────────────────┬──────────────────────┬─────┘
           │                         │                      │
           │ HTTP                    │ HTTP                 │ HTTP
           │                         │                      │
           ▼                         ▼                      ▼
┌──────────────────┐   ┌──────────────────────┐   ┌───────────────┐
│  AI ANALYSIS     │   │  GIT INTEGRATION     │   │ OTHER         │
│  SERVICE         │◄──┤  SERVICE             │   │ SERVICES      │
│  Port: 8022      │   │  Port: 8012          │   │               │
│  (Python/FastAPI)│   │  (Node.js/Express)   │   │               │
└──────────────────┘   └──────────────────────┘   └───────────────┘
           │                         │
           │                         │
           ▼                         ▼
┌──────────────────┐   ┌──────────────────────┐
│  PostgreSQL DB   │   │  Redis Cache         │
│  (Repository     │   │  (Analysis Results)  │
│   Metadata)      │   │                      │
└──────────────────┘   └──────────────────────┘

Service Components

1. AI Analysis Service (Port 8022)

Technology: Python 3.11, FastAPI, Anthropic Claude API
Purpose: Analyzes repository code using Claude AI
Key Features:
- Repository analysis with memory system
- File-by-file code quality assessment
- PDF/JSON report generation
- Rate limiting for Claude API (90 requests/minute)
- Redis caching for repeated analyses
- Content optimization for large files

2. API Gateway (Port 8000)

Technology: Node.js, Express.js
Purpose: Central entry point for all frontend requests
Key Features:
- Request routing and proxying
- CORS handling
- Authentication middleware
- Service health monitoring
- WebSocket support
- Request logging

3. Git Integration Service (Port 8012)

Technology: Node.js, Express.js
Purpose: Manages repository connections and file access
Key Features:
- GitHub OAuth integration
- Repository cloning and syncing
- File tree navigation
- Diff generation
- Commit history tracking
- Multi-VCS support (GitHub, GitLab, Bitbucket, Gitea)

4. Frontend (Port 3000)

Technology: Next.js 14, React, TypeScript
Purpose: User interface
Key Features:
- Repository management
- AI analysis triggering
- Real-time progress tracking
- Report viewing

Communication Flow

Complete Analysis Flow

┌──────────┐
│ Frontend │
└────┬─────┘
     │
     │ 1. POST /api/ai-analysis/analyze-repository
     │    Body: { repository_id, user_id, output_format, max_files }
     │
     ▼
┌────────────────┐
│  API Gateway   │
└────┬───────────┘
     │
     │ 2. Forward to AI Analysis Service
     │    POST /analyze-repository
     │    Timeout: 240 seconds
     │
     ▼
┌──────────────────────┐
│ AI Analysis Service  │
└────┬─────────────────┘
     │
     │ 3. Get Repository Info from Git Integration
     │    GET http://git-integration:8012/api/github/repository/{id}/ui-view
     │    Headers: { x-user-id: userId }
     │
     ▼
┌──────────────────────┐
│ Git Integration      │
└────┬─────────────────┘
     │
     │ 4. Return Repository Metadata
     │    { repository_info, file_tree, local_path }
     │
     ▼
┌──────────────────────┐
│ AI Analysis Service  │
└────┬─────────────────┘
     │
     │ 5. For each file:
     │    - Get file content via Git Integration API
     │    - Check Redis cache
     │    - Apply rate limiting
     │    - Optimize content (truncate if > 8000 tokens)
     │    - Send to Claude API
     │    - Cache result
     │
     │ 6. Generate Repository-level Analysis
     │    - Architecture assessment
     │    - Security review
     │    - Code quality metrics
     │
     │ 7. Create Report (PDF/JSON)
     │    Path: /app/reports/{analysis_id}_analysis.pdf
     │
     │ 8. Return Analysis Results
     │    { success, analysis_id, report_path, stats }
     │
     ▼
┌────────────────┐
│  API Gateway   │
└────┬───────────┘
     │
     │ 9. Forward response to Frontend
     │
     ▼
┌──────────┐
│ Frontend │
└──────────┘

AI Analysis Service Details

Base URL

Direct: http://localhost:8022
Via Gateway: http://localhost:8000/api/ai-analysis

Key Endpoints

1. Analyze Repository

Endpoint: POST /analyze-repository

Request:

{
  "repository_id": "uuid-string",
  "user_id": "user-uuid",
  "output_format": "pdf",
  "max_files": 100
}

Response:

{
  "success": true,
  "message": "Repository analysis completed successfully",
  "analysis_id": "repo_analysis_uuid_20241216_143022",
  "report_path": "/app/reports/repo_analysis_uuid_20241216_143022_analysis.pdf",
  "stats": {
    "repository_id": "uuid-string",
    "total_files": 85,
    "total_lines": 15420,
    "languages": ["typescript", "javascript", "python"],
    "code_quality_score": 7.8,
    "high_quality_files": 45,
    "medium_quality_files": 30,
    "low_quality_files": 10,
    "total_issues": 23
  }
}

2. Get Repository Info

Endpoint: GET /repository/{repository_id}/info?user_id={user_id}

Response:

{
  "success": true,
  "repository_info": {
    "id": "uuid-string",
    "name": "my-repo",
    "owner": "owner-name",
    "local_path": "/app/git-repos/owner__my-repo__main",
    "repository_url": "https://github.com/owner/my-repo"
  }
}

3. Download Report

Endpoint: GET /reports/{filename}

Returns the generated PDF or JSON report file.

4. Memory System Stats

Endpoint: GET /memory/stats

Response:

{
  "success": true,
  "memory_stats": {
    "total_memories": 150,
    "recent_analyses": 5,
    "cache_hit_rate": 0.65
  }
}

5. Health Check

Endpoint: GET /health

Response:

{
  "status": "healthy",
  "service": "ai-analysis-service",
  "timestamp": "2024-12-16T14:30:22.000Z",
  "version": "1.0.0"
}

Internal Components

GitIntegrationClient

Handles communication with git-integration service:

class GitIntegrationClient:
    def __init__(self):
        self.base_url = os.getenv('GIT_INTEGRATION_SERVICE_URL', 
                                   'http://git-integration:8012')
        self.timeout = 30.0
    
    async def get_repository_info(self, repository_id: str, user_id: str):
        """Get repository information from git-integration service."""
        response = await client.get(
            f"{self.base_url}/api/github/repository/{repository_id}/ui-view",
            headers={'x-user-id': user_id}
        )
        return response.json()

ClaudeRateLimiter

Manages Claude API rate limits:

class ClaudeRateLimiter:
    def __init__(self, requests_per_minute: int = 90):
        self.requests_per_minute = requests_per_minute
        self.requests = []
        self.lock = asyncio.Lock()
    
    async def wait_if_needed(self):
        """Wait if rate limit would be exceeded."""
        # Implements sliding window rate limiting

AnalysisCache

Redis-based caching for analysis results:

class AnalysisCache:
    def __init__(self):
        self.redis = redis.Redis(
            host=os.getenv('REDIS_HOST', 'redis'),
            port=6379,
            decode_responses=True
        )
        self.cache_ttl = 86400  # 24 hours
    
    async def get_cached_analysis(self, file_hash: str):
        """Get cached analysis result."""
        cache_key = f"analysis:{file_hash}"
        return self.redis.get(cache_key)

ContentOptimizer

Optimizes large files for Claude API:

class ContentOptimizer:
    @staticmethod
    def optimize_content_for_claude(content: str, max_tokens: int = 8000):
        """Optimize file content for Claude API limits."""
        if len(content) > max_tokens * 4:
            # Extract important lines (imports, functions, classes)
            # Truncate intelligently
            return optimized_content
        return content

API Gateway Integration

AI Analysis Routes

The API Gateway proxies requests to the AI Analysis Service:

// Route: /api/ai-analysis/*
app.use('/api/ai-analysis',
  createServiceLimiter(200),
  (req, res, next) => {
    const aiAnalysisServiceUrl = process.env.AI_ANALYSIS_URL || 
                                   'http://localhost:8022';
    const rewrittenPath = req.originalUrl.replace(/^\/api\/ai-analysis/, '');
    const targetUrl = `${aiAnalysisServiceUrl}${rewrittenPath}`;
    
    // Proxy configuration
    const options = {
      method: req.method,
      url: targetUrl,
      headers: {
        'Content-Type': 'application/json',
        'User-Agent': 'API-Gateway/1.0',
        'X-User-ID': req.user?.id || req.user?.userId,
      },
      timeout: 240000, // 4 minutes
      maxContentLength: 100 * 1024 * 1024 // 100MB
    };
    
    // Forward request
    axios(options)
      .then(response => res.status(response.status).json(response.data))
      .catch(error => handleError(error));
  }
);

Service Configuration

const serviceTargets = {
  AI_ANALYSIS_URL: process.env.AI_ANALYSIS_URL || 'http://localhost:8022',
  GIT_INTEGRATION_URL: process.env.GIT_INTEGRATION_URL || 'http://localhost:8012',
  // ... other services
};

CORS Configuration

app.use(cors({
  origin: '*',
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'PATCH'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-User-ID']
}));

Git Integration Service

Base URL

Direct: http://localhost:8012
Via Gateway: http://localhost:8000/api/github

Key Endpoints Used by AI Analysis

1. Get Repository UI View

Endpoint: GET /api/github/repository/{id}/ui-view?view_type=tree

Headers:

x-user-id: {userId}

Response:

{
  "success": true,
  "data": {
    "repository_info": {
      "id": "uuid",
      "name": "repo-name",
      "owner": "owner-name",
      "provider": "github",
      "local_path": "/app/git-repos/owner__repo__main",
      "repository_url": "https://github.com/owner/repo"
    },
    "ui_data": {
      "left_panel": {
        "file_tree": [
          {
            "type": "directory",
            "path": "src",
            "children": [
              {
                "type": "file",
                "path": "src/index.ts",
                "size": 1024
              }
            ]
          }
        ]
      }
    }
  }
}

2. Get File Content

Endpoint: GET /api/github/repository/{id}/file-content?file_path={path}

Headers:

x-user-id: {userId}

Response:

{
  "success": true,
  "data": {
    "file_info": {
      "filename": "index.ts",
      "file_extension": "ts",
      "relative_path": "src/index.ts",
      "file_size_bytes": 1024,
      "is_binary": false,
      "language_detected": "typescript"
    },
    "content": "import express from 'express';\n...",
    "preview": "import express from 'express';\n..."
  }
}

3. Attach Repository

Endpoint: POST /api/github/attach-repository

Request:

{
  "repository_url": "https://github.com/owner/repo",
  "branch_name": "main",
  "user_id": "user-uuid"
}

Response:

{
  "success": true,
  "message": "Repository attached and synced successfully",
  "data": {
    "repository_id": "uuid",
    "repository_name": "repo",
    "owner_name": "owner",
    "branch_name": "main",
    "is_public": true,
    "storage_info": {
      "local_path": "/app/git-repos/owner__repo__main",
      "total_files": 85,
      "total_size_bytes": 1024000
    }
  }
}

Communication Pattern

The AI Analysis Service communicates with Git Integration through HTTP REST APIs:

async def get_repository_files_from_api(repository_id: str, user_id: str, max_files: int = 100):
    """Get repository files from Git Integration Service API."""
    
    # 1. Get file tree
    response = await client.get(
        f"{git_client.base_url}/api/github/repository/{repository_id}/ui-view?view_type=tree",
        headers={'x-user-id': user_id}
    )
    
    data = response.json()
    file_tree = data['data']['ui_data']['left_panel']['file_tree']
    
    # 2. Extract file paths from tree
    files_to_analyze = []
    extract_files_from_tree(file_tree, files_to_analyze)
    
    # 3. Fetch content for each file
    files_with_content = []
    for file_path, _ in files_to_analyze:
        content_response = await client.get(
            f"{git_client.base_url}/api/github/repository/{repository_id}/file-content?file_path={file_path}",
            headers={'x-user-id': user_id}
        )
        
        content_data = content_response.json()
        if content_data['success']:
            content = content_data['content']
            files_with_content.append((file_path, content))
    
    return files_with_content

Frontend Integration

Configuration

File: src/config/api-gateway.ts

export const API_GATEWAY_CONFIG = {
  BASE_URL: process.env.NEXT_PUBLIC_API_GATEWAY_URL || 'http://localhost:8000',
  
  ENDPOINTS: {
    AI_ANALYSIS: {
      BASE: '/api/ai-analysis',
      ANALYZE: '/api/ai-analysis/analyze-repository',
      REPORT: (filename: string) => `/api/ai-analysis/reports/${filename}`,
    },
    
    GIT_INTEGRATION: {
      BASE: '/api/github',
      REPOSITORIES: '/api/github/repositories',
      REPOSITORY_INFO: (repositoryId: string) => 
        `/api/github/repository/${repositoryId}/info`
    }
  }
}

React Hook for AI Analysis

File: src/hooks/useAIAnalysis.ts

export const useAIAnalysis = () => {
  const [isAnalyzing, setIsAnalyzing] = useState(false)
  const [progress, setProgress] = useState<AnalysisProgress | null>(null)
  const [result, setResult] = useState<AnalysisResult | null>(null)
  const [error, setError] = useState<string | null>(null)

  const startAnalysis = async (
    repositoryId: string, 
    userId: string,
    options = {}
  ) => {
    try {
      setIsAnalyzing(true)
      
      // Start analysis via API Gateway
      const response = await fetch(
        buildApiUrl('/api/ai-analysis/analyze-repository'),
        {
          method: 'POST',
          headers: getApiHeaders(),
          body: JSON.stringify({
            repository_id: repositoryId,
            user_id: userId,
            output_format: options.output_format || 'pdf',
            max_files: options.max_files || 100
          })
        }
      )

      if (!response.ok) {
        throw new Error('Analysis failed to start')
      }

      const data = await response.json()
      
      if (data.success) {
        setResult(data)
      }
    } catch (err) {
      setError(err.message)
    } finally {
      setIsAnalyzing(false)
    }
  }

  return { isAnalyzing, progress, result, error, startAnalysis }
}

Usage Example

import { useAIAnalysis } from '@/hooks/useAIAnalysis'

function RepositoryAnalysis({ repositoryId, userId }) {
  const { 
    isAnalyzing, 
    result, 
    error, 
    startAnalysis 
  } = useAIAnalysis()

  const handleAnalyze = async () => {
    await startAnalysis(repositoryId, userId, {
      output_format: 'pdf',
      max_files: 100
    })
  }

  return (
    <div>
      <button 
        onClick={handleAnalyze} 
        disabled={isAnalyzing}
      >
        {isAnalyzing ? 'Analyzing...' : 'Analyze Repository'}
      </button>

      {result && (
        <div>
          <h3>Analysis Complete</h3>
          <p>Quality Score: {result.stats.code_quality_score}/10</p>
          <p>Total Files: {result.stats.total_files}</p>
          <p>Total Issues: {result.stats.total_issues}</p>
          <a href={`/api/ai-analysis/reports/${result.analysis_id}_analysis.pdf`}>
            Download Report
          </a>
        </div>
      )}

      {error && <div className="error">{error}</div>}
    </div>
  )
}

Request/Response Examples

Example 1: Complete Analysis Flow

Step 1: Frontend initiates analysis

POST http://localhost:8000/api/ai-analysis/analyze-repository
Content-Type: application/json

{
  "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "660e8400-e29b-41d4-a716-446655440001",
  "output_format": "pdf",
  "max_files": 100
}

Step 2: API Gateway forwards to AI Analysis Service

POST http://localhost:8022/analyze-repository
Content-Type: application/json
X-User-ID: 660e8400-e29b-41d4-a716-446655440001

{
  "repository_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "660e8400-e29b-41d4-a716-446655440001",
  "output_format": "pdf",
  "max_files": 100
}

Step 3: AI Analysis Service gets repository info

GET http://localhost:8012/api/github/repository/550e8400-e29b-41d4-a716-446655440000/ui-view?view_type=tree
x-user-id: 660e8400-e29b-41d4-a716-446655440001

Step 4: Git Integration returns repository data

{
  "success": true,
  "data": {
    "repository_info": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "my-project",
      "owner": "johndoe",
      "local_path": "/app/git-repos/johndoe__my-project__main"
    },
    "ui_data": {
      "left_panel": {
        "file_tree": [
          {
            "type": "file",
            "path": "src/index.ts",
            "name": "index.ts"
          },
          {
            "type": "file",
            "path": "src/utils.ts",
            "name": "utils.ts"
          }
        ]
      }
    }
  }
}

Step 5: AI Analysis Service gets file content

GET http://localhost:8012/api/github/repository/550e8400-e29b-41d4-a716-446655440000/file-content?file_path=src/index.ts
x-user-id: 660e8400-e29b-41d4-a716-446655440001

Step 6: Final response to frontend

{
  "success": true,
  "message": "Repository analysis completed successfully",
  "analysis_id": "repo_analysis_550e8400_20241216_143022",
  "report_path": "/app/reports/repo_analysis_550e8400_20241216_143022_analysis.pdf",
  "stats": {
    "repository_id": "550e8400-e29b-41d4-a716-446655440000",
    "total_files": 85,
    "total_lines": 15420,
    "languages": ["typescript", "javascript"],
    "code_quality_score": 7.8,
    "high_quality_files": 45,
    "medium_quality_files": 30,
    "low_quality_files": 10,
    "total_issues": 23
  }
}

Error Handling

Error Types and Responses

1. Service Unavailable (502)

{
  "error": "AI Analysis service unavailable",
  "message": "ECONNREFUSED",
  "service": "ai-analysis"
}

Causes:

AI Analysis service is down
Network issues
Service not responding

2. Gateway Timeout (504)

{
  "error": "Gateway timeout",
  "service": "ai-analysis"
}

Causes:

Analysis taking longer than 4 minutes
Service overloaded
Large repository

3. Authentication Required (401)

{
  "success": false,
  "message": "GitHub authentication required for private repository",
  "requires_auth": true,
  "auth_url": "https://backend.codenuk.com/api/github/auth/github?..."
}

Causes:

Private repository without OAuth token
Expired OAuth token

4. Repository Not Found (404)

{
  "success": false,
  "message": "Repository not found"
}

Causes:

Invalid repository ID
Repository deleted
User doesn't have access

5. Rate Limit Exceeded (429)

{
  "success": false,
  "message": "Claude API rate limit exceeded",
  "retry_after": 60
}

Causes:

Too many concurrent analyses
Claude API limits hit

Error Handling in Frontend

try {
  const result = await startAnalysis(repositoryId, userId)
  // Handle success
} catch (error) {
  if (error.status === 401) {
    // Redirect to OAuth
    window.location.href = error.auth_url
  } else if (error.status === 504) {
    // Show timeout message
    setError('Analysis taking longer than expected. Please try again.')
  } else if (error.status === 502) {
    // Show service unavailable message
    setError('AI Analysis service is currently unavailable.')
  } else {
    // Generic error
    setError(error.message || 'An error occurred')
  }
}

Deployment Configuration

Environment Variables

AI Analysis Service (.env)

# Service Configuration
PORT=8022
HOST=0.0.0.0

# Anthropic API
ANTHROPIC_API_KEY=sk-ant-api03-...

# Git Integration Service
GIT_INTEGRATION_SERVICE_URL=http://git-integration:8012

# Redis Cache
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=

# Rate Limiting
CLAUDE_REQUESTS_PER_MINUTE=90

# Analysis Configuration
MAX_FILES_DEFAULT=100
CACHE_TTL_SECONDS=86400
CONTENT_MAX_TOKENS=8000

API Gateway (.env)

# Service URLs
PORT=8000
NODE_ENV=production

AI_ANALYSIS_URL=http://localhost:8022
GIT_INTEGRATION_URL=http://localhost:8012
USER_AUTH_URL=http://localhost:8011

# CORS
CORS_ORIGIN=*

# Timeouts
PROXY_TIMEOUT=240000

Git Integration Service (.env)

# Service Configuration
PORT=8012

# Database
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=git_integration
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres123

# GitHub OAuth
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_CALLBACK_URL=https://backend.codenuk.com/api/github/auth/github/callback

# Repository Storage
GIT_REPOS_PATH=/app/git-repos

# Public Base URL
PUBLIC_BASE_URL=https://backend.codenuk.com
API_GATEWAY_PUBLIC_URL=https://backend.codenuk.com

Frontend (.env.local)

NEXT_PUBLIC_API_GATEWAY_URL=http://localhost:8000
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000

Docker Compose Configuration

version: '3.8'

services:
  api-gateway:
    build: ./services/api-gateway
    ports:
      - "8000:8000"
    environment:
      - AI_ANALYSIS_URL=http://ai-analysis:8022
      - GIT_INTEGRATION_URL=http://git-integration:8012
    depends_on:
      - ai-analysis
      - git-integration
    networks:
      - backend-network

  ai-analysis:
    build: ./services/ai-analysis-service
    ports:
      - "8022:8022"
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - GIT_INTEGRATION_SERVICE_URL=http://git-integration:8012
      - REDIS_HOST=redis
    volumes:
      - ./reports:/app/reports
    depends_on:
      - redis
      - git-integration
    networks:
      - backend-network

  git-integration:
    build: ./services/git-integration
    ports:
      - "8012:8012"
    environment:
      - POSTGRES_HOST=postgres
      - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
      - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}
      - PUBLIC_BASE_URL=https://backend.codenuk.com
    volumes:
      - ./git-repos:/app/git-repos
    depends_on:
      - postgres
    networks:
      - backend-network

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=git_integration
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres123
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - backend-network

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    networks:
      - backend-network

  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_API_GATEWAY_URL=http://localhost:8000
    depends_on:
      - api-gateway
    networks:
      - backend-network

volumes:
  postgres-data:
  redis-data:

networks:
  backend-network:
    driver: bridge

Network Flow in Docker

Internet
    │
    ▼
[Nginx/Traefik Reverse Proxy]
    │
    ├─> frontend:3000
    │
    └─> api-gateway:8000
            │
            ├─> ai-analysis:8022 ──┐
            │                       ├─> redis:6379
            └─> git-integration:8012 ─┘
                        │
                        └─> postgres:5432

Performance Considerations

1. Rate Limiting

Claude API: 90 requests/minute (sliding window)
Wait times automatically calculated
Queued requests processed sequentially

2. Caching

Redis cache for analyzed files (24-hour TTL)
SHA-256 hash-based cache keys
Cache hit rate typically 40-60%

3. Content Optimization

Files > 32KB tokens are truncated
Preserves important code structures (imports, functions, classes)
Reduces API costs by 70-80%

4. Timeouts

API Gateway → AI Analysis: 240 seconds
AI Analysis → Git Integration: 30 seconds
AI Analysis → Claude API: 120 seconds per request

5. Concurrent Analysis

Maximum 5 concurrent repository analyses
File-level parallelization disabled (sequential processing)
Prevents rate limit violations

Troubleshooting

Issue 1: Service Cannot Connect to Git Integration

Symptoms:

Error: "Failed to get repository info"
502 Bad Gateway errors

Solution:

# Check if git-integration service is running
curl http://localhost:8012/health

# Check Docker network connectivity
docker network inspect backend-network

# Verify environment variable
docker exec ai-analysis env | grep GIT_INTEGRATION_SERVICE_URL

Issue 2: Claude API Rate Limit Exceeded

Symptoms:

Error: "Rate limit exceeded"
Analysis fails midway

Solution:

# Reduce max_files in request
{
  "max_files": 50  // Instead of 100
}

# Check rate limiter configuration
CLAUDE_REQUESTS_PER_MINUTE=50  // Reduce from 90

Issue 3: Redis Connection Failed

Symptoms:

Warning: "Redis connection failed"
No caching working

Solution:

# Check Redis service
docker exec redis redis-cli ping

# Verify connection settings
REDIS_HOST=redis
REDIS_PORT=6379

Issue 4: Authentication Errors

Symptoms:

401 Unauthorized
"GitHub authentication required"

Solution:

User needs to authenticate via OAuth
Frontend should redirect to auth_url provided in error response
Check GitHub OAuth credentials in git-integration service

Monitoring and Logging

Log Locations

# AI Analysis Service
docker logs ai-analysis -f

# API Gateway
docker logs api-gateway -f

# Git Integration
docker logs git-integration -f

Key Log Patterns

Successful Analysis

✅ [AI ANALYSIS] Repository analysis completed successfully
📊 Stats: 85 files, 15420 lines, score: 7.8/10

Rate Limiting

⚠️ [RATE LIMITER] Waiting 5.2 seconds before next request

Cache Hit

📦 [CACHE] Using cached analysis for file: src/index.ts

Git Integration Communication

🔍 [GIT CLIENT] Getting repository info for: uuid-123
✅ [GIT CLIENT] Repository info retrieved: johndoe/my-repo

Security Considerations

1. Authentication Flow

Frontend passes user_id in requests
API Gateway adds x-user-id header
Services validate user ownership

2. Private Repository Access

OAuth tokens stored in PostgreSQL
Tokens encrypted at rest
Token validation before file access

3. API Keys

Claude API key in environment variable only
Never exposed to frontend
Rotated regularly

4. CORS Configuration

Specific origins in production
Credentials allowed for authenticated requests

Additional Resources

Support and Contact

For issues or questions:

Check service logs first
Verify environment variables
Test service endpoints individually
Check Docker network connectivity

Last Updated: December 2024 Version: 1.0.0

30 KiB Raw Blame History

AI Analysis Service - Communication Architecture

Table of Contents

System Architecture Overview

Service Components

1. AI Analysis Service (Port 8022)

2. API Gateway (Port 8000)

3. Git Integration Service (Port 8012)

4. Frontend (Port 3000)

Communication Flow

Complete Analysis Flow

AI Analysis Service Details

Base URL

Key Endpoints

1. Analyze Repository

2. Get Repository Info

3. Download Report

4. Memory System Stats

5. Health Check

Internal Components

GitIntegrationClient

ClaudeRateLimiter

AnalysisCache

ContentOptimizer

API Gateway Integration

AI Analysis Routes

Service Configuration

CORS Configuration

Git Integration Service

Base URL

Key Endpoints Used by AI Analysis

1. Get Repository UI View

2. Get File Content

3. Attach Repository

Communication Pattern

Frontend Integration

Configuration

React Hook for AI Analysis

Usage Example

Request/Response Examples

Example 1: Complete Analysis Flow

Step 1: Frontend initiates analysis

Step 2: API Gateway forwards to AI Analysis Service

Step 3: AI Analysis Service gets repository info

Step 4: Git Integration returns repository data

Step 5: AI Analysis Service gets file content

Step 6: Final response to frontend

Error Handling

Error Types and Responses

1. Service Unavailable (502)

2. Gateway Timeout (504)

3. Authentication Required (401)

4. Repository Not Found (404)

5. Rate Limit Exceeded (429)

Error Handling in Frontend

Deployment Configuration

Environment Variables

AI Analysis Service (.env)

API Gateway (.env)

Git Integration Service (.env)

Frontend (.env.local)

Docker Compose Configuration

Network Flow in Docker

Performance Considerations

1. Rate Limiting

2. Caching

3. Content Optimization

4. Timeouts

5. Concurrent Analysis

Troubleshooting

Issue 1: Service Cannot Connect to Git Integration

Issue 2: Claude API Rate Limit Exceeded

Issue 3: Redis Connection Failed

Issue 4: Authentication Errors

Monitoring and Logging

Log Locations

Key Log Patterns

Successful Analysis

Rate Limiting

Cache Hit

30 KiB

Raw Blame History