486 lines
8.7 KiB
Markdown
486 lines
8.7 KiB
Markdown
# 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
|
|
|