# AI Analysis Service - Quick Reference Guide

## Quick Start

### 1. Start All Services

```bash
cd /path/to/codenuk/backend/codenuk_backend_mine
docker-compose up -d
```

### 2. Verify Services are Running

```bash
# Check all services
docker-compose ps

# Test individual services
curl http://localhost:8000/health          # API Gateway
curl http://localhost:8022/health          # AI Analysis
curl http://localhost:8012/health          # Git Integration
```

### 3. Run Analysis from Frontend

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

const { startAnalysis } = useAIAnalysis()

await startAnalysis(repositoryId, userId, {
  output_format: 'pdf',
  max_files: 100
})
```

---

## Common API Calls

### Analyze Repository

```bash
curl -X POST http://localhost:8000/api/ai-analysis/analyze-repository \
  -H "Content-Type: application/json" \
  -d '{
    "repository_id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "660e8400-e29b-41d4-a716-446655440001",
    "output_format": "pdf",
    "max_files": 100
  }'
```

### Get Repository Info

```bash
curl http://localhost:8000/api/github/repository/550e8400-e29b-41d4-a716-446655440000/ui-view?view_type=tree \
  -H "x-user-id: 660e8400-e29b-41d4-a716-446655440001"
```

### Download Report

```bash
curl http://localhost:8000/api/ai-analysis/reports/repo_analysis_550e8400_20241216_143022_analysis.pdf \
  --output analysis_report.pdf
```

### Get Memory Stats

```bash
curl http://localhost:8000/api/ai-analysis/memory/stats
```

---

## Service URLs

| Service | Direct URL | Via Gateway |
|---------|-----------|-------------|
| AI Analysis | http://localhost:8022 | http://localhost:8000/api/ai-analysis |
| Git Integration | http://localhost:8012 | http://localhost:8000/api/github |
| API Gateway | http://localhost:8000 | N/A |
| Frontend | http://localhost:3000 | N/A |

---

## Environment Variables Quick Reference

### AI Analysis Service

```bash
PORT=8022
ANTHROPIC_API_KEY=sk-ant-api03-...
GIT_INTEGRATION_SERVICE_URL=http://git-integration:8012
REDIS_HOST=redis
REDIS_PORT=6379
```

### API Gateway

```bash
PORT=8000
AI_ANALYSIS_URL=http://localhost:8022
GIT_INTEGRATION_URL=http://localhost:8012
```

### Git Integration

```bash
PORT=8012
POSTGRES_HOST=postgres
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
PUBLIC_BASE_URL=https://backend.codenuk.com
```

---

## Troubleshooting Commands

### Check Service Logs

```bash
# AI Analysis Service
docker logs ai-analysis -f

# API Gateway
docker logs api-gateway -f

# Git Integration
docker logs git-integration -f

# All services
docker-compose logs -f
```

### Restart Service

```bash
# Restart specific service
docker-compose restart ai-analysis

# Restart all services
docker-compose restart
```

### Check Service Health

```bash
# Using curl
curl http://localhost:8022/health

# Using docker exec
docker exec ai-analysis curl localhost:8022/health
```

### Clear Redis Cache

```bash
docker exec redis redis-cli FLUSHDB
```

### Check Database Connection

```bash
docker exec postgres psql -U postgres -d git_integration -c "SELECT COUNT(*) FROM all_repositories;"
```

---

## Common Issues and Fixes

### Issue: Service Cannot Connect

```bash
# Check if service is running
docker ps | grep ai-analysis

# Check network connectivity
docker network inspect backend-network

# Restart service
docker-compose restart ai-analysis
```

### Issue: Redis Connection Failed

```bash
# Check Redis status
docker exec redis redis-cli ping

# Expected output: PONG
```

### Issue: Rate Limit Exceeded

```bash
# Edit .env file
CLAUDE_REQUESTS_PER_MINUTE=50  # Reduce from 90

# Restart service
docker-compose restart ai-analysis
```

### Issue: Analysis Timeout

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

---

## File Locations

### Reports
```
/app/reports/repo_analysis_{id}_{timestamp}_analysis.pdf
```

### Repository Storage
```
/app/git-repos/{owner}__{repo}__{branch}/
```

### Logs
```
docker logs {service_name}
```

### Configuration
```
services/ai-analysis-service/.env
services/api-gateway/.env
services/git-integration/.env
```

---

## Testing Endpoints

### Test AI Analysis Service Directly

```bash
# Health check
curl http://localhost:8022/health

# Test with direct repository analysis
curl -X POST http://localhost:8022/analyze-repository \
  -H "Content-Type: application/json" \
  -d '{
    "repository_id": "test-id",
    "user_id": "test-user",
    "output_format": "json",
    "max_files": 10
  }'
