Munich-news/docs/QUICK_REFERENCE.md

Quick Reference Guide

Starting the Application

1. Start MongoDB

docker-compose up -d

2. Start Backend (Port 5001)

cd backend
source venv/bin/activate  # or: venv\Scripts\activate on Windows
python app.py

3. Start Frontend (Port 3000)

cd frontend
npm start

4. Run Crawler (Optional)

cd news_crawler
pip install -r requirements.txt
python crawler_service.py 10

Common Commands

RSS Feed Management

List all feeds:

curl http://localhost:5001/api/rss-feeds

Add a feed:

curl -X POST http://localhost:5001/api/rss-feeds \
  -H "Content-Type: application/json" \
  -d '{"name": "Feed Name", "url": "https://example.com/rss"}'

Remove a feed:

curl -X DELETE http://localhost:5001/api/rss-feeds/<feed_id>

Toggle feed status:

curl -X PATCH http://localhost:5001/api/rss-feeds/<feed_id>/toggle

News & Subscriptions

Get latest news:

curl http://localhost:5001/api/news

Subscribe:

curl -X POST http://localhost:5001/api/subscribe \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Get stats:

curl http://localhost:5001/api/stats

Ollama (AI)

Test connection:

curl http://localhost:5001/api/ollama/ping

List models:

curl http://localhost:5001/api/ollama/models

Email Tracking & Analytics

Get newsletter metrics:

curl http://localhost:5001/api/analytics/newsletter/<newsletter_id>

Get article performance:

curl http://localhost:5001/api/analytics/article/<article_id>

Get subscriber activity:

curl http://localhost:5001/api/analytics/subscriber/<email>

Delete subscriber tracking data:

curl -X DELETE http://localhost:5001/api/tracking/subscriber/<email>

Anonymize old tracking data:

curl -X POST http://localhost:5001/api/tracking/anonymize

Database

Connect to MongoDB:

mongosh
use munich_news

Check articles:

db.articles.find().limit(5)
db.articles.countDocuments()
db.articles.countDocuments({full_content: {$exists: true}})

Check subscribers:

db.subscribers.find()
db.subscribers.countDocuments({status: "active"})

Check RSS feeds:

db.rss_feeds.find()

Check tracking data:

db.newsletter_sends.find().limit(5)
db.link_clicks.find().limit(5)
db.subscriber_activity.find()

File Locations

Configuration

• Backend: backend/.env
• Frontend: frontend/package.json
• Crawler: Uses backend's .env or own .env

Logs

• Backend: Terminal output
• Frontend: Terminal output
• Crawler: Terminal output

Database

• MongoDB data: Docker volume mongodb_data
• Database name: munich_news

Ports

Service	Port	URL
Frontend	3000	http://localhost:3000
Backend	5001	http://localhost:5001
MongoDB	27017	mongodb://localhost:27017
Ollama	11434	http://localhost:11434

Troubleshooting

Backend won't start

• Check if port 5001 is available
• Verify MongoDB is running
• Check .env file exists

Frontend can't connect

• Verify backend is running on port 5001
• Check CORS settings
• Check API_URL in frontend

Crawler fails

• Install dependencies: pip install -r requirements.txt
• Check MongoDB connection
• Verify RSS feeds exist in database

MongoDB connection error

• Start MongoDB: docker-compose up -d
• Check connection string in .env
• Verify port 27017 is not blocked

Port 5000 conflict (macOS)

• AirPlay uses port 5000
• Use port 5001 instead (set in .env)
• Or disable AirPlay Receiver in System Preferences

Project Structure

munich-news/
├── backend/          # Main API (Flask)
├── frontend/         # Web UI (Express + JS)
├── news_crawler/     # Crawler microservice
├── .env             # Environment variables
└── docker-compose.yml  # MongoDB setup

Environment Variables

Backend (.env)

MONGODB_URI=mongodb://localhost:27017/
FLASK_PORT=5001
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-password
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=phi3:latest
OLLAMA_ENABLED=true
TRACKING_ENABLED=true
TRACKING_API_URL=http://localhost:5001
TRACKING_DATA_RETENTION_DAYS=90

Development Workflow

1. Add RSS Feed → Backend API
2. Run Crawler → Fetches full content
3. View News → Frontend displays articles
4. Users Subscribe → Via frontend form
5. Send Newsletter → Manual or scheduled

Useful Links

• Frontend: http://localhost:3000
• Backend API: http://localhost:5001
• MongoDB: mongodb://localhost:27017
• Architecture: See ARCHITECTURE.md
• Backend Structure: See backend/STRUCTURE.md
• Crawler Guide: See news_crawler/README.md