grateful-journal/BACKEND_QUICKSTART.md

# MongoDB & FastAPI Backend Setup - Quick Start

## What's Been Set Up

✅ **Backend directory structure** (`/backend`)  
✅ **FastAPI application** (main.py with routes, CORS, lifecycle)  
✅ **MongoDB connection** (config.py, db.py)  
✅ **Pydantic models** (User, JournalEntry, UserSettings)  
✅ **API routes** (users.py, entries.py)  
✅ **Environment configuration** (.env.example)  
✅ **Documentation** (README.md, MONGODB_SETUP.md)  
✅ **Firebase auth preserved** (Google sign-in, no Firestore)

---

## How to Start MongoDB

### 1. Install MongoDB (if not already installed)

```bash
# macOS
brew tap mongodb/brew
brew install mongodb-community

# Linux (Ubuntu)
curl -fsSL https://www.mongodb.org/static/pgp/server-6.0.asc | sudo apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/6.0 multiverse" \
  | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list
sudo apt-get update
sudo apt-get install -y mongodb-org

# Windows: Download from https://www.mongodb.com/try/download/community
```

### 2. Start MongoDB Service

```bash
# macOS
brew services start mongodb-community

# Linux
sudo systemctl start mongod

# Windows
net start MongoDB

# Verify it's running
mongosh  # Should connect successfully
```

---

## How to Start FastAPI Backend

### 1. Navigate to backend directory

```bash
cd backend
```

### 2. Create Python virtual environment

```bash
python3 -m venv venv

# Activate it
source venv/bin/activate          # macOS/Linux
# or
venv\Scripts\activate             # Windows
```

### 3. Install dependencies

```bash
pip install -r requirements.txt
```

### 4. Configure environment (optional)

```bash
cp .env.example .env
# Edit .env if you need to change defaults
```

### 5. Start the API server

```bash
python main.py
```

You should see:

```
✓ Connected to MongoDB: grateful_journal
INFO:     Uvicorn running on http://0.0.0.0:8001
```

### 6. Access API Documentation

Open in browser:

- **Interactive API Docs**: http://localhost:8001/docs
- **Alternative Docs**: http://localhost:8001/redoc
- **Health Check**: http://localhost:8001/health

---

## Complete Startup (All Services)

### Terminal 1: Start MongoDB

```bash
brew services start mongodb-community
mongosh  # Verify connection
```

### Terminal 2: Start Frontend

```bash
npm run dev -- --port 8000
```

### Terminal 3: Start Backend

```bash
cd backend
source venv/bin/activate
python main.py
```

Now you have:

- **Frontend**: http://localhost:8000
- **Backend**: http://localhost:8001
- **MongoDB**: localhost:27017

---

## API Endpoints Ready to Use

### User Management

- `POST /api/users/register` — Register user after Firebase auth
- `GET /api/users/by-email/{email}` — Fetch user profile
- `PUT /api/users/update/{user_id}` — Update profile
- `DELETE /api/users/{user_id}` — Delete account & data

### Journal Entries

- `POST /api/entries/{user_id}` — Create entry
- `GET /api/entries/{user_id}` — List entries (paginated)
- `GET /api/entries/{user_id}/{entry_id}` — Get entry
- `PUT /api/entries/{user_id}/{entry_id}` — Update entry
- `DELETE /api/entries/{user_id}/{entry_id}` — Delete entry
- `GET /api/entries/{user_id}/date/{YYYY-MM-DD}` — Entries by date

---

## Authentication Flow

1. **Frontend**: User clicks "Sign in with Google"
2. **Firebase**: Returns auth token + user info (email, displayName, photoURL)
3. **Frontend**: Calls `POST /api/users/register` with user data
4. **Backend**: Stores user in MongoDB, returns user ID
5. **Frontend**: Uses user ID for all subsequent API calls

---

## File Structure

```
grateful-journal/
├── backend/                    # NEW: FastAPI backend
│   ├── main.py                 # FastAPI app
│   ├── config.py               # Settings
│   ├── db.py                   # MongoDB connection
│   ├── models.py               # Pydantic models
│   ├── requirements.txt         # Python dependencies
│   ├── .env.example            # Environment template
│   ├── README.md               # Backend docs
│   └── routers/                # API routes
│       ├── users.py
│       └── entries.py
├── src/                        # Frontend (existing)
│   └── lib/
│       └── firebase.ts         # Auth only (Firestore removed)
├── docs/
│   ├── FIRESTORE_SETUP.md      # (old, keep for reference)
│   └── MONGODB_SETUP.md        # NEW: MongoDB setup guide
└── project-context.md          # Updated with backend info
```

---

## Removed Files (Firestore)

- ❌ `src/lib/firestoreService.ts` (removed — use MongoDB API instead)
- ❌ `src/lib/firestoreConfig.ts` (removed — use MongoDB API instead)

---

## Next Steps

1. **Start MongoDB** (see above)
2. **Start FastAPI** (see above)
3. **Connect Frontend to Backend**
    - Update `src/contexts/AuthContext.tsx` to call `/api/users/register`
    - Create hooks to fetch/save entries from `/api/entries/*`
    - Pass Firebase user ID to all API calls

4. **Test in API Docs** (http://localhost:8001/docs)
    - Try creating a user
    - Try creating an entry
    - Try fetching entries

---

## Troubleshooting

**"MongoDB connection refused"**

- Is the service running? `brew services list` (macOS) or `systemctl status mongod` (Linux)
- Check port 27017 is free: `lsof -i :27017`

**"ModuleNotFoundError: pymongo"**

- Is venv activated? Run `. venv/bin/activate` again
- Did you run `pip install -r requirements.txt`?

**"CORS error in browser console"**

- Backend running on 8001? Check `http://localhost:8001/docs`
- Frontend URL in `.env`? Should be `http://localhost:8000`

---

For detailed setup instructions, see:

- [MONGODB_SETUP.md](./docs/MONGODB_SETUP.md) — Full MongoDB installation & configuration
- [backend/README.md](./backend/README.md) — Backend architecture & endpoints
- [project-context.md](./project-context.md) — Implementation rules & conventions