backend_requirements.md

# Backend Requirements

## Overview
This document outlines the technical requirements for the Flask API backend of the Lin application.

## Python Dependencies
The backend will require the following Python packages:

### Core Dependencies
- Flask: Web framework
- Flask-CORS: Cross-Origin Resource Sharing support
- Flask-JWT-Extended: JWT token management
- Flask-SQLAlchemy: ORM for database interactions
- Flask-Migrate: Database migration support
- python-dotenv: Environment variable management
- requests: HTTP library for API calls
- requests-oauthlib: OAuth support
- apscheduler: Task scheduling
- supabase: Supabase client for database operations
- pandas: Data manipulation
- gradio-client: Hugging Face API client

### Development Dependencies
- pytest: Testing framework
- pytest-cov: Test coverage reporting
- flake8: Code linting
- black: Code formatting

## Environment Variables
The backend will require the following environment variables:

- SUPABASE_URL: Supabase project URL
- SUPABASE_KEY: Supabase API key
- CLIENT_ID: LinkedIn OAuth client ID
- CLIENT_SECRET: LinkedIn OAuth client secret
- REDIRECT_URL: LinkedIn OAuth redirect URL
- HUGGING_KEY: Hugging Face API key
- JWT_SECRET_KEY: Secret key for JWT token generation
- DATABASE_URL: Database connection string (if using PostgreSQL directly)

## Database Requirements
The application will use Supabase as the primary database, which is based on PostgreSQL. The following tables will be needed:

### Users
- id (UUID)
- email (string)
- password_hash (string)
- created_at (timestamp)
- email_confirmed_at (timestamp)

### Social_network
- id (UUID)
- user_id (UUID, foreign key to Users)
- social_network (string)
- account_name (string)
- token (string)
- sub (string)
- given_name (string)
- family_name (string)
- picture (string)
- created_at (timestamp)

### Source
- id (UUID)
- user_id (UUID, foreign key to Users)
- source (string)
- category (string)
- last_update (timestamp)
- created_at (timestamp)

### Post_content
- id (UUID)
- social_account_id (UUID, foreign key to Social_network)
- text_content (text)
- image_content_url (bytea or URL)
- is_published (boolean)
- sched (UUID)
- created_at (timestamp)
- scheduled_at (timestamp)

### Scheduling
- id (UUID)
- social_account_id (UUID, foreign key to Social_network)
- schedule_time (string)
- adjusted_time (string)
- created_at (timestamp)

## API Requirements

### Authentication
- JWT-based authentication
- Password hashing with bcrypt
- Email confirmation flow
- Password reset functionality

### Security
- CORS policy configuration
- Input validation and sanitization
- Rate limiting for API endpoints
- Secure headers implementation

### Error Handling
- Consistent error response format
- Proper HTTP status codes
- Logging of errors for debugging
- Validation error handling

## Integration Requirements

### LinkedIn API
- OAuth2 authentication flow
- Post creation and publishing
- User profile information retrieval
- Image upload support

### Hugging Face API
- Content generation using Gradio client
- Error handling for API failures
- Timeout handling for long-running requests

### Scheduling System
- APScheduler for task management
- Conflict resolution for overlapping schedules
- Automatic adjustment of schedule times
- Persistent storage of scheduled tasks

## Deployment Requirements

### Server
- Python 3.8+
- WSGI server (Gunicorn recommended)
- Reverse proxy (Nginx recommended)
- SSL certificate for HTTPS

### Scalability
- Stateless design for horizontal scaling
- Database connection pooling
- Caching strategy for frequently accessed data
- Background task processing for long-running operations

### Monitoring
- Logging configuration
- Health check endpoints
- Performance monitoring
- Error tracking integration

## Testing Requirements

### Unit Tests
- Model validation tests
- Service layer tests
- Utility function tests

### Integration Tests
- API endpoint tests
- Database integration tests
- External API integration tests

### Test Coverage
- Minimum 80% code coverage
- Testing of edge cases
- Mocking of external dependencies
- Continuous integration setup