# Quick Reference Guide

## Starting the Application

### 1. Start MongoDB
```bash
docker-compose up -d
```

### 2. Start Backend (Port 5001)
```bash
cd backend
source venv/bin/activate  # or: venv\Scripts\activate on Windows
python app.py
```

### 3. Start Frontend (Port 3000)
```bash
cd frontend
npm start
```

### 4. Run Crawler (Optional)
```bash
cd news_crawler
pip install -r requirements.txt
python crawler_service.py 10
```

## Common Commands

### RSS Feed Management

**List all feeds:**
```bash
curl http://localhost:5001/api/rss-feeds
```

**Add a feed:**
```bash
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:**
```bash
curl -X DELETE http://localhost:5001/api/rss-feeds/<feed_id>
```

**Toggle feed status:**
```bash
curl -X PATCH http://localhost:5001/api/rss-feeds/<feed_id>/toggle
```

### News & Subscriptions

**Get latest news:**
```bash
curl http://localhost:5001/api/news
```

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

**Get stats:**
```bash
curl http://localhost:5001/api/stats
```

### Ollama (AI)

**Test connection:**
```bash
curl http://localhost:5001/api/ollama/ping
```

**List models:**
```bash
curl http://localhost:5001/api/ollama/models
```

### Email Tracking & Analytics

**Get newsletter metrics:**
```bash
curl http://localhost:5001/api/analytics/newsletter/<newsletter_id>
```

**Get article performance:**
```bash
curl http://localhost:5001/api/analytics/article/<article_id>
```

**Get subscriber activity:**
```bash
curl http://localhost:5001/api/analytics/subscriber/<email>
```

**Delete subscriber tracking data:**
```bash
curl -X DELETE http://localhost:5001/api/tracking/subscriber/<email>
```

**Anonymize old tracking data:**
```bash
curl -X POST http://localhost:5001/api/tracking/anonymize
```

### Database

**Connect to MongoDB:**
```bash
mongosh
use munich_news
```

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

**Check subscribers:**
```javascript
db.subscribers.find()
db.subscribers.countDocuments({status: "active"})
```

**Check RSS feeds:**
```javascript
db.rss_feeds.find()
```

**Check tracking data:**
```javascript
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)
```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`