backend/README.md

# Lin Backend API

This is the Flask backend API for the Lin application, a community manager assistant for LinkedIn.

## Features

- User authentication (registration, login, logout)
- Social media account management (LinkedIn integration)
- RSS source management
- AI-powered content generation
- Post scheduling and publishing
- RESTful API design
- JWT-based authentication
- Task scheduling with Celery

## Technologies

- Flask (Python web framework)
- Supabase (Database and authentication)
- Celery (Distributed task queue)
- Redis (Message broker for Celery)
- requests (HTTP library)
- requests-oauthlib (OAuth support)
- gradio-client (Hugging Face API)
- Flask-JWT-Extended (JWT token management)

## Project Structure

```
backend/
├── app.py                 # Flask application entry point
├── config.py              # Configuration settings
├── requirements.txt       # Python dependencies
├── .env.example          # Environment variables example
├── celery_app.py          # Celery application configuration
├── celery_beat_config.py  # Celery Beat configuration
├── start_celery.sh        # Script to start Celery components (Linux/Mac)
├── start_celery.bat       # Script to start Celery components (Windows)
├── TASK_SCHEDULING_EVOLUTION.md # Documentation on migration from APScheduler to Celery
├── models/                # Data models
│   ├── __init__.py
│   ├── user.py            # User model
│   ├── social_account.py  # Social media account model
│   ├── source.py          # RSS source model
│   ├── post.py            # Post content model
│   └── schedule.py        # Scheduling model
├── api/                   # API endpoints
│   ├── __init__.py
│   ├── auth.py            # Authentication endpoints
│   ├── sources.py         # Source management endpoints
│   ├── accounts.py        # Social account endpoints
│   ├── posts.py           # Post management endpoints
│   └── schedules.py       # Scheduling endpoints
├── services/              # Business logic
│   ├── __init__.py
│   ├── auth_service.py    # Authentication service
│   ├── linkedin_service.py# LinkedIn integration service
│   ├── content_service.py # Content generation service
│   └── schedule_service.py# Scheduling service
├── celery_tasks/          # Celery tasks
│   ├── __init__.py
│   ├── content_tasks.py   # Content generation and publishing tasks
│   ├── scheduler.py       # Scheduler functions
│   └── schedule_loader.py # Task for loading schedules from database
├── utils/                 # Utility functions
│   ├── __init__.py
│   └── database.py        # Database connection
└── scheduler/             # Task scheduling (deprecated, kept for backward compatibility)
    ├── __init__.py
    └── task_scheduler.py  # Scheduling implementation
```

## API Endpoints

### Authentication
- `POST /api/auth/register` - Register a new user
- `POST /api/auth/login` - Login user
- `POST /api/auth/logout` - Logout user
- `GET /api/auth/user` - Get current user

### Sources
- `GET /api/sources` - Get all sources for current user
- `POST /api/sources` - Add a new source
- `DELETE /api/sources/<id>` - Delete a source

### Accounts
- `GET /api/accounts` - Get all social accounts for current user
- `POST /api/accounts` - Add a new social account
- `POST /api/accounts/callback` - Handle OAuth callback
- `DELETE /api/accounts/<id>` - Delete a social account

### Posts
- `GET /api/posts` - Get all posts for current user
- `POST /api/posts/generate` - Generate AI content
- `POST /api/posts` - Create a new post
- `POST /api/posts/<id>/publish` - Publish a post
- `DELETE /api/posts/<id>` - Delete a post

### Schedules
- `GET /api/schedules` - Get all schedules for current user
- `POST /api/schedules` - Create a new schedule
- `DELETE /api/schedules/<id>` - Delete a schedule

## Setup Instructions

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

2. **Set up environment variables**:
   Copy `.env.example` to `.env` and fill in your values:
   ```bash
   # Windows Command Prompt
   copy .env.example .env
   
   # PowerShell
   Copy-Item .env.example .env
   ```

