KindnessBot Cursor Rules

# Cursor Rules for AI-Powered Bot
project: flask-ai-keyword-bot

description: >
  An AI-powered bot that scans for specific keywords/hashtags on X (formerly Twitter), defined by an admin. It follows admin-defined guidelines to comment on relevant posts.
  The bot runs on a user-defined schedule for a limited time and can also be manually triggered.

principles:
  - Write concise, accurate, friendly responses.
  - Use functional programming wherever possible; use classes only for Flask views.
  - Prefer iteration and modularization over duplication.
  - Use descriptive, snake_case variable names.
  - Structure project into logical modules: app initialization, blueprints, models, utilities, and config.

guidelines:
  python:
    - Use `def` for function definitions with type hints for all parameters and return types.
    - Adopt the Receive an Object, Return an Object (RORO) pattern.
    - Handle errors and edge cases early; favor `if-return` patterns over deeply nested logic.
    - Use Flask Blueprints to organize application routes.
    - Avoid unnecessary curly braces in single-line conditional statements.
    - Implement error handling and logging with user-friendly messages.
    - Include custom error handlers for consistent error responses.
    - Use environment variables for sensitive data and configuration.
    - Include API documentation using Flask-RESTX or Flasgger for OpenAPI compliance.

  flask:
    - Use Flask's application factory pattern for modularity.
    - Organize functionality into Blueprints and extension-specific modules.
    - Use Flask-RESTful for RESTful APIs and Marshmallow for validation/serialization.
    - Apply Flask-JWT-Extended for secure authentication.
    - Optimize performance with Flask-Caching and database query tuning.

  database:
    - Use Flask-SQLAlchemy for ORM with proper session management.
    - Define Marshmallow schemas for models to handle validation and serialization.
    - Implement database migrations using Flask-Migrate.

  performance:
    - Use Celery or RQ for background tasks.
    - Cache frequent queries with Flask-Caching.
    - Optimize database queries and manage sessions efficiently.
    - Log application performance metrics (latency, throughput).

  testing:
    - Write unit tests with pytest and integration tests using Flask's test client.
    - Mock external API calls and interactions with X for predictable results.
    - Create test fixtures for database and application setup.

  deployment:
  - Use Docker for containerization.
  - Deploy with a WSGI HTTP server (Gunicorn) behind an Nginx reverse proxy.
  - Configure logging and monitoring with tools like Sentry or Prometheus.

note:
  Refer to Flask documentation and API-specific libraries for integration with X's API. Use Python's `schedule` library or Celery to manage the bot's run schedule.
  Admin builds on local machine so after every edit suggestion, always provide me the push to Github command, followed by the pull command for droplet