Munich-news/backend/STRUCTURE.md

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)
│
└── 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

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

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

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:

# 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)