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
Routing	react-router-dom 7	Routes: `/`, `/history`, `/settings`, `/login`
Auth	Firebase 12	Google sign-in only
Styling	Plain CSS	`src/index.css` (globals), `src/App.css` (components)
Backend	Planned Python/FastAPI	Modular: one file per page/function
Database	Planned MongoDB	To be set up after responsive UI

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 page and its functions. Each app page (write, history, settings, auth) has its own backend module; avoid one monolithic API file.
Database: MongoDB. Setup comes after frontend responsive work.

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/
  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)
  lib/                      # firebase.ts, firestoreService.ts

Last updated from session context and codebase review.

3.4 KiB Raw Blame History