Project Context for AI Agents

This file contains critical rules and patterns that AI agents must follow when implementing code in this project. Focus on unobvious details that agents might otherwise miss.

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 (when implemented)

Framework: FastAPI. APIs in Python only.
Modularity: Separate file per route. Each feature (users, entries) has its own router module.
Database: MongoDB. Setup instructions below.
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

Last updated: 2026-03-04

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

Frontend-Backend Integration (Completed)

✅ API Service Layer — Created src/lib/api.ts with all backend calls ✅ AuthContext Updated — Now syncs users with MongoDB on login

Auto-registers new users in MongoDB
Fetches existing user profiles
Provides userId (MongoDB ID) to all pages ✅ HomePage — Entry creation via POST /api/entries/{userId}
Save with success/error feedback
Clears form after save ✅ HistoryPage — Fetches entries via GET /api/entries/{userId}
Calendar shows days with entries
Lists recent entries with timestamps
Filters by current month ✅ SettingsPage — Updates user settings via PUT /api/users/update/{userId}
Theme selector (light/dark) with MongoDB persistence
Profile info from Firebase

Next Steps (Implementation)

🔄 Add entry detail view / edit functionality
🔄 Firebase token verification in backend middleware
🔄 Search/filter entries by date range
🔄 Client-side encryption for entries

6.0 KiB Raw Blame History