# AI Analysis Service - Flow Diagrams ## 1. Complete Request Flow ``` ┌───────────────────────────────────────────────────────────────────────┐ │ USER INTERFACE │ │ (Browser/Next.js Frontend) │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ 1. User clicks "Analyze Repository" │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ FRONTEND APPLICATION │ │ │ │ const { startAnalysis } = useAIAnalysis() │ │ await startAnalysis(repositoryId, userId, options) │ │ │ │ POST /api/ai-analysis/analyze-repository │ │ { │ │ "repository_id": "uuid", │ │ "user_id": "user-uuid", │ │ "output_format": "pdf", │ │ "max_files": 100 │ │ } │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ HTTP POST │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ API GATEWAY │ │ (Express.js - Port 8000) │ │ │ │ Route: /api/ai-analysis/* │ │ - Validate request │ │ - Add headers (X-User-ID) │ │ - Set timeout: 240 seconds │ │ - Proxy to AI Analysis Service │ │ │ │ Target: http://ai-analysis:8022/analyze-repository │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ HTTP POST (Internal Network) │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ AI ANALYSIS SERVICE │ │ (FastAPI - Port 8022) │ │ │ │ Endpoint: POST /analyze-repository │ │ 1. Validate request parameters │ │ 2. Generate analysis_id │ │ 3. Create temp directory │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ 4. Get repository info │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ GET Repository Information from Git Integration │ │ │ │ GET http://git-integration:8012/api/github/repository/{id}/ui-view │ │ Headers: { x-user-id: userId } │ │ Query: { view_type: "tree" } │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ GIT INTEGRATION SERVICE │ │ (Express.js - Port 8012) │ │ │ │ Route: /api/github/repository/:id/ui-view │ │ 1. Query PostgreSQL for repository metadata │ │ 2. Build file tree from repository_files table │ │ 3. Return repository info + file tree │ │ │ │ Response: │ │ { │ │ "success": true, │ │ "data": { │ │ "repository_info": { id, name, owner, local_path }, │ │ "ui_data": { │ │ "left_panel": { │ │ "file_tree": [ { type, path, name }, ... ] │ │ } │ │ } │ │ } │ │ } │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ Return repository data │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ AI ANALYSIS SERVICE │ │ │ │ 5. Extract file list from tree │ │ 6. For each file (up to max_files): │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ For each file │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ FILE ANALYSIS LOOP │ │ │ │ For file in files_to_analyze: │ │ a. Get file content from Git Integration │ │ b. Generate file hash (SHA-256) │ │ c. Check Redis cache │ │ d. If cache miss: │ │ - Wait for rate limiter │ │ - Optimize content (truncate if needed) │ │ - Send to Claude API │ │ - Parse response │ │ - Cache result in Redis │ │ e. Add to results │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ Get File Content (for each file) │ │ │ │ GET http://git-integration:8012/api/github/repository/{id}/ │ │ file-content?file_path={path} │ │ Headers: { x-user-id: userId } │ │ │ │ ┌─────────────────────────────────────────┐ │ │ │ GIT INTEGRATION SERVICE │ │ │ │ │ │ │ │ 1. Resolve file path (case-insensitive)│ │ │ │ 2. Read from local storage │ │ │ │ 3. Return file content + metadata │ │ │ └─────────────────────────────────────────┘ │ │ │ │ Response: │ │ { │ │ "success": true, │ │ "content": "file content...", │ │ "file_info": { │ │ "filename": "index.ts", │ │ "is_binary": false, │ │ "language_detected": "typescript" │ │ } │ │ } │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ ANALYSIS PROCESSING │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ 1. Check Redis Cache │ │ │ │ Key: analysis:{file_hash} │ │ │ │ TTL: 24 hours │ │ │ │ │ │ │ │ Cache Hit: Return cached result ────────────┼──────┐ │ │ │ Cache Miss: Continue ──────────────────────┐│ │ │ │ └───────────────────────────────────────────────┘│ │ │ │ │ │ │ │ ┌─────────────────────────────────────────────────┘ │ │ │ │ 2. Rate Limiter │ │ │ │ - Check requests in last 60 seconds │ │ │ │ - If >= 90 requests: wait │ │ │ │ - Add timestamp to requests array │ │ │ └─────────────────────────────────────────────────┐ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────────┘ │ │ │ │ 3. Content Optimizer │ │ │ │ - Check file size (token estimate) │ │ │ │ - If > 8000 tokens: │ │ │ │ * Extract imports, functions, classes │ │ │ │ * Truncate with context preservation │ │ │ └─────────────────────────────────────────────────┐ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────────┘ │ │ │ │ 4. Claude API Call │ │ │ │ POST https://api.anthropic.com/v1/messages │ │ │ │ { │ │ │ │ "model": "claude-3-opus-20240229", │ │ │ │ "max_tokens": 4096, │ │ │ │ "messages": [{ │ │ │ │ "role": "user", │ │ │ │ "content": "Analyze: {optimized_content}" │ │ │ │ }] │ │ │ │ } │ │ │ └─────────────────────────────────────────────────┐ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────────┘ │ │ │ │ 5. Parse Response & Cache │ │ │ │ - Extract code quality score │ │ │ │ - Extract issues found │ │ │ │ - Extract recommendations │ │ │ │ - Store in Redis cache │ │ │ └─────────────────────────────────────────────────┐ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────────┘ │ │ │ │ Result │ │ │ │ { │ │ │ │ "path": "src/index.ts", ◄────────────────────────────────────┤ │ │ "language": "typescript", │ │ │ │ "severity_score": 8.5, │ │ │ │ "issues_found": [...], │ │ │ │ "recommendations": [...] │ │ │ │ } │ │ │ └──────────────────────────────────────────────────────── │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ All files analyzed │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ REPOSITORY-LEVEL ANALYSIS │ │ │ │ 7. Aggregate file analyses │ │ 8. Analyze repository architecture │ │ 9. Security assessment │ │ 10. Generate executive summary │ │ │ │ Result: │ │ { │ │ "code_quality_score": 7.8, │ │ "total_files": 85, │ │ "total_lines": 15420, │ │ "languages": ["typescript", "javascript"], │ │ "architecture_assessment": "...", │ │ "security_assessment": "...", │ │ "file_analyses": [...] │ │ } │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ REPORT GENERATION │ │ │ │ 11. Generate PDF Report │ │ - Title page │ │ - Executive summary │ │ - Repository overview │ │ - Language breakdown │ │ - Quality metrics │ │ - File-by-file analysis │ │ - Security findings │ │ - Recommendations │ │ │ │ 12. Save to /app/reports/ │ │ Filename: repo_analysis_{id}_{timestamp}_analysis.pdf │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ AI ANALYSIS SERVICE │ │ │ │ 13. Build response │ │ 14. Cleanup temp directory │ │ 15. Return result │ │ │ │ Response: │ │ { │ │ "success": true, │ │ "message": "Analysis completed successfully", │ │ "analysis_id": "repo_analysis_uuid_20241216_143022", │ │ "report_path": "/app/reports/..._analysis.pdf", │ │ "stats": { │ │ "total_files": 85, │ │ "code_quality_score": 7.8, │ │ "high_quality_files": 45, │ │ "medium_quality_files": 30, │ │ "low_quality_files": 10, │ │ "total_issues": 23 │ │ } │ │ } │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ Return response │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ API GATEWAY │ │ │ │ 16. Receive response from AI Analysis │ │ 17. Add gateway headers │ │ 18. Forward to frontend │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ HTTP Response │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ FRONTEND APPLICATION │ │ │ │ 19. Receive response │ │ 20. Update UI with results │ │ 21. Display quality metrics │ │ 22. Show download link for report │ │ │ │ setResult(analysisData) │ │ setIsAnalyzing(false) │ └──────────────────────────────┬────────────────────────────────────────┘ │ │ ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ USER INTERFACE │ │ │ │ Display: │ │ ✓ Analysis Complete │ │ ✓ Code Quality Score: 7.8/10 │ │ ✓ Total Files: 85 │ │ ✓ Total Issues: 23 │ │ ✓ [Download Report] button │ └───────────────────────────────────────────────────────────────────────┘ ``` --- ## 2. Service Communication Diagram ``` ┌─────────────────────────────────────────────────────────────────┐ │ │ │ CODENUK MICROSERVICES │ │ │ │ ┌────────────────┐ │ │ │ FRONTEND │ │ │ │ (Next.js) │ │ │ │ Port: 3000 │ │ │ └────────┬───────┘ │ │ │ │ │ │ All requests go through Gateway │ │ ▼ │ │ ┌────────────────┐ │ │ │ API GATEWAY │◄──────────── Entry Point │ │ │ (Express.js) │ │ │ │ Port: 8000 │ │ │ └────┬───┬───┬───┘ │ │ │ │ │ │ │ │ │ └──────────────────────┐ │ │ │ │ │ │ │ │ └───────────┐ │ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────┐ ┌──────────┐ ┌──────────┐ │ │ │ AI │ │ GIT │ │ OTHER │ │ │ │ ANALYSIS│◄──┤INTEGRATION │ SERVICES │ │ │ │ │ │ │ │ │ │ │ │Port 8022│ │Port 8012 │ │ │ │ │ └────┬────┘ └────┬─────┘ └──────────┘ │ │ │ │ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────┐ ┌──────────┐ │ │ │ Redis │ │PostgreSQL│ │ │ │ Cache │ │ Database │ │ │ │Port 6379│ │Port 5432 │ │ │ └─────────┘ └──────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 3. Data Flow Diagram ``` ┌─────────────────────────────────────────────────────────────────────┐ │ DATA FLOW │ │ │ │ 1. Repository Metadata │ │ ┌──────────────┐ │ │ │ PostgreSQL │ │ │ │ Database │ │ │ └──────┬───────┘ │ │ │ │ │ │ Stores: │ │ │ - Repository info (URL, branch, owner) │ │ │ - File metadata (paths, sizes, types) │ │ │ - Directory structure │ │ │ - OAuth tokens │ │ │ - Commit history │ │ ▼ │ │ ┌──────────────────┐ │ │ │ Git Integration │ │ │ │ Service │ │ │ └──────────────────┘ │ │ │ │ 2. File Content │ │ ┌──────────────┐ │ │ │ File System │ │ │ │ /app/git-repos │ │ └──────┬───────┘ │ │ │ │ │ │ Stores: │ │ │ - Cloned repositories │ │ │ - Actual file content │ │ │ - Git history │ │ ▼ │ │ ┌──────────────────┐ │ │ │ Git Integration │ │ │ │ Service │ │ │ └──────────────────┘ │ │ │ │ 3. Analysis Cache │ │ ┌──────────────┐ │ │ │ Redis │ │ │ └──────┬───────┘ │ │ │ │ │ │ Caches: │ │ │ - File analysis results (24h TTL) │ │ │ - Key: analysis:{file_hash} │ │ │ - Value: JSON analysis result │ │ ▼ │ │ ┌──────────────────┐ │ │ │ AI Analysis │ │ │ │ Service │ │ │ └──────────────────┘ │ │ │ │ 4. Analysis Reports │ │ ┌──────────────┐ │ │ │ File System │ │ │ │ /app/reports │ │ │ └──────┬───────┘ │ │ │ │ │ │ Stores: │ │ │ - Generated PDF reports │ │ │ - JSON analysis exports │ │ │ - Downloadable via API │ │ ▲ │ │ ┌──────────────────┐ │ │ │ AI Analysis │ │ │ │ Service │ │ │ └──────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 4. Authentication Flow ``` ┌─────────────────────────────────────────────────────────────────────┐ │ GITHUB OAUTH AUTHENTICATION │ │ │ │ User needs to analyze private repository │ │ │ │ 1. Frontend → API Gateway → Git Integration │ │ POST /api/github/attach-repository │ │ { repository_url: "https://github.com/user/private-repo" } │ │ │ │ 2. Git Integration checks if repo is private │ │ - Tries to access without auth │ │ - Gets 404 (private repo) │ │ │ │ 3. Git Integration returns auth required │ │ { │ │ "success": false, │ │ "requires_auth": true, │ │ "auth_url": "https://backend.codenuk.com/api/github/auth..." │ │ } │ │ │ │ 4. Frontend redirects user to auth_url │ │ ┌──────────────┐ │ │ │ Browser │ │ │ │ Redirect │ │ │ └──────┬───────┘ │ │ │ │ │ ▼ │ │ 5. OAuth Flow │ │ ┌──────────────────────────────────────────┐ │ │ │ https://github.com/login/oauth/authorize │ │ │ │ ?client_id=xxx │ │ │ │ &redirect_uri=xxx │ │ │ │ &scope=repo │ │ │ │ &state=xxx │ │ │ └──────┬───────────────────────────────────┘ │ │ │ │ │ │ User approves │ │ ▼ │ │ 6. GitHub redirects back │ │ https://backend.codenuk.com/api/github/auth/github/callback │ │ ?code=xxx&state=xxx │ │ │ │ 7. Git Integration exchanges code for token │ │ POST https://github.com/login/oauth/access_token │ │ { code, client_id, client_secret } │ │ │ │ 8. Store token in PostgreSQL │ │ INSERT INTO github_user_tokens │ │ (user_id, access_token, scope, ...) │ │ │ │ 9. Redirect user back to frontend │ │ https://frontend.codenuk.com/repositories │ │ ?auth_success=true │ │ │ │ 10. User can now attach private repository │ │ POST /api/github/attach-repository │ │ - Service finds OAuth token for user │ │ - Uses token to clone private repo │ │ - Success! │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 5. Error Handling Flow ``` ┌─────────────────────────────────────────────────────────────────────┐ │ ERROR HANDLING │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Frontend makes request │ │ │ └────────────────┬────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ API Gateway receives request │ │ │ │ - Validates format │ │ │ │ - Checks authentication (if required) │ │ │ └────────────────┬────────────────────────────────────┘ │ │ │ │ │ ┌─────┴─────┐ │ │ │ │ │ │ Valid │ │ Invalid │ │ │ │ │ │ ▼ ▼ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ Forward │ │Return 400/401│ │ │ │ to Service │ │ Bad Request │ │ │ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ │ └───────────────────┐ │ │ ▼ │ │ │ ┌─────────────────────────────────┐ │ │ │ │ Backend Service │ │ │ │ │ - Process request │ │ │ │ │ - May call other services │ │ │ │ └─────────┬───────────────────────┘ │ │ │ │ │ │ │ ┌─────┴─────┐ │ │ │ │ │ │ │ │Success│ │ Error │ │ │ │ │ │ │ │ ▼ ▼ │ │ │ ┌────────┐ ┌─────────────────────┐ │ │ │ │Return │ │Determine Error Type │ │ │ │ │Success │ └────────┬────────────┘ │ │ │ │200/201 │ │ │ │ │ └───┬────┘ │ │ │ │ │ ▼ │ │ │ │ ┌───────────────────────┐ │ │ │ │ │ Service Unavailable │ │ │ │ │ │ (502 Bad Gateway) │ │ │ │ │ └───────┬───────────────┘ │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ ┌───────────────────────┐ │ │ │ │ │ Service Timeout │ │ │ │ │ │ (504 Gateway Timeout) │ │ │ │ │ └───────┬───────────────┘ │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ ┌───────────────────────┐ │ │ │ │ │ Rate Limit Exceeded │ │ │ │ │ │ (429 Too Many) │ │ │ │ │ └───────┬───────────────┘ │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ ┌───────────────────────┐ │ │ │ │ │ Resource Not Found │ │ │ │ │ │ (404 Not Found) │ │ │ │ │ └───────┬───────────────┘ │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ ┌───────────────────────┐ │ │ │ │ │ Other Server Error │ │ │ │ │ │ (500 Internal Error) │ │ │ │ │ └───────┬───────────────┘ │ │ │ │ │ │ │ │ │ └────────────────────┼───────────┐ │ │ │ │ │ │ │ └─────────────────────────────────┼───────────┼──┐ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌───────────────────────────┐ │ │ │ API Gateway │ │ │ │ - Log error │ │ │ │ - Add gateway headers │ │ │ │ - Forward to frontend │ │ │ └────────────┬──────────────┘ │ │ │ │ │ ▼ │ │ ┌───────────────────────────┐ │ │ │ Frontend │ │ │ │ - Display error message │ │ │ │ - Show retry option │ │ │ │ - Log for debugging │ │ │ └───────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 6. Caching Strategy ``` ┌─────────────────────────────────────────────────────────────────────┐ │ REDIS CACHING STRATEGY │ │ │ │ Request to analyze file │ │ │ │ │ ▼ │ │ ┌──────────────────┐ │ │ │ Generate file │ │ │ │ hash (SHA-256) │ │ │ └────────┬─────────┘ │ │ │ │ │ │ Hash: a3f5b8c... │ │ ▼ │ │ ┌──────────────────┐ │ │ │ Check Redis │ │ │ │ Key: analysis: │ │ │ │ a3f5b8c... │ │ │ └────────┬─────────┘ │ │ │ │ │ ┌─────┴─────┐ │ │ │ │ │ │Cache│ │ Cache │ │ Hit │ │ Miss │ │ │ │ │ │ ▼ ▼ │ │ ┌──────┐ ┌──────────────────┐ │ │ │Return│ │ Analyze file │ │ │ │Cached│ │ using Claude API │ │ │ │Result│ └────────┬─────────┘ │ │ └──┬───┘ │ │ │ │ │ Analysis result │ │ │ ▼ │ │ │ ┌──────────────────┐ │ │ │ │ Store in Redis │ │ │ │ │ TTL: 24 hours │ │ │ │ └────────┬─────────┘ │ │ │ │ │ │ └───────────────────┤ │ │ │ │ │ ▼ │ │ Return result │ │ │ │ Benefits: │ │ - Reduces Claude API calls by 60-70% │ │ - Faster response times for repeated analyses │ │ - Lowers API costs significantly │ │ - Improves user experience │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- **Version**: 1.0.0 **Last Updated**: December 2024