prakash/codenuk_backend_mine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3c9a45eb2b
codenuk_backend_mine/services/ai-analysis-service/README_DOCUMENTATION.md
Pradeep de71743b61 implemented direct file passes
2025-10-17 10:33:14 +05:30

11 KiB
Raw Blame History

AI Analysis Service Documentation

Welcome! This directory contains comprehensive documentation for understanding how the AI Analysis Service connects and communicates with the Frontend, API Gateway, and Git Integration Service.

Documentation Files Overview

I've created 5 comprehensive documentation files for you:

1. DOCUMENTATION_INDEX.md (START HERE)

Your main entry point - Contains:

  • Quick navigation to all documents
  • Architecture overview
  • Environment setup guide
  • API endpoints reference
  • Configuration details
  • Troubleshooting guide
  • Common questions and answers

Use this when: You want a high-level overview and quick navigation

2. SERVICE_COMMUNICATION_ARCHITECTURE.md (DETAILED GUIDE)

Complete technical documentation - Contains:

  • Detailed system architecture with diagrams
  • Component descriptions (AI Analysis, API Gateway, Git Integration, Frontend)
  • Complete communication flow (step-by-step)
  • All API endpoints with request/response examples
  • Internal component details (Rate Limiter, Cache, Optimizer)
  • Error handling strategies
  • Deployment configuration
  • Performance considerations
  • Security guidelines

Use this when: You need in-depth understanding of the system

Key Sections:

  • System Architecture Overview
  • Service Components (detailed)
  • Communication Flow (complete request lifecycle)
  • AI Analysis Service Details (endpoints, classes, methods)
  • API Gateway Integration
  • Git Integration Service
  • Frontend Integration (React hooks, API calls)
  • Request/Response Examples (real-world scenarios)
  • Error Handling (all error types and solutions)
  • Deployment Configuration (Docker, environment variables)

3. QUICK_REFERENCE.md (QUICK COMMANDS)

Fast reference for common operations - Contains:

  • Quick start commands
  • Common API calls (curl examples)
  • Service URLs table
  • Environment variables quick reference
  • Troubleshooting commands
  • File locations
  • Testing endpoints
  • Performance tuning tips
  • Monitoring commands
  • Development tips
  • Useful Docker commands
  • API response codes

Use this when: You need to quickly execute a command or check a configuration

Example:

# Start all services
docker-compose up -d

# Check service health
curl http://localhost:8022/health

# View logs
docker logs ai-analysis -f

4. FLOW_DIAGRAMS.md (VISUAL DIAGRAMS)

Visual representations of data flow - Contains:

  • Complete request flow diagram (ASCII art)
  • Service communication diagram
  • Data flow diagram
  • Authentication flow
  • Error handling flow
  • Caching strategy diagram

Use this when: You want to visualize how requests flow through the system

Includes:

  1. Complete Request Flow (21 steps from user click to response)
  2. Service Communication Diagram (how services connect)
  3. Data Flow Diagram (PostgreSQL, File System, Redis, Reports)
  4. Authentication Flow (GitHub OAuth)
  5. Error Handling Flow (decision tree)
  6. Caching Strategy (cache hit/miss flow)

5. INTEGRATION_EXAMPLE.md (EXISTING FILE)

Code examples and usage patterns - Contains:

  • Frontend integration examples
  • TypeScript interfaces
  • React component examples
  • API service functions

Use this when: You're writing code to integrate with the service

Quick Start

1. Understand the Architecture

Start with: DOCUMENTATION_INDEX.md

  • Read "Architecture Overview" section
  • Review "System Components"
  • Check "Environment Setup"

2. See the Flow

Next, read: FLOW_DIAGRAMS.md

  • Look at "Complete Request Flow"
  • Review "Service Communication Diagram"
  • Understand "Data Flow Diagram"

3. Get Detailed Information

Deep dive: SERVICE_COMMUNICATION_ARCHITECTURE.md

  • Read sections relevant to your needs
  • Check API endpoints
  • Review error handling

4. Execute Commands

Use: QUICK_REFERENCE.md

  • Copy and run commands
  • Check configurations
  • Troubleshoot issues

Common Use Cases

Use Case 1: Setting Up the Service

Path: DOCUMENTATION_INDEX.md → Environment Setup → Quick Reference

  1. Read environment setup in DOCUMENTATION_INDEX.md
  2. Copy environment variables from QUICK_REFERENCE.md
  3. Run quick start commands
  4. Verify with health checks

Use Case 2: Understanding Communication Flow

Path: FLOW_DIAGRAMS.md → SERVICE_COMMUNICATION_ARCHITECTURE.md

  1. View visual diagram in FLOW_DIAGRAMS.md
  2. Read detailed flow in SERVICE_COMMUNICATION_ARCHITECTURE.md
  3. Check request/response examples

Use Case 3: Debugging an Issue

Path: QUICK_REFERENCE.md → Troubleshooting → SERVICE_COMMUNICATION_ARCHITECTURE.md

  1. Check common issues in QUICK_REFERENCE.md
  2. Run troubleshooting commands
  3. Review error handling in SERVICE_COMMUNICATION_ARCHITECTURE.md
  4. Check logs and health endpoints

Use Case 4: Integrating Frontend

Path: INTEGRATION_EXAMPLE.md → SERVICE_COMMUNICATION_ARCHITECTURE.md → Frontend Integration

  1. Review code examples in INTEGRATION_EXAMPLE.md
  2. Check API endpoints in SERVICE_COMMUNICATION_ARCHITECTURE.md
  3. Implement using provided React hooks
  4. Test with examples from QUICK_REFERENCE.md

