# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

CQA Test Application is a Flask-based test automation and validation service designed for testing various cloud services and infrastructure components. It provides REST APIs for testing FOS (File Object Storage), DBS (Database Service), Function-as-a-Service, App Runner, and load balancing functionality.

## Development Commands

### Running the Application
```bash
# Local development
python run_cqa_test_app.py

# MCP Server (standalone)
python run_mcp_server.py

# Docker local testing
docker build -t cqa-test-app .
docker run -p 80:80 cqa-test-app

# Docker Compose (includes Prometheus monitoring)
docker-compose up --build
```

### Environment Configuration
Required environment variables:
- `CQA_TEST_APP_ENV`: Environment setting (dev/prod, defaults to prod)
- `CQA_TEST_APP_HTTP_PORT`: HTTP port (defaults to 80)
- `CQA_TEST_APP_HTTPS_PORT`: HTTPS port (defaults to 443)
- `UDP_TEST`: Enable UDP server (true/false)
- `UDP_PORT`: UDP server port (defaults to 8080)
- `FLAVA_LOGSTORE_TOKEN`: OpenTelemetry logging token

### Jira Integration (for MCP)
- `JIRA_URL`: Jira server URL (e.g., https://your-domain.atlassian.net)
- `JIRA_PERSONAL_TOKEN`: Personal Access Token (recommended)
- `JIRA_USERNAME` + `JIRA_API_TOKEN`: Username/email + API token (legacy)

Copy `.env.example` to `.env` and configure your settings.

### Deployment
```bash
# Kubernetes deployment
kubectl apply -f ./deployments/cqa-test-app-k8s.yaml -n <namespace>

# AWS App Runner deployment (see README.md for detailed steps)
aws apprunner create-service --service-name cqa-test-app
```

## Architecture

### Core Structure
- `run_cqa_test_app.py`: Main Flask application entry point
- `common/context.py`: Central context and API function initialization
- `functions/APIFunctions.py`: Core business logic and API implementations
- `lib/`: Utility libraries (auth, certificates, S3 client, logging)
- `products/`: Product-specific modules (PaaS, FaaS)
- `templates/`: HTML templates for web UI testing pages

### Key Components

**Main Application (`run_cqa_test_app.py`)**:
- Multi-threaded server running HTTP (port 80), HTTPS (port 443), and optional UDP
- Prometheus metrics integration
- Self-signed SSL certificate generation
- Signal handling for graceful shutdown

**API Functions (`functions/APIFunctions.py`)**:
- Command execution (`/run_cmd`)
- File operations and FOS testing
- Database connectivity testing  
- iPerf network testing
- Athenz authentication integration

**Product Modules**:
- `products/paas/app_runner.py`: App Runner environment variable APIs
- `products/faas/`: Function-as-a-Service testing handlers
- `products/jira/api.py`: Jira integration REST APIs
- `products/mcp/api.py`: MCP (Model Context Protocol) server APIs
- `testapps/lb_least_conn.py`: Load balancer testing applications

**MCP Integration**:
- HTTP API endpoints for MCP tool execution (`/api/mcp/`)
- Jira tools: list projects, search issues, get issue details, create issues
- System tools: command execution, network testing
- Integrated within Flask app

**Authentication & Security**:
- HTTP Basic Auth via `lib/auth.py`
- Athenz token-based authentication
- Self-signed certificate generation for HTTPS

### Service Endpoints
- `/`: Main documentation page
- `/test`: Health check endpoint
- `/monitor/l7check`: Load balancer health check
- `/run_cmd`: Execute shell commands via POST
- `/api/app_runner/env_vars`: Environment variable inspection
- `/test_fos_*`: File Object Storage testing endpoints
- `/connect`, `/execute_query`: Database testing endpoints
- UI test pages: `/test_fos_ui/`, `/dbs_test_ui/`, `/function_test_ui/`, `/jira_test_ui/`

#### Jira Integration Endpoints
- `/api/jira/projects`: List accessible Jira projects
- `/api/jira/search`: Search issues using JQL
- `/api/jira/issue/<key>`: Get issue details
- `/api/jira/issue/<key>/comments`: Get issue comments
- `/api/jira/issue`: Create new issue (POST)
- `/api/jira/status`: Check Jira connection status

#### MCP Server Endpoints
- `/api/mcp/tools`: List available MCP tools
- `/api/mcp/execute`: Execute MCP tool (POST)
- `/api/mcp/server/info`: MCP server information

### Monitoring & Observability
- Prometheus metrics exported automatically
- OpenTelemetry structured logging to Flava monitoring system
- Environment-specific log endpoints (dev/prod)
- Custom metrics for request tracking and performance monitoring

### Testing Infrastructure
- Supports multiple deployment models: VM, Docker, Kubernetes, AWS App Runner
- Built-in load balancer testing with least-connection algorithms
- Network performance testing via iPerf3 integration
- Database connectivity testing for MySQL and PostgreSQL
- File storage operations testing with CRUD operations

## MCP Hub Integration

This application now serves as an MCP server for testing and QA automation:

### MCP Tools Available
1. **Jira Tools**:
   - `jira_list_projects`: List accessible projects
   - `jira_search_issues`: Search using JQL queries
   - `jira_get_issue`: Get detailed issue information
   - `jira_get_comments`: Retrieve issue comments
   - `jira_create_issue`: Create new issues

2. **System Tools**:
   - `run_command`: Execute system commands
   - `network_test`: Run iperf3 network performance tests

### MCP Server Usage
```bash
# Use HTTP API endpoints
curl -X GET http://localhost:80/api/mcp/tools
curl -X POST http://localhost:80/api/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "jira_list_projects", "arguments": {}}'
```

## Important Notes
- The application runs multiple servers concurrently (HTTP, HTTPS, UDP optional)
- Uses Flask-RESTful for API structure and Swagger UI for documentation
- Integrated with internal Line Corp infrastructure (Athenz, VCR registry)
- Environment-specific configuration via environment variables
- Prometheus monitoring configured in `config/prometheus.yml`
- MCP tools are integrated within Flask app via HTTP APIs
- Jira integration requires proper API credentials configuration