3. **Start Redis Server**:
   ```bash
   # If you have Redis installed locally
   redis-server
   
   # Or use Docker
   docker run -d -p 6379:6379 redis:alpine
   ```

4. **Start Celery Components**:
   ```bash
   # Start Celery worker
   celery -A celery_app worker --loglevel=info
   
   # Start Celery Beat scheduler (in another terminal)
   celery -A celery_beat_config beat --loglevel=info
   ```

5. **Run the application**:
   ```bash
   python app.py
   ```

## Environment Variables

- `SUPABASE_URL` - Your Supabase project URL
- `SUPABASE_KEY` - Your 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
- `SECRET_KEY` - Flask secret key
- `DEBUG` - Debug mode (True/False)
- `SCHEDULER_ENABLED` - Enable/disable task scheduler (True/False)
- `PORT` - Port to run the application on
- `CELERY_BROKER_URL` - Redis URL for Celery broker (default: redis://localhost:6379/0)
- `CELERY_RESULT_BACKEND` - Redis URL for Celery result backend (default: redis://localhost:6379/0)

## Development

### Running Tests

```bash
pytest
```

### Linting

```bash
flake8 .
```

### Starting Celery Components with Scripts

On Linux/Mac:
```bash
# Start both worker and scheduler
./start_celery.sh all

# Start only worker
./start_celery.sh worker

# Start only scheduler
./start_celery.sh beat
```

On Windows:
```cmd
# Start both worker and scheduler
start_celery.bat all

# Start only worker
start_celery.bat worker

# Start only scheduler
start_celery.bat beat
```

### Windows-Specific Issues

1. **File Copy Commands**
   - Use `copy` command in Command Prompt or `Copy-Item` in PowerShell
   - Avoid using Unix-style `cp` command which doesn't work on Windows

2. **Python Installation Issues**
   - Ensure Python is added to your system PATH
   - Try using `python` instead of `python3` if you have Python 3.x installed
   - If `pip` fails, try `python -m pip install -r requirements.txt`

3. **Permission Issues**
   - If you encounter permission errors, try running your terminal as Administrator
   - Or check file permissions on the project directory

4. **Port Conflicts**
   - Windows might have other services using port 5000
   - Use `netstat -ano | findstr :5000` to check what's using port 5000
   - Change port in configuration if needed

5. **Virtual Environment Issues**
   - If using virtual environments, ensure they're activated properly
   - On Windows, use `venv\Scripts\activate` for Command Prompt
   - Or `venv\Scripts\Activate.ps1` for PowerShell

6. **Environment Variables**
   - Use `set` command in Command Prompt to set environment variables
   - Use `$env:VARIABLE_NAME="value"` in PowerShell
   - Or use the Windows GUI (System Properties > Environment Variables)

## Deployment

The application can be deployed to any platform that supports Python applications:

1. **Heroku**:
   - Create a new Heroku app
   - Set environment variables in Heroku config
   - Deploy using Git
   - Add Redis add-on for Celery

2. **Docker**:
   ```bash
   # The docker-compose.yml file includes Redis
   docker-compose up
   ```

3. **Traditional Server**:
   - Install Python dependencies
   - Set environment variables
   - Install and start Redis
   - Start Celery components
   - Run with a WSGI server like Gunicorn

## Task Scheduling with Celery

The application now uses Celery for task scheduling instead of APScheduler. This provides better scalability and reliability:

1. **Content Generation Tasks**: Generate AI content for scheduled posts
2. **Post Publishing Tasks**: Publish posts to LinkedIn
3. **Schedule Loader Task**: Periodically loads schedules from the database

Tasks are stored in Redis and can be processed by multiple workers, making the system more robust and scalable.

For more details on the migration from APScheduler to Celery, see `TASK_SCHEDULING_EVOLUTION.md`.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a pull request

## License

This project is licensed under the MIT License.