```

### Test Git Integration Service

```bash
# Health check
curl http://localhost:8012/health

# Get repository list
curl http://localhost:8012/api/github/user/test-user-id/repositories \
  -H "x-user-id: test-user-id"
```

### Test Through API Gateway

```bash
# Health check
curl http://localhost:8000/health

# Test AI Analysis proxying
curl http://localhost:8000/api/ai-analysis/health

# Test Git Integration proxying
curl http://localhost:8000/api/github/health
```

---

## Performance Tuning

### Optimize for Speed

```bash
# Reduce max files
max_files: 50

# Increase rate limit (if you have higher API limits)
CLAUDE_REQUESTS_PER_MINUTE=150

# Enable more aggressive caching
CACHE_TTL_SECONDS=172800  # 48 hours instead of 24
```

### Optimize for Quality

```bash
# Analyze more files
max_files: 200

# Reduce content truncation threshold
CONTENT_MAX_TOKENS=16000  # Instead of 8000
```

---

## Monitoring

### Check Analysis Progress

```bash
# Watch logs in real-time
docker logs ai-analysis -f | grep "Analyzing file"
```

### Monitor Redis Cache

```bash
# Get cache stats
docker exec redis redis-cli INFO stats

# Check cache keys
docker exec redis redis-cli KEYS "analysis:*"

# Get cache hit rate
docker exec redis redis-cli INFO stats | grep keyspace
```

### Monitor Database

```bash
# Check repository count
docker exec postgres psql -U postgres -d git_integration \
  -c "SELECT COUNT(*) FROM all_repositories;"

# Check recent analyses
docker exec postgres psql -U postgres -d git_integration \
  -c "SELECT id, repository_name, created_at FROM all_repositories ORDER BY created_at DESC LIMIT 10;"
```

---

## Development Tips

### Run Service Locally (Outside Docker)

```bash
# AI Analysis Service
cd services/ai-analysis-service
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-api03-...
export GIT_INTEGRATION_SERVICE_URL=http://localhost:8012
python server.py
```

### Hot Reload

```bash
# Frontend (auto-reloads)
cd fronend/codenuk_frontend_mine
npm run dev

# Backend services (use nodemon)
cd services/api-gateway
npm install -g nodemon
nodemon src/server.js
```

### Debug Mode

```bash
# Enable debug logging
export DEBUG=*
export LOG_LEVEL=debug

# Python service
export PYTHONUNBUFFERED=1
```

---

## Security Checklist

- [ ] Set strong GITHUB_CLIENT_SECRET
- [ ] Set secure POSTGRES_PASSWORD
- [ ] Rotate ANTHROPIC_API_KEY regularly
- [ ] Use HTTPS in production (PUBLIC_BASE_URL)
- [ ] Set CORS_ORIGIN to specific domains in production
- [ ] Enable Redis password in production
- [ ] Set SESSION_SECRET to secure random string
- [ ] Never commit .env files to git

---

## Backup and Restore

### Backup PostgreSQL Database

```bash
docker exec postgres pg_dump -U postgres git_integration > backup.sql
```

### Restore PostgreSQL Database

```bash
docker exec -i postgres psql -U postgres git_integration < backup.sql
```

### Backup Redis Cache

```bash
docker exec redis redis-cli BGSAVE
docker cp redis:/data/dump.rdb ./redis-backup.rdb
```

---

## Useful Docker Commands

```bash
# View all containers
docker-compose ps

# Stop all services
docker-compose down

# Restart specific service
docker-compose restart ai-analysis

# View logs
docker-compose logs -f ai-analysis

# Execute command in container
docker exec -it ai-analysis bash

# Remove all containers and volumes
docker-compose down -v

# Rebuild specific service
docker-compose build ai-analysis

# Scale service (if supported)
docker-compose up -d --scale ai-analysis=3
```

---

## API Response Codes

| Code | Meaning | Action |
|------|---------|--------|
| 200 | Success | Continue |
| 201 | Created | Resource created successfully |
| 400 | Bad Request | Check request parameters |
| 401 | Unauthorized | Authenticate user |
| 403 | Forbidden | Check permissions |
| 404 | Not Found | Verify resource ID |
| 429 | Rate Limited | Wait and retry |
| 500 | Server Error | Check service logs |
| 502 | Bad Gateway | Check if service is running |
| 504 | Gateway Timeout | Increase timeout or reduce load |

---

## Contact and Support

For detailed documentation, see:
- [Full Architecture Documentation](./SERVICE_COMMUNICATION_ARCHITECTURE.md)
- [Integration Examples](./INTEGRATION_EXAMPLE.md)
- [AI Analysis README](./README.md)

---

**Version**: 1.0.0
**Last Updated**: December 2024