# 🚀 LocateTheNews Startup Guide

## Quick Start

### Backend (FastAPI)

#### macOS/Linux:
```bash
cd backend
./start.sh
```

or manually:
```bash
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m spacy download en_core_web_sm
python -m app.main
```

#### Windows:
```bash
cd backend
start.bat
```

or manually:
```bash
cd backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
python -m spacy download en_core_web_sm
python -m app.main
```

Backend will be running at **http://localhost:8000**.

API Documentation: **http://localhost:8000/api/docs**

---

### Frontend (React)

Open a new terminal:

```bash
cd frontend
npm install
npm start
```

Frontend will automatically open at **http://localhost:3000**.

---

## Step-by-Step Detailed Setup

### 1. Backend Setup

#### Requirements:
- Python 3.8+
- pip

#### Steps:

1. **Go to backend directory:**
   ```bash
   cd backend
   ```

2. **Create virtual environment:**
   ```bash
   python3 -m venv venv
   # Windows: python -m venv venv
   ```

3. **Activate virtual environment:**
   ```bash
   source venv/bin/activate
   # Windows: venv\Scripts\activate
   ```

4. **Install packages:**
   ```bash
   pip install -r requirements.txt
   ```

5. **Download spaCy model (for NLP):**
   ```bash
   python -m spacy download en_core_web_sm
   ```
   
   For Turkish (optional):
   ```bash
   python -m spacy download tr_core_news_sm
   ```

6. **Start Backend:**
   ```bash
   python -m app.main
   ```

   Or with uvicorn:
   ```bash
   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
   ```

✅ If the backend is running successfully, you will see:
```
INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete.
```

---

### 2. Frontend Setup

#### Requirements:
- Node.js 16+
- npm or yarn

#### Steps:

1. **Go to frontend directory:**
   ```bash
   cd frontend
   ```

2. **Install packages:**
   ```bash
   npm install
   ```

3. **Start Frontend:**
   ```bash
   npm start
   ```

✅ If the frontend is running successfully, your browser will open automatically:
```
Compiled successfully!
You can now view locatethenews-frontend in the browser.
  Local:            http://localhost:3000
```

---

## Testing

### Backend Test:
1. Open in browser: http://localhost:8000/api/docs
2. You can test endpoints in Swagger UI
3. Health check: http://localhost:8000/api/v1/health
4. Events: http://localhost:8000/api/v1/events

### Frontend Test:
1. Open in browser: http://localhost:3000
2. You should see news markers on the map
3. Click on markers to see news details

---

## Troubleshooting

### Backend issues:

**Import error:**
```bash
# Check if virtual environment is active
which python  # macOS/Linux
where python  # Windows
# Should point to venv/bin/python or venv\Scripts\python
```

**spaCy model error:**
```bash
python -m spacy download en_core_web_sm
```

**Port already in use:**
```bash
# Find and kill the process using port 8000
lsof -ti:8000 | xargs kill  # macOS/Linux
# or change SERVER_PORT in config.py
```

### Frontend issues:

**npm install error:**
```bash
# Check Node.js version
node --version  # should be 16+

# Clean npm cache
npm cache clean --force
npm install
```

**Port 3000 in use:**
```bash
# Use a different port
PORT=3001 npm start
```

**Backend connection error:**
- Ensure backend is running (http://localhost:8000/api/v1/health)
- Check CORS settings (backend/app/config.py)

---

## Production Build

### Frontend Build:
```bash
cd frontend
npm run build
# Static files will be generated in build/ folder
```

### Backend Production:
```bash
# With Gunicorn (recommended)
pip install gunicorn
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
```

---

## Running with Docker (Future)

```bash
docker-compose up
```

---

## Help

If you encounter issues:
1. Check terminal outputs
2. Review log files
3. Ensure ports are open
4. Verify that the virtual environment is active