# Backend Documentation

## Backend Framework and Language

**Framework**: Node.js with Express.js
**Language**: JavaScript/TypeScript
**Architecture**: RESTful API with layered architecture

Node.js with Express.js is chosen for:
- Excellent performance for real-time applications
- Rich ecosystem of packages for financial data processing
- Good compatibility with React frontend
- Efficient handling of asynchronous operations (important for LLM API calls)
- Seamless integration with Supabase

## API Design

### API Structure

The API follows RESTful principles with the following main resources:

1. **Auth**
   - `/api/auth/login` - Social login with Google
   - `/api/auth/logout` - User logout
   - `/api/auth/refresh` - Token refresh

2. **Users**
   - `/api/users/profile` - User profile management
   - `/api/users/api-keys` - Secure API key management
   - `/api/users/credits` - Credit management

3. **Indicators**
   - `/api/indicators` - CRUD operations for indicators
   - `/api/indicators/categories` - Get indicators by category
   - `/api/indicators/trending` - Get trending indicators

4. **Strategies**
   - `/api/strategies` - CRUD operations for strategies
   - `/api/strategies/generate` - AI strategy generation
   - `/api/strategies/export` - Generate PineScript code
   - `/api/strategies/versions` - Strategy version management

5. **Community**
   - `/api/community/strategies` - Shared strategies
   - `/api/community/users` - User profiles

### API Versioning

The API will be versioned using URL path versioning:
- `/api/v1/...` - Initial version

### Authentication and Authorization

1. **Authentication**
   - JWT (JSON Web Tokens) for session management
   - Google OAuth for social login
   - Refresh token rotation for security

2. **Authorization**
   - Role-based access control (Free user vs. Paid user)
   - Resource-based permissions

## LLM Integration

### Supported Providers
- OpenAI
- Anthropic
- OpenRouter.ai

### Integration Architecture

1. **Provider Adapter Pattern**
   - Abstract interface for LLM providers
   - Concrete implementations for each provider
   - Fallback mechanism if primary provider fails

2. **Prompt Engineering**
   - Structured prompts for strategy generation
   - Context management for complex strategies
   - Response validation and error handling

3. **Security Considerations**
   - Encrypted storage of API keys
   - No persistence of full strategy responses
   - Rate limiting to prevent abuse

## Error Handling

1. **Standardized Error Responses**
   ```json
   {
     "status": "error",
     "code": "ERROR_CODE",
     "message": "User-friendly error message",
     "details": { /* Additional error details */ }
   }
   ```

2. **Error Categories**
   - Authentication errors (401)
   - Authorization errors (403)
   - Resource not found (404)
   - Validation errors (422)
   - Server errors (500)
   - LLM provider errors (502)

3. **Graceful Degradation**
   - Fallback options when services are unavailable
   - Detailed user instructions for recovery

## Third-Party Integrations

1. **Payment Processing**
   - Stripe integration for subscription management
   - PayPal as alternative payment method
   - Coupon code functionality

2. **Email Service**
   - Transactional emails for account verification
   - Subscription notifications
   - Strategy export delivery

## Caching Strategy

1. **Redis Cache**
   - Cache common indicator configurations
   - Store frequently accessed strategy templates
   - Temporary storage for generated strategies

2. **Cache Invalidation**
   - Time-based expiration for market data
   - Event-based invalidation for user-specific data

## Security Measures

1. **Data Protection**
   - Encryption of sensitive data at rest
   - Secure transmission with TLS
   - API key encryption with AES-256

2. **API Security**
   - Rate limiting to prevent abuse
   - CORS configuration for frontend access
   - Input validation and sanitization
   - Protection against common attacks (XSS, CSRF, injection)

3. **Monitoring and Logging**
   - Structured logging for operations
   - Error tracking and alerting
   - Audit trail for sensitive operations

## Performance Optimization

1. **Query Optimization**
   - Efficient database queries
   - Pagination for large result sets
   - Eager loading of related data

2. **Asynchronous Processing**
   - Background jobs for resource-intensive tasks
   - Queuing system for LLM requests

3. **Scaling Considerations**
   - Horizontal scaling readiness
   - Stateless API design
   - Connection pooling for database access