427 lines
11 KiB
Markdown
427 lines
11 KiB
Markdown
# 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**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
ANTHROPIC_API_KEY=sk-ant-api03-...
|
|
GIT_INTEGRATION_SERVICE_URL=http://git-integration:8012
|
|
REDIS_HOST=redis
|
|
```
|
|
|
|
**API Gateway**:
|
|
```bash
|
|
AI_ANALYSIS_URL=http://localhost:8022
|
|
GIT_INTEGRATION_URL=http://localhost:8012
|
|
```
|
|
|
|
**Git Integration**:
|
|
```bash
|
|
GITHUB_CLIENT_ID=your_client_id
|
|
GITHUB_CLIENT_SECRET=your_client_secret
|
|
POSTGRES_HOST=postgres
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Commands
|
|
|
|
```bash
|
|
# 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.
|
|
|