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)

# 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

# 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

cd backend

2. Create Python virtual environment

python3 -m venv venv

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

3. Install dependencies

pip install -r requirements.txt

4. Configure environment (optional)

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

5. Start the API server

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

brew services start mongodb-community
mongosh  # Verify connection

Terminal 2: Start Frontend

npm run dev -- --port 8000

Terminal 3: Start Backend

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 — Full MongoDB installation & configuration
• backend/README.md — Backend architecture & endpoints
• project-context.md — Implementation rules & conventions