# Charts API Documentation

## Overview

The Charts API provides comprehensive analytics and charting capabilities for the Schematics Backend project. It efficiently serves chart data with Redis caching for optimal performance and includes features for users joined over time and chat analytics by type.

## Features

- **High Performance**: Redis caching with configurable TTL
- **Date Range Filtering**: Flexible date range queries with validation
- **Rate Limiting**: Built-in protection against abuse
- **Comprehensive Validation**: Joi-based input validation
- **Error Handling**: Graceful error handling with detailed messages
- **Health Monitoring**: Built-in health checks and metrics
- **Cache Management**: Cache invalidation and refresh capabilities

## Architecture

The API follows a clean architecture pattern:

```
Routes → Controller → Service → Repository → Prisma → Database
                ↓
            Redis Cache
```

### Components

- **Routes**: Express router with middleware
- **Controller**: HTTP request/response handling
- **Service**: Business logic and data processing
- **Repository**: Data access with caching
- **Middleware**: Validation, rate limiting, and cache headers

## API Endpoints

### Base URL

```
/v1/charts
```

### 1. Users Joined Chart

**GET** `/users-joined`

Returns users joined over time with date range filtering.

#### Query Parameters

- `startDate` (optional): Start date in ISO format (YYYY-MM-DD)
- `endDate` (optional): End date in ISO format (YYYY-MM-DD)

#### Example Request

```bash
GET /v1/charts/users-joined?startDate=2025-01-01&endDate=2025-01-31
```

#### Example Response

```json
{
  "success": true,
  "message": "Users joined chart data retrieved successfully",
  "data": [
    {
      "date": "2025-01-01",
      "count": 5
    },
    {
      "date": "2025-01-02",
      "count": 3
    }
  ],
  "metadata": {
    "totalCount": 150,
    "dateRange": {
      "start": "2025-01-01T00:00:00.000Z",
      "end": "2025-01-31T23:59:59.999Z"
    },
    "cached": false,
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}
```

### 2. Chats By Type Chart

**GET** `/chats-by-type`

Returns chat counts grouped by chat type with date range filtering.

#### Query Parameters

- `startDate` (optional): Start date in ISO format (YYYY-MM-DD)
- `endDate` (optional): End date in ISO format (YYYY-MM-DD)

#### Example Request

```bash
GET /v1/charts/chats-by-type?startDate=2025-01-01&endDate=2025-01-31
```

#### Example Response

```json
{
  "success": true,
  "message": "Chats by type chart data retrieved successfully",
  "data": [
    {
      "chatType": "supportive",
      "count": 45
    },
    {
      "chatType": "analytics",
      "count": 23
    },
    {
      "chatType": "motivational",
      "count": 32
    }
  ],
  "metadata": {
    "totalCount": 100,
    "dateRange": {
      "start": "2025-01-01T00:00:00.000Z",
      "end": "2025-01-31T23:59:59.999Z"
    },
    "cached": false,
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}
```

### 3. Charts Summary

**GET** `/summary`

Returns overall charts summary and statistics.

#### Example Request

```bash
GET /v1/charts/summary
```

#### Example Response

```json
{
  "success": true,
  "message": "Charts summary retrieved successfully",
  "data": {
    "totalUsers": 150,
    "totalChats": 100,
    "cacheStatus": "active"
  }
}
```

### 4. Cache Management

#### Clear Cache

**DELETE** `/cache`

Clears all charts cache.

#### Example Request

```bash
DELETE /v1/charts/cache
```

#### Example Response

```json
{
  "success": true,
  "message": "Charts cache cleared successfully"
}
```

#### Refresh Cache

**POST** `/cache/refresh`

Refreshes charts cache with optional date range.

#### Query Parameters

- `startDate` (optional): Start date in ISO format (YYYY-MM-DD)
- `endDate` (optional): End date in ISO format (YYYY-MM-DD)

#### Example Request

```bash
POST /v1/charts/cache/refresh?startDate=2025-01-01&endDate=2025-01-31
```

#### Example Response

```json
{
  "success": true,
  "message": "Charts cache refreshed successfully"
}
```

### 5. Health Check

**GET** `/health`

Returns charts service health status.

#### Example Request

```bash
GET /v1/charts/health
```

#### Example Response

```json
{
  "success": true,
  "message": "Charts service is healthy",
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "totalUsers": 150,
    "totalChats": 100,
    "cacheStatus": "active"
  }
}
```

## Redis Caching

