cs_betty/app
1
0
Fork 0
forked from cartsnitch/app
Code Pull Requests Activity

docs: update CLAUDE.md for standalone frontend repo

Browse Source
This commit is contained in:
Test User
2026-04-19 12:39:12 +00:00
parent 92ab66d737
commit 7ae6382f8b
1 changed files with 37 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+37 -21
View File
@@ -1,26 +1,21 @@
# CartSnitch Monorepo # CartSnitch Frontend
## Project Context ## Project Context
CartSnitch is a self-hosted grocery price intelligence platform. This repo (`cartsnitch/cartsnitch`) is the **monorepo** containing the flagship frontend PWA and core backend services. CartSnitch is a self-hosted grocery price intelligence platform. This repo (`cartsnitch/app`) is the **standalone frontend PWA** — a mobile-first React application.
**GitHub org:** github.com/cartsnitch **GitHub org:** github.com/cartsnitch
**Domain:** cartsnitch.com **Domain:** cartsnitch.com
### Monorepo Layout ### CartSnitch Repos
| Directory | Service | Purpose |
|-----------|---------|---------|
| `/` (root) | Frontend | React PWA, mobile-first (this directory) |
| `auth/` | Auth | Better-Auth Node.js service (session management, email/password, OAuth) |
| `api/` | API Gateway | Frontend-facing REST API |
| `common/` | Common | Shared Python models, schemas, Alembic migrations |
| `receiptwitness/` | ReceiptWitness | Purchase data ingestion via retailer scrapers |
### Other CartSnitch Repos (still separate)
| Repo | Service | Purpose | | Repo | Service | Purpose |
|------|---------|---------| |------|---------|---------|
| `cartsnitch/app` | Frontend | React PWA, mobile-first (this repo) |
| `cartsnitch/auth` | Auth | Better-Auth Node.js service (session management, email/password, OAuth) |
| `cartsnitch/api` | API Gateway | Frontend-facing REST API |
| `cartsnitch/common` | Common | Shared Python models, schemas, Alembic migrations |
| `cartsnitch/receiptwitness` | ReceiptWitness | Purchase data ingestion via retailer scrapers |
| `cartsnitch/stickershock` | StickerShock | Price increase detection & CPI comparison | | `cartsnitch/stickershock` | StickerShock | Price increase detection & CPI comparison |
| `cartsnitch/shrinkray` | ShrinkRay | Shrinkflation monitoring | | `cartsnitch/shrinkray` | ShrinkRay | Shrinkflation monitoring |
| `cartsnitch/clipartist` | ClipArtist | Coupon/deal watching & shopping optimization | | `cartsnitch/clipartist` | ClipArtist | Coupon/deal watching & shopping optimization |
@@ -41,20 +36,19 @@ The frontend is a mobile-first PWA that serves as the primary user interface for
## Tech Stack ## Tech Stack
- React 18+ (or Next.js if SSR/SSG is valuable for public pages) - React 18+
- TypeScript - TypeScript
- Tailwind CSS (mobile-first responsive design) - Tailwind CSS (mobile-first responsive design)
- Workbox (service worker, offline caching, PWA manifest) - Workbox (service worker, offline caching, PWA manifest)
- Recharts or Chart.js (price trend visualizations) - Recharts (price trend visualizations)
- TanStack Query (React Query) for data fetching and caching - TanStack Query (React Query) for data fetching and caching
- React Router (client-side routing) - React Router (client-side routing)
- Zustand or Jotai (lightweight state management) - Zustand (state management)
- Vite (build tool) - Vite (build tool)
## Repo Structure ## Repo Structure
``` ```
frontend/
├── CLAUDE.md ├── CLAUDE.md
├── README.md ├── README.md
├── package.json ├── package.json
@@ -63,6 +57,9 @@ frontend/
├── tailwind.config.ts ├── tailwind.config.ts
├── Dockerfile # Multi-stage: build + nginx serve ├── Dockerfile # Multi-stage: build + nginx serve
├── docker-compose.yml # Local dev ├── docker-compose.yml # Local dev
├── .github/
│ └── workflows/
│ └── ci.yml # CI: lint, test, audit, e2e, lighthouse, build-and-push, deploy
├── public/ ├── public/
│ ├── manifest.json # PWA manifest │ ├── manifest.json # PWA manifest
│ ├── sw.js # Service worker (Workbox generated) │ ├── sw.js # Service worker (Workbox generated)
@@ -131,7 +128,7 @@ frontend/
│ │ ├── EmptyState.tsx │ │ ├── EmptyState.tsx
│ │ ├── StoreLogo.tsx │ │ ├── StoreLogo.tsx
│ │ └── ErrorBoundary.tsx │ │ └── ErrorBoundary.tsx
│ ├── stores/ # Zustand/Jotai state stores │ ├── stores/ # Zustand state stores
│ │ ├── authStore.ts │ │ ├── authStore.ts
│ │ └── uiStore.ts │ │ └── uiStore.ts
│ ├── utils/ │ ├── utils/
@@ -144,6 +141,10 @@ frontend/
│ ├── price.ts │ ├── price.ts
│ ├── coupon.ts │ ├── coupon.ts
│ └── alert.ts │ └── alert.ts
├── e2e/
│ └── ...
├── scripts/
│ └── ...
└── tests/ └── tests/
└── ... └── ...
``` ```
@@ -167,7 +168,7 @@ frontend/
All data comes from the CartSnitch API gateway (`cartsnitch/api`). Base URL configured via environment variable `VITE_API_URL`. All data comes from the CartSnitch API gateway (`cartsnitch/api`). Base URL configured via environment variable `VITE_API_URL`.
- **Authentication via Better-Auth** (`auth/` service). Sessions are managed via httpOnly cookies — no tokens in localStorage or memory. - **Authentication via Better-Auth** (`cartsnitch/auth` service). Sessions are managed via httpOnly cookies — no tokens in localStorage or memory.
- Auth service URL configured via `VITE_AUTH_URL` (default: `http://localhost:3001`) - Auth service URL configured via `VITE_AUTH_URL` (default: `http://localhost:3001`)
- Frontend uses `better-auth/react` client for sign-in, sign-up, sign-out, and `useSession()` hook - Frontend uses `better-auth/react` client for sign-in, sign-up, sign-out, and `useSession()` hook
- API gateway validates sessions by querying the shared `sessions` table in Postgres - API gateway validates sessions by querying the shared `sessions` table in Postgres
@@ -184,9 +185,24 @@ All data comes from the CartSnitch API gateway (`cartsnitch/api`). Base URL conf
- `npm run build` for production build - `npm run build` for production build
- Lint with ESLint, format with Prettier - Lint with ESLint, format with Prettier
## CI/CD
This repo uses a GitHub Actions CI pipeline (`.github/workflows/ci.yml`):
- **lint** — ESLint + TypeScript check
- **test** — Vitest
- **audit** — npm audit
- **e2e** — Playwright
- **lighthouse** — Lighthouse CI
- **build-and-push** — builds Docker image, Grype vulnerability scan, pushes to `ghcr.io/cartsnitch/app`
- **deploy-dev** — updates `ghcr.io/cartsnitch/app` image tag in `infra/apps/overlays/dev/kustomization.yaml`
- **deploy-uat** — updates `ghcr.io/cartsnitch/app` image tag in `infra/apps/overlays/uat/kustomization.yaml`
Image tags: CalVer (`YYYY.MM.DD[.N]`) on `main`, `sha-<commit>` on `dev`/`uat`.
## Important Notes ## Important Notes
- The store account connection flow is the most complex UX. Users need to authenticate with each retailer. This likely involves opening a controlled browser window/iframe where they log in, and CartSnitch captures the resulting session. Design this flow carefully — it needs to feel safe and trustworthy. - The store account connection flow is the most complex UX. Users need to authenticate with each retailer. This likely involves opening a controlled browser window/iframe where they log in, and CartSnitch captures the resulting session. Design this flow carefully — it needs to feel safe and trustworthy.
- Public price transparency pages should be SSR-friendly or statically generated for SEO if the "naming and shaming" feature is going to get organic traffic. Consider Next.js for these pages specifically, or a separate lightweight static site. - Public price transparency pages should be SSR-friendly or statically generated for SEO if the "naming and shaming" feature is going to get organic traffic.
- The optimized shopping list is the killer feature for retention. Make it dead simple: add items → see the split → go shop. No friction. - The optimized shopping list is the killer feature for retention. Make it dead simple: add items → see the split → go shop. No friction.
- Push notifications (via service worker) for price alerts and deal notifications are a Phase 2+ feature but design the alert system with this in mind. - Push notifications (via service worker) for price alerts and deal notifications are a Phase 2+ feature but design the alert system with this in mind.