# Grateful Journal — Project Instructions for Copilot

## Project Overview

**Grateful Journal** — A minimal, private-first gratitude journaling web app. Three main pages (Write, History/calendar, Settings/profile) plus Google auth. No feeds or algorithms; privacy by design with client-side encryption; daily use, even one sentence.

**User:** Jeet

---

## Technology Stack & Versions

| Layer    | Technology           | Notes                                                 |
| -------- | -------------------- | ----------------------------------------------------- |
| Frontend | React 19, TypeScript | Vite 7 build; port 8000                               |
| Routing  | react-router-dom 7   | Routes: `/`, `/history`, `/settings`, `/login`        |
| Auth     | Firebase 12          | Google sign-in only (no database)                     |
| Styling  | Plain CSS            | `src/index.css` (globals), `src/App.css` (components) |
| Backend  | FastAPI 0.104        | Python; port 8001; modular routes                     |
| Database | MongoDB 6.x          | Local instance; collections: users, entries, settings |

---

## Critical Implementation Rules

### Frontend

- **Colour palette (Coolors):** Use CSS variables from `src/index.css`. Primary green `#1be62c`, background soft `#f1eee1`, surface `#ffffff`, accent light `#cff2dc`, accent bright `#c3fd2f`. Do not introduce new palette colours without reason.
- **Layout:** Responsive for all screens. Breakpoints: `--bp-sm` 480px, `--bp-md` 768px, `--bp-lg` 1024px, `--bp-xl` 1280px. On laptop (1024px+), page is single-screen 100vh — no vertical scroll; fonts and spacing scaled so content fits one viewport.
- **Touch targets:** Minimum 44px (`--touch-min`) on interactive elements for small screens.
- **Safe areas:** Use `env(safe-area-inset-*)` for padding where the app can sit under notches or system UI. Viewport meta includes `viewport-fit=cover`.
- **Structure:** Main app layout: page container → header + main content + fixed `BottomNav`. Content max-width `min(680px, 100%)` (or `--content-max` 720px where appropriate).

### Backend

- **Framework:** FastAPI. APIs in Python only.
- **Modularity:** Separate file per route. Each feature (users, entries) has its own router module.
- **Database:** MongoDB. Setup instructions in `docs/MONGODB_SETUP.md`.
- **Port:** 8001 (backend); 8000 (frontend). CORS configured between them.
- **Authentication:** Relies on Firebase Google Auth token from frontend (passed in Authorization header).

### Conventions

- **Fonts:** Inter for UI, Playfair Display for headings/editorial, Lora for body/entry text. Loaded via Google Fonts in `index.html`.
- **Naming:** CSS uses BEM-like class names (e.g. `.journal-card`, `.journal-prompt`). Keep the same pattern for new components.
- **Build:** Fixing the current TypeScript/ESLint build errors is deferred to a later step; do not assume a clean build when adding features.

---

## File Layout (Reference)

```
src/                          # Frontend
  App.tsx, App.css            # Root layout, routes, global page styles
  index.css                   # Resets, :root vars, base typography
  main.tsx
  pages/                      # HomePage, HistoryPage, SettingsPage, LoginPage
  components/                 # BottomNav, LoginCard, GoogleSignInButton, ProtectedRoute
  contexts/                   # AuthContext (Firebase Google Auth)
  lib/
    firebase.ts               # Firebase auth config (Firestore removed)

backend/                      # FastAPI backend (Port 8001)
  main.py                     # FastAPI app, CORS, routes, lifespan
  config.py                   # Settings, environment variables
  db.py                       # MongoDB connection manager
  models.py                   # Pydantic models (User, JournalEntry, Settings)
  requirements.txt            # Python dependencies
  .env.example                # Environment variables template
  routers/
    users.py                  # User registration, update, delete endpoints
    entries.py                # Entry CRUD, date filtering endpoints
```

---

## Recent Changes & Status

### Port Configuration (Updated)

✅ Frontend port changed to **8000** (was 5173)  
✅ Backend port remains **8001**  
✅ CORS configuration updated in FastAPI  
✅ Vite config updated with server port 8000

### Backend Setup (Completed)

✅ FastAPI backend initialized (port 8001)  
✅ MongoDB connection configured (local instance)  
✅ Pydantic models for User, JournalEntry, UserSettings  
✅ Route structure: `/api/users/*` and `/api/entries/*`  
✅ CORS enabled for frontend (localhost:8000)  
✅ Firestore database files removed (`firestoreService.ts`, `firestoreConfig.ts`)  
✅ Firebase authentication kept (Google sign-in only)

### API Ready

- User registration, profile updates, deletion
- Entry CRUD (create, read, update, delete)
- Entry filtering by date
- Pagination support

### Next Steps (Implementation)

🔄 Connect frontend React app to backend APIs  
🔄 Pass Firebase user ID from frontend to backend  
🔄 Integrate Auth context with entry save/load  
🔄 Add optional: Firebase token verification in backend middleware

---

_Last updated: 2026-03-04_