# AI Code Review Assistant - Documentation

## Overview

The AI Code Review Assistant is a comprehensive microservices-based system that provides intelligent code analysis and review capabilities. It integrates with GitHub to automatically analyze pull requests and generate actionable feedback.

## Architecture

### Microservices Structure

The system consists of 6 core services:

1. **Main Service** (Port 8000) - API Gateway and orchestration
2. **GitHub Integration** (Port 8001) - OAuth, webhooks, and PR processing
3. **Analysis Engine** (Port 8002) - Multi-language static analysis
4. **AI Core** (Port 8003) - LLM-powered intelligent analysis
5. **Review Generation** (Port 8004) - Comment formatting and review creation
6. **Dashboard** (Port 8005) - Web UI and user management
7. **Performance Monitoring** (Port 8006) - Metrics, caching, and health monitoring

### Technology Stack

- **Backend**: FastAPI (Python)
- **Frontend**: HTML5, CSS3, JavaScript, Chart.js
- **Database**: In-memory caching (Redis-like)
- **Monitoring**: Custom metrics collection
- **Security**: HMAC signature verification, input validation

## Quick Start

### Prerequisites

- Python 3.8+
- pip package manager
- Git

### Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd ai-code-review-assistant
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. Start all services:
```bash
python main.py &
python github_service.py &
python analysis_engine.py &
python ai_core.py &
python review_service.py &
python dashboard_service.py &
python performance_service.py &
```

### Configuration

Create a `.env` file with the following variables:

```env
GITHUB_WEBHOOK_SECRET=your-secret-here
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
AI_MODEL_NAME=gpt-4-code-review
CACHE_TTL=3600
MAX_CACHE_SIZE=1000
```

## API Documentation

### Main Service API

#### Analyze Code
```http
POST /analyze
Content-Type: application/json

{
  "repository_url": "https://github.com/example/repo",
  "pull_request_id": 123,
  "files": [
    {
      "path": "src/main.py",
      "content": "print('hello world')"
    }
  ],
  "user_token": "github-token"
}
```

#### Health Check
```http
GET /health
```

### GitHub Integration API

#### Webhook Handler
```http
POST /webhook
X-Hub-Signature: sha256=signature
X-GitHub-Event: pull_request
```

#### OAuth Callback
```http
GET /auth/oauth?code=github-auth-code
```

### Analysis Engine API

#### Analyze File
```http
POST /analyze
Content-Type: application/json

{
  "file_path": "src/main.py",
  "content": "print('hello')"
}
```

#### Get Rules
```http
GET /rules?language=python
```

### AI Core API

#### AI Analysis
```http
POST /analyze
Content-Type: application/json

{
  "code": "print('hello')",
  "context": {
    "repository_info": {},
    "file_history": [],
    "dependencies": []
  },
  "analysis_types": ["security", "performance"]
}
```

### Review Generation API

#### Generate Review
```http
POST /generate
Content-Type: application/json

{
  "analysis_results": [...],
  "ai_insights": [...],
  "file_context": {...}
}
```

## Supported Languages

- **Python** - Full static analysis and security scanning
- **JavaScript** - ES6+ support, security patterns
- **TypeScript** - Type checking and best practices
- **Java** - Enterprise patterns and security
- **Go** - Concurrency and performance analysis
- **Rust** - Memory safety and patterns
- **C++** - Modern C++ features and security
- **C#** - .NET patterns and best practices

## Security Features

### Input Validation
- All inputs are validated and sanitized
- SQL injection prevention
- Code execution protection

### Authentication
- GitHub OAuth integration
- HMAC webhook signature verification
- Token-based API access

### Security Scanning
- Detects common vulnerabilities (SQL injection, XSS, etc.)
- Identifies hardcoded secrets
- Security best practices enforcement

## Performance Optimization

### Caching Strategy
- Intelligent result caching
- LRU eviction policy
- Configurable TTL

### Metrics Collection
- Response time tracking
- Error rate monitoring
- Resource usage statistics

### Scalability
- Horizontal scaling support
- Load balancing ready
- Microservices architecture

## Deployment Guide

### Docker Deployment

1. Build the image:
```bash
docker build -t ai-code-review-assistant .
```

2. Run with Docker Compose:
```yaml
version: '3.8'
services:
  main:
    image: ai-code-review-assistant
    ports:
      - "8000:8000"
    environment:
      - GITHUB_WEBHOOK_SECRET=${WEBHOOK_SECRET}
```

### Kubernetes Deployment

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ai-code-review-assistant
spec:
  replicas: 3
  selector:
    matchLabels:
      app: ai-code-review-assistant
  template:
    metadata:
      labels:
        app: ai-code-review-assistant
    spec:
      containers:
      - name: main
        image: ai-code-review-assistant:latest
        ports:
        - containerPort: 8000
```

### Cloud Deployment

#### AWS
- Use ECS Fargate for container orchestration
- RDS for persistent storage
- CloudWatch for monitoring

#### Google Cloud
- Cloud Run for serverless deployment
- Cloud SQL for database
- Stackdriver for monitoring

#### Azure
- Container Instances for deployment
- Azure SQL for database
- Application Insights for monitoring

## Monitoring and Maintenance

### Health Checks
Each service provides a `/health` endpoint returning:
- Service status
- Dependencies health
- Performance metrics

### Logging
- Structured JSON logging
- Request/response tracking
- Error correlation

### Alerting
- Performance threshold alerts
- Error rate notifications
- Service health monitoring

## Testing

### Unit Tests
```bash
python test_suite.py
```

### Integration Tests
```bash
python -m pytest tests/integration/
```

### Security Tests
```bash
python -m pytest tests/security/
```

### Performance Tests
```bash
python -m pytest tests/performance/
```

## Troubleshooting

### Common Issues

#### Service Not Starting
- Check port availability
- Verify environment variables
- Review service logs

#### GitHub Integration Failing
- Verify webhook secret
- Check OAuth credentials
- Validate repository permissions

#### Analysis Errors
- Check file format support
- Verify code syntax
- Review analysis rules

### Debug Mode

Enable debug logging:
```bash
export LOG_LEVEL=DEBUG
python main.py
```

## Contributing

### Development Setup
1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Submit a pull request

### Code Standards
- Follow PEP 8 for Python
- Use type hints
- Write comprehensive tests
- Document all public APIs

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

- **Documentation**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/example/issues)
- **Discussions**: [GitHub Discussions](https://github.com/example/discussions)

## Changelog

### v1.0.0
- Initial release
- Core microservices architecture
- GitHub integration
- Multi-language analysis
- AI-powered insights
- Web dashboard
- Performance monitoring

---

*Last updated: February 8, 2026*