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 (Google sign-in only)
    api.ts                    # API client for backend calls

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)
✅ Firebase Google Auth kept (Firestore completely removed) ✅ MongoDB as single source of truth

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

5.1 KiB Raw Blame History