Use Case 5: Deploying to Production

Path: DOCUMENTATION_INDEX.md → Deployment → SERVICE_COMMUNICATION_ARCHITECTURE.md

  1. Review deployment checklist in DOCUMENTATION_INDEX.md
  2. Check configuration in SERVICE_COMMUNICATION_ARCHITECTURE.md
  3. Set environment variables from QUICK_REFERENCE.md
  4. Monitor using commands from QUICK_REFERENCE.md

File Navigation Map

ai-analysis-service/
├── DOCUMENTATION_INDEX.md          ← START HERE (Overview & Navigation)
├── SERVICE_COMMUNICATION_ARCHITECTURE.md  ← Complete Technical Guide
├── QUICK_REFERENCE.md              ← Commands & Quick Tips
├── FLOW_DIAGRAMS.md                ← Visual Diagrams
├── INTEGRATION_EXAMPLE.md          ← Code Examples
├── README.md                       ← Service README
├── server.py                       ← Main Service Code
├── ai-analyze.py                   ← Analysis Logic
└── ... (other files)

Documentation Features

Comprehensive Coverage

  • System architecture and design
  • All service interactions
  • Complete API documentation
  • Error handling strategies
  • Performance optimization tips
  • Security considerations
  • Deployment guidelines

Easy Navigation

  • Table of contents in each file
  • Cross-references between documents
  • Clear section headers
  • Logical flow of information

Practical Examples

  • Real curl commands
  • Docker commands
  • Code snippets
  • Configuration examples
  • Request/response samples

Visual Aids

  • ASCII art diagrams
  • Flow charts
  • Data flow illustrations
  • Service communication maps

Troubleshooting Support

  • Common issues and solutions
  • Debugging commands
  • Log analysis tips
  • Health check procedures

Key Concepts Explained

1. Service Communication

The AI Analysis Service communicates with:

  • Git Integration: To get repository files and metadata
  • API Gateway: Acts as entry point for all requests
  • Redis: For caching analysis results
  • Claude API: For AI-powered code analysis

2. Request Flow

Frontend → API Gateway → AI Analysis → Git Integration → PostgreSQL/FileSystem
                              ↓
                          Claude API
                              ↓
                            Redis

3. Analysis Process

  1. Get repository info from Git Integration
  2. Retrieve file list
  3. For each file:
    • Check cache
    • Apply rate limiting
    • Optimize content
    • Analyze with Claude
    • Cache result
  4. Generate repository-level analysis
  5. Create PDF/JSON report

4. Key Features

  • Rate Limiting: 90 requests/minute to Claude API
  • Caching: 24-hour TTL in Redis
  • Content Optimization: Truncates files > 8000 tokens
  • Error Handling: Comprehensive error responses
  • Authentication: GitHub OAuth for private repos

Environment Variables Summary

Required Variables

AI Analysis Service:

ANTHROPIC_API_KEY=sk-ant-api03-...
GIT_INTEGRATION_SERVICE_URL=http://git-integration:8012
REDIS_HOST=redis

API Gateway:

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

Git Integration:

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
POSTGRES_HOST=postgres

Quick Commands

# Start all services
docker-compose up -d

# Check health
curl http://localhost:8000/health
curl http://localhost:8022/health
curl http://localhost:8012/health

# Analyze repository
curl -X POST http://localhost:8000/api/ai-analysis/analyze-repository \
  -H "Content-Type: application/json" \
  -d '{"repository_id": "uuid", "user_id": "user-uuid", "output_format": "pdf", "max_files": 100}'

# View logs
docker logs ai-analysis -f

# Restart service
docker-compose restart ai-analysis

Support

If You Need Help

  1. Check DOCUMENTATION_INDEX.md for quick answers
  2. Use QUICK_REFERENCE.md for common commands
  3. Review FLOW_DIAGRAMS.md to understand the flow
  4. Read SERVICE_COMMUNICATION_ARCHITECTURE.md for detailed info
  5. Check service logs using commands in QUICK_REFERENCE.md

Troubleshooting Process

  1. Identify the issue
  2. Check relevant documentation section
  3. Run diagnostic commands
  4. Review logs
  5. Verify configuration
  6. Test endpoints individually

What's Documented

System Architecture

  • Overall system design
  • Service relationships
  • Communication patterns
  • Data storage

Services

  • AI Analysis Service (detailed)
  • API Gateway (routing, proxying)
  • Git Integration (repository access)
  • Frontend (React hooks, API calls)

Operations

  • Installation and setup
  • Configuration
  • Running and monitoring
  • Troubleshooting
  • Deployment

Integration

  • API endpoints
  • Request/response formats
  • Error handling
  • Authentication flow
  • Frontend integration

Performance

  • Rate limiting
  • Caching strategies
  • Content optimization
  • Timeout configurations

Security

  • API key management
  • OAuth tokens
  • Network security
  • CORS configuration

Version Information

Documentation Version: 1.0.0 Last Updated: December 2024 Service Version: 1.0.0

Next Steps

  1. Read DOCUMENTATION_INDEX.md for overview
  2. Review FLOW_DIAGRAMS.md for visual understanding
  3. Study SERVICE_COMMUNICATION_ARCHITECTURE.md for details
  4. Keep QUICK_REFERENCE.md handy for commands
  5. Use INTEGRATION_EXAMPLE.md when coding

Feedback

If you find any issues or have suggestions for improving this documentation:

  • Check if information is accurate
  • Verify commands work
  • Test examples
  • Suggest improvements

Happy Coding!

For any questions, refer to the appropriate documentation file based on your needs.