Munich-news/PROJECT_STRUCTURE.md

Project Structure

munich-news/
├── backend/                    # Backend API and services
│   ├── routes/                # API routes
│   ├── services/              # Business logic
│   ├── .env.example           # Environment template
│   ├── app.py                 # Flask application
│   ├── config.py              # Configuration
│   └── database.py            # MongoDB connection
│
├── news_crawler/              # News crawler service
│   ├── Dockerfile             # Crawler container
│   ├── crawler_service.py     # Main crawler logic
│   ├── scheduled_crawler.py   # Scheduler (6 AM)
│   ├── rss_utils.py           # RSS parsing utilities
│   └── requirements.txt       # Python dependencies
│
├── news_sender/               # Newsletter sender service
│   ├── Dockerfile             # Sender container
│   ├── sender_service.py      # Main sender logic
│   ├── scheduled_sender.py    # Scheduler (7 AM)
│   ├── tracking_integration.py # Email tracking
│   ├── newsletter_template.html # Email template
│   └── requirements.txt       # Python dependencies
│
├── frontend/                  # React dashboard (optional)
│   ├── src/                   # React components
│   ├── public/                # Static files
│   └── package.json           # Node dependencies
│
├── tests/                     # All test files
│   ├── crawler/               # Crawler tests
│   ├── sender/                # Sender tests
│   └── backend/               # Backend tests
│
├── docs/                      # Documentation
│   ├── ARCHITECTURE.md        # System architecture
│   ├── DEPLOYMENT.md          # Deployment guide
│   ├── API.md                 # API reference
│   ├── DATABASE_SCHEMA.md     # Database structure
│   ├── BACKEND_STRUCTURE.md   # Backend organization
│   ├── CRAWLER_HOW_IT_WORKS.md # Crawler internals
│   ├── EXTRACTION_STRATEGIES.md # Content extraction
│   └── RSS_URL_EXTRACTION.md  # RSS parsing
│
├── .kiro/                     # Kiro IDE configuration
│   └── specs/                 # Feature specifications
│
├── docker-compose.yml         # Docker orchestration
├── README.md                  # Main documentation
├── QUICKSTART.md              # 5-minute setup guide
├── CONTRIBUTING.md            # Contribution guidelines
├── .gitignore                 # Git ignore rules
└── .dockerignore              # Docker ignore rules

Key Files

Configuration

• backend/.env - Environment variables (create from .env.example)
• docker-compose.yml - Docker services configuration

Entry Points

• news_crawler/scheduled_crawler.py - Crawler scheduler (6 AM)
• news_sender/scheduled_sender.py - Sender scheduler (7 AM)
• backend/app.py - Backend API server

Documentation

• README.md - Main project documentation
• QUICKSTART.md - Quick setup guide
• docs/ - Detailed documentation

Tests

• tests/crawler/ - Crawler test files
• tests/sender/ - Sender test files
• tests/backend/ - Backend test files

Docker Services

When you run docker-compose up -d, these services start:

1. mongodb - Database (port 27017)
2. crawler - News crawler (scheduled for 6 AM)
3. sender - Newsletter sender (scheduled for 7 AM)
4. backend - API server (port 5001, optional)

Data Flow

RSS Feeds → Crawler → MongoDB → Sender → Subscribers
                        ↓
                   Backend API
                        ↓
                   Analytics

Development Workflow

1. Edit code in respective directories
2. Rebuild containers: docker-compose up -d --build
3. View logs: docker-compose logs -f
4. Run tests: docker-compose exec <service> python tests/...

Adding New Features

1. Create spec in .kiro/specs/
2. Implement in appropriate directory
3. Add tests in tests/
4. Update documentation in docs/
5. Submit pull request

Clean Architecture

• Separation of Concerns: Each service has its own directory
• Centralized Configuration: All config in backend/.env
• Organized Tests: All tests in tests/ directory
• Clear Documentation: All docs in docs/ directory
• Single Entry Point: One docker-compose.yml file

This structure makes the project:

• ✅ Easy to navigate
• ✅ Simple to deploy
• ✅ Clear to understand
• ✅ Maintainable long-term