ai-news-aggregator Cursor Rules

# Cursor Rules for news-aggregator Project

## Project Structure

- **Modular Django Project:** The project adopts a modular architecture, segregating functionalities into distinct Django apps to enhance maintainability and scalability.

  - **`feed_service`:**
    - **Purpose:** Manages all aspects related to RSS feeds.
    - **Responsibilities:**
      - Fetching and parsing RSS feeds.
      - Storing feed data and associated entries.
      - Handling user subscriptions to various feeds.
    - **Models:**
      - `Feed`: Represents an RSS feed source.
      - `FeedEntry`: Represents individual news entries from feeds.
      - `UserFeedSubscription`: Manages the relationship between users and their subscribed feeds.
      - `UserArticleInteraction`: Stores AI-generated content and user-specific data for each article.

  - **`dashboard`:**
    - **Purpose:** Serves as the user interface layer of the application.
    - **Responsibilities:**
      - Displaying subscribed feeds and available feeds for subscription.
      - Presenting aggregated news entries to users based on their subscriptions.
      - Managing user interactions such as subscribing/unsubscribing to feeds.
    - **Views:**
      - `feed_list`: Lists all subscribed and available feeds.
      - `feed_detail`: Shows details of a specific feed and its entries.
      - `subscribe_feed` & `unsubscribe_feed`: Handle subscription actions.
      - `home`: Consolidates news entries from all subscribed feeds.

  - **`users`:**
    - **Purpose:** Handles user authentication and profile management.
    - **Responsibilities:**
      - Managing user registration, login, and logout processes.
      - Extending Django's built-in user model to include additional user-related information.
      - Integrating with `django-allauth` for enhanced authentication features.

  - **`contrib`:**
    - **Purpose:** Contains supplementary components and custom integrations.
    - **Responsibilities:**
      - Managing migrations related to Django's `sites` framework.
      - Including any additional utility modules or packages that support the main apps.

  - **`management/commands`:**
    - **Purpose:** Houses custom Django management commands.
    - **Responsibilities:**
      - Automating tasks such as updating feeds and processing news entries.
      - Providing commands for maintenance and data management.

- **Core Configurations:**
  - **Settings:**
    - Separated into multiple modules (`base`, `local`, `production`) to cater to different environments and deployment stages.
  - **Templates:**
    - Organized under each app with a base template (`base.html`) extended by other templates for consistency.
  - **Static Files:**
    - Managed centrally with directories for CSS, JavaScript, and fonts to ensure uniform styling and functionality across the application.
  - **Middleware:**
    - Configured to include essential middleware for security, session management, and debugging tools like `django-debug-toolbar` during development.

- **Utilities and Integrations:**
  - **Celery:**
    - Integrated for handling asynchronous tasks such as fetching and processing feeds.
  - **Sentry:**
    - Incorporated for error tracking and monitoring.
  - **Pre-commit Hooks:**
    - Set up to enforce code quality standards and perform automated linting and formatting.

- **AI Models:**
  - We use `gpt-4o` for AI processing.

## Code Style & Patterns

- Models use descriptive names and include helpful docstrings
- Model fields include appropriate help_text for clarity
- Use of `related_name` in ForeignKey fields for reverse lookups
- Consistent ordering in model Meta classes
- Descriptive `__str__` methods for all models
- Ruff is used for linting and formatting
- Follows Django best practices where appropriate
- In templates, `endblock` should always have a name

## View Patterns

- All dashboard views require authentication (`@login_required`)
- POST-only actions use `HttpResponseNotAllowed` for safety
- Views use `get_object_or_404` for clean 404 handling
- `prefetch_related` used for optimizing queries with related data
- Redirect after successful POST actions

## Template Patterns

- Templates extend `base.html`
- Bootstrap classes used for styling
- Consistent use of semantic HTML5 elements
- Forms use POST method with CSRF protection
- Empty states handled with `{% empty %}` blocks
- Slice filter used for limiting related items (`|slice:":3"`)

## Data Access Rules

- Users can only access their subscribed feeds
- Feed subscriptions are soft-deleted (`is_active=False`)
- Feeds themselves are user-agnostic
- Feed entries are always tied to a feed

## Performance Patterns

- Use `prefetch_related` for optimizing queries
- Limit related items in templates (`slice:":3"`)
- Soft deletes instead of hard deletes
- Indexes on frequently queried fields