# Backend Structure

The backend has been modularized for better maintainability and scalability.

## Directory Structure

```
backend/
├── app.py                      # Main Flask application entry point
├── config.py                   # Configuration management
├── database.py                 # Database connection and initialization
├── requirements.txt            # Python dependencies
├── .env                        # Environment variables
│
├── routes/                     # API route handlers (blueprints)
│   ├── __init__.py
│   ├── subscription_routes.py # /api/subscribe, /api/unsubscribe
│   ├── news_routes.py          # /api/news, /api/stats
│   ├── rss_routes.py           # /api/rss-feeds (CRUD operations)
│   ├── ollama_routes.py        # /api/ollama/* (AI features)
│   ├── tracking_routes.py      # /api/track/* (email tracking)
│   └── analytics_routes.py     # /api/analytics/* (engagement metrics)
│
└── services/                   # Business logic layer
    ├── __init__.py
    ├── news_service.py         # News fetching and storage logic
    ├── email_service.py        # Newsletter email sending
    ├── ollama_service.py       # Ollama AI integration
    ├── tracking_service.py     # Email tracking (opens/clicks)
    └── analytics_service.py    # Engagement analytics
```

## Key Components

### app.py
- Main Flask application
- Registers all blueprints
- Minimal code, just wiring things together

### config.py
- Centralized configuration
- Loads environment variables
- Single source of truth for all settings

### database.py
- MongoDB connection setup
- Collection definitions
- Database initialization with indexes

### routes/
Each route file is a Flask Blueprint handling specific API endpoints:
- **subscription_routes.py**: User subscription management
- **news_routes.py**: News fetching and statistics
- **rss_routes.py**: RSS feed management (add/remove/list/toggle)
- **ollama_routes.py**: AI/Ollama integration endpoints
- **tracking_routes.py**: Email tracking (pixel, click redirects, data deletion)
- **analytics_routes.py**: Engagement analytics (open rates, click rates, subscriber activity)

### services/
Business logic separated from route handlers:
- **news_service.py**: Fetches news from RSS feeds, saves to database
- **email_service.py**: Sends newsletter emails to subscribers
- **ollama_service.py**: Communicates with Ollama AI server
- **tracking_service.py**: Email tracking logic (tracking IDs, pixel generation, click logging)
- **analytics_service.py**: Analytics calculations (open rates, click rates, activity classification)

## Benefits of This Structure

1. **Separation of Concerns**: Routes handle HTTP, services handle business logic
2. **Testability**: Each module can be tested independently
3. **Maintainability**: Easy to find and modify specific functionality
4. **Scalability**: Easy to add new routes or services
5. **Reusability**: Services can be used by multiple routes

## Adding New Features

### To add a new API endpoint:
1. Create a new route file in `routes/` or add to existing one
2. Create a Blueprint and define routes
3. Register the blueprint in `app.py`

### To add new business logic:
1. Create a new service file in `services/`
2. Import and use in your route handlers

### Example:
```python
# services/my_service.py
def my_business_logic():
    return "Hello"

# routes/my_routes.py
from flask import Blueprint
from services.my_service import my_business_logic

my_bp = Blueprint('my', __name__)

@my_bp.route('/api/my-endpoint')
def my_endpoint():
    result = my_business_logic()
    return {'message': result}

# app.py
from routes.my_routes import my_bp
app.register_blueprint(my_bp)
```