update

docs/QUICK_REFERENCE.md

@@ -0,0 +1,243 @@
+# 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`