57 KiB
57 KiB
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