### Cache Configuration

- **TTL**: 5 minutes for chart data, 10 minutes for summary
- **Prefix**: `charts:` for all cache keys
- **Compression**: Automatic for data > 1KB
- **Max Keys**: 1000 keys per chart type

### Cache Keys

- `charts:users-joined:{startDate}:{endDate}`
- `charts:chats-by-type:{startDate}:{endDate}`
- `charts:summary`
- `charts:metrics`

### Cache Operations

- **Get**: Retrieve cached data
- **Set**: Store data with TTL
- **Delete**: Remove specific keys
- **Invalidate**: Clear by pattern
- **Refresh**: Update cache with fresh data

## Validation

### Date Validation

- **Format**: ISO date format (YYYY-MM-DD)
- **Range**: Start date must be before end date
- **Limits**: Maximum 1 year range
- **Defaults**: Current month if not specified

### Input Sanitization

- Date parameter normalization
- Query parameter limits
- Type conversion and validation

## Rate Limiting

- **Window**: 15 minutes
- **Limit**: 100 requests per IP
- **Headers**: Standard rate limit headers
- **Response**: JSON error message

## Error Handling

### HTTP Status Codes

- `200`: Success
- `400`: Bad Request (validation errors)
- `429`: Too Many Requests (rate limiting)
- `500`: Internal Server Error
- `503`: Service Unavailable (health check failures)

### Error Response Format

```json
{
  "success": false,
  "message": "Error description",
  "error": "Specific error details",
  "details": [
    {
      "field": "fieldName",
      "message": "Validation message"
    }
  ]
}
```

## Performance Features

### Caching Strategy

- **Lazy Loading**: Cache on first request
- **TTL Management**: Automatic expiration
- **Pattern Invalidation**: Bulk cache clearing
- **Memory Optimization**: Efficient key storage

### Database Optimization

- **Indexed Queries**: Optimized Prisma queries
- **Group By Operations**: Efficient aggregation
- **Date Range Filtering**: Indexed date fields

## Monitoring & Health

### Health Checks

- Redis connectivity
- Database connectivity
- Cache performance
- Service responsiveness

### Metrics

- Cache hit/miss rates
- Response times
- Error rates
- Memory usage

## Testing

### Test Suite

- **Unit Tests**: Individual component testing
- **Integration Tests**: API endpoint testing
- **Performance Tests**: Cache performance validation
- **Error Tests**: Error handling validation

### Test Commands

```bash
# Run all tests
npm test

# Run charts tests only
npm test -- charts.test.ts

# Run with coverage
npm run test:coverage
```

## Development

### Prerequisites

- Node.js 18+
- Redis server
- PostgreSQL database
- Prisma CLI

### Installation

```bash
npm install
npm run build
```

### Environment Variables

```env
# Redis
REDIS_URL=redis://localhost:6379
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# Server
PORT=3000
NODE_ENV=development
```

### Development Commands

```bash
# Start development server
npm run dev

# Build project
npm run build

# Start production server
npm start

# Database migrations
npx prisma migrate dev

# Generate Prisma client
npx prisma generate
```

## Security

### Input Validation

- Joi schema validation
- SQL injection prevention
- XSS protection
- Parameter sanitization

### Rate Limiting

- IP-based limiting
- Configurable thresholds
- Abuse prevention

### Error Handling

- No sensitive data exposure
- Generic error messages
- Proper logging

## Deployment

### Production Considerations

- Redis cluster configuration
- Database connection pooling
- Load balancing
- Monitoring and alerting
- Backup strategies

### Docker Support

```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
EXPOSE 3000
CMD ["npm", "start"]
```

## Troubleshooting

### Common Issues

#### Cache Not Working

- Check Redis connectivity
- Verify cache configuration
- Check TTL settings

#### Slow Response Times

- Monitor database performance
- Check cache hit rates
- Review query optimization

#### Validation Errors

- Verify date format
- Check parameter types
- Review validation schemas

### Debug Mode

```bash
NODE_ENV=development DEBUG=charts:* npm run dev
```

## Contributing

### Code Style

- TypeScript strict mode
- ESLint configuration
- Prettier formatting
- Consistent naming conventions

### Testing Requirements

- 90%+ code coverage
- All endpoints tested
- Error scenarios covered
- Performance benchmarks

## License

This project is licensed under the ISC License.

## Support

For support and questions:

- Create an issue in the repository
- Check the documentation
- Review the test suite
- Contact the development team