forked from cartsnitch/cartsnitch
release: remove mock auth bypass + README expansion (CAR-813/CAR-829)
release: remove mock auth bypass + README expansion (CAR-813/CAR-829)
This commit is contained in:
savannah-savings-cto[bot]
@@ -1 +1,315 @@
|
||||
# CartSnitch
|
||||
|
||||
**Grocery price intelligence — know what you're paying, every time.**
|
||||
|
||||
CartSnitch is a self-hosted grocery price intelligence platform that connects to your store loyalty accounts, tracks prices across retailers, monitors shrinkflation, and helps you find the best deals.
|
||||
|
||||
---
|
||||
|
||||
## Project Overview
|
||||
|
||||
CartSnitch solves the problem of **grocery price opacity**. Most shoppers don't know if they're getting a good deal, whether prices have spiked since their last visit, or if the "sale" is actually a worse price than a competitor. CartSnitch makes prices transparent.
|
||||
|
||||
**Core features:**
|
||||
- Connect Meijer, Kroger, Target loyalty accounts
|
||||
- View purchase history across all stores in one timeline
|
||||
- Track per-item price charts across stores over time
|
||||
- Receive shrinkflation and price increase alerts
|
||||
- Browse active coupons and deals
|
||||
- Generate optimized shopping lists with store-split plans
|
||||
- Public price transparency dashboards
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
CartSnitch is a polyglot microservices platform. The monorepo contains the frontend PWA and core services.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CartSnitch PWA │
|
||||
│ (React, mobile-first PWA) │
|
||||
└──────────┬────────────────────┬────────────────────┬───────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌──────────────────┐ ┌─────────────────┐ ┌─────────────────────┐
|
||||
│ Auth Service │ │ API Gateway │ │ ReceiptWitness │
|
||||
│ (Better-Auth) │ │ (Python/FastAPI)│ │ (Python/Scrapers) │
|
||||
│ Session mgmt │ │ REST + proxy │ │ Purchase ingestion │
|
||||
└────────┬─────────┘ └────────┬────────┘ └──────────┬──────────┘
|
||||
│ │ │
|
||||
└──────────────────────┼────────────────────────┘
|
||||
▼
|
||||
┌────────────────────────┐
|
||||
│ CloudNativePG (PGSQL) │
|
||||
│ Shared database │
|
||||
└────────────────────────┘
|
||||
```
|
||||
|
||||
### Services in This Repo
|
||||
|
||||
| Directory | Service | Description |
|
||||
|-----------|---------|-------------|
|
||||
| `/` (root) | Frontend | React PWA, mobile-first |
|
||||
| `auth/` | Auth | Better-Auth service — session management, email/password, OAuth |
|
||||
| `api/` | API Gateway | Frontend-facing REST API, Python/FastAPI |
|
||||
| `common/` | Common | Shared Python models, Pydantic schemas, Alembic migrations |
|
||||
| `receiptwitness/` | ReceiptWitness | Purchase data ingestion via retailer scrapers |
|
||||
|
||||
### Other CartSnitch Repos
|
||||
|
||||
| Repo | Service |
|
||||
|------|---------|
|
||||
| `cartsnitch/stickershock` | Price increase detection & CPI comparison |
|
||||
| `cartsnitch/shrinkray` | Shrinkflation monitoring |
|
||||
| `cartsnitch/clipartist` | Coupon/deal watching |
|
||||
| `cartsnitch/infra` | Kubernetes manifests, Flux kustomizations |
|
||||
|
||||
---
|
||||
|
||||
## Tech Stack
|
||||
|
||||
### Frontend
|
||||
- **React 18+** with TypeScript
|
||||
- **Vite** — build tool
|
||||
- **Tailwind CSS v4** — mobile-first responsive design
|
||||
- **Workbox** — service worker, offline caching, PWA manifest
|
||||
- **Recharts** — price trend visualizations
|
||||
- **TanStack Query** — data fetching and caching
|
||||
- **React Router v7** — client-side routing
|
||||
- **Zustand** — lightweight state management
|
||||
|
||||
### Backend Services
|
||||
- **Better-Auth** — authentication (session management, email/password, OAuth)
|
||||
- **Node.js** (API Gateway)
|
||||
- **Python/FastAPI** (API Gateway, ReceiptWitness)
|
||||
- **PostgreSQL** via CloudNativePG
|
||||
- **DragonflyDB** for caching
|
||||
|
||||
### Infrastructure
|
||||
- **Kubernetes** (k3s-compatible)
|
||||
- **Flux CD** — GitOps deployment
|
||||
- **GitHub Actions** — CI/CD
|
||||
- **CalVer** (`YYYY.MM.DD[.N]`) — image tagging
|
||||
- **Bitnami Sealed Secrets** — secret management
|
||||
- **Authentik** — OIDC/OAuth2 provider
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 20+
|
||||
- npm or pnpm
|
||||
- PostgreSQL (local or containerized)
|
||||
- Docker (for running services locally)
|
||||
|
||||
### Local Development
|
||||
|
||||
1. **Clone the repo**
|
||||
```bash
|
||||
git clone https://github.com/cartsnitch/cartsnitch.git
|
||||
cd cartsnitch
|
||||
```
|
||||
|
||||
2. **Install dependencies**
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. **Set up environment variables**
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your local settings
|
||||
```
|
||||
|
||||
4. **Start the frontend dev server**
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
The PWA will be available at `http://localhost:5173`.
|
||||
|
||||
5. **Run tests**
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
6. **Build for production**
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Running Backend Services Locally
|
||||
|
||||
The frontend PWA communicates with three backend services. For full local development, you'll need to run each service:
|
||||
|
||||
```bash
|
||||
# Auth service (Better-Auth)
|
||||
cd auth
|
||||
npm install
|
||||
npm run dev
|
||||
|
||||
# API Gateway (separate repo: cartsnitch/api)
|
||||
# See api/README.md
|
||||
|
||||
# ReceiptWitness (separate repo: cartsnitch/receiptwitness)
|
||||
# See receiptwitness/README.md
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `VITE_API_URL` | API Gateway base URL | `http://localhost:3000` |
|
||||
| `VITE_AUTH_URL` | Auth service base URL | `http://localhost:3001` |
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions. Please follow the workflow below.
|
||||
|
||||
### Branching Strategy
|
||||
|
||||
- Branch from `dev`
|
||||
- Use prefix: `feature/`, `fix/`, `docs/`, `chore/`
|
||||
- Examples: `feature/shopping-list-optimization`, `fix/price-chart-zoom`
|
||||
|
||||
### Commit Convention
|
||||
|
||||
We use [Conventional Commits](https://www.conventionalcommits.org/):
|
||||
|
||||
```
|
||||
feat: add shopping list export
|
||||
fix: correct price chart date formatting
|
||||
docs: update API documentation
|
||||
chore: update dependencies
|
||||
```
|
||||
|
||||
### Pull Request Workflow
|
||||
|
||||
1. Open a PR against `dev`
|
||||
2. CI must pass (lint, type check, tests, e2e)
|
||||
3. QA reviews and approves
|
||||
4. CTO merges to `dev`
|
||||
5. Dev deploys automatically
|
||||
6. CTO promotes `dev → uat`
|
||||
7. UAT and security review
|
||||
8. CEO merges `uat → main`
|
||||
9. Production deploys automatically
|
||||
|
||||
**Never push directly to `main`, `dev`, or `uat`.**
|
||||
|
||||
### Code Standards
|
||||
|
||||
- ESLint for linting
|
||||
- TypeScript strict mode
|
||||
- Mobile-first responsive design
|
||||
- Accessibility (WCAG 2.1 AA)
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit Tests
|
||||
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
### E2E Tests (Playwright)
|
||||
|
||||
```bash
|
||||
npm run test:e2e
|
||||
```
|
||||
|
||||
Tests run headless by default. For headed mode:
|
||||
|
||||
```bash
|
||||
npm run test:e2e:headed
|
||||
```
|
||||
|
||||
### Lighthouse CI
|
||||
|
||||
Performance audits run automatically in CI. To run locally:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
npm run preview
|
||||
# In another terminal:
|
||||
npx lighthouse http://localhost:4173 --output=html --output-path=./report/lighthouse.html
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Pipeline
|
||||
|
||||
All branches (`main`, `dev`, `uat`) run through GitHub Actions on every push.
|
||||
|
||||
### Pipeline Stages
|
||||
|
||||
| Job | Trigger | Purpose |
|
||||
|-----|---------|---------|
|
||||
| `lint` | Every push | ESLint + TypeScript type check |
|
||||
| `test` | Every push | Unit tests via Vitest |
|
||||
| `audit` | Every push | Security vulnerability scan |
|
||||
| `e2e` | Every push | Playwright end-to-end tests |
|
||||
| `lighthouse` | After test | Performance budget check |
|
||||
| `build-and-push` | On push to main/dev/uat | Build and push Docker images to GHCR |
|
||||
| `deploy-dev` | On push to dev or main | Update `cartsnitch/infra` → auto-deploy to dev |
|
||||
| `deploy-uat` | On push to uat or main | Update `cartsnitch/infra` → auto-deploy to uat |
|
||||
|
||||
### Image Tagging
|
||||
|
||||
- **Production (`main`):** CalVer tag (`YYYY.MM.DD[.N]`) + `latest`
|
||||
- **Development (`dev`):** SHA tag (`sha-<short-sha>`)
|
||||
|
||||
### Deployment Environments
|
||||
|
||||
| Environment | Namespace | URL | Trigger |
|
||||
|-------------|-----------|-----|---------|
|
||||
| Dev | `cartsnitch-dev` | `cartsnitch.dev.farh.net` | Push to `dev` branch |
|
||||
| UAT | `cartsnitch-uat` | `cartsnitch.uat.farh.net` | Push to `uat` branch |
|
||||
| Production | `cartsnitch` | `cartsnitch.farh.net` | Push to `main` branch |
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
### Infrastructure
|
||||
|
||||
The infrastructure repository ([cartsnitch/infra](https://github.com/cartsnitch/infra)) contains Kubernetes manifests and Flux Kustomize overlays.
|
||||
|
||||
### Flux GitOps Flow
|
||||
|
||||
1. CI builds and pushes a new Docker image
|
||||
2. CI opens a PR to `cartsnitch/infra` updating the image tag
|
||||
3. On merge, Flux reconciles the manifests and rolls out the new image
|
||||
|
||||
### Forcing a Rollout
|
||||
|
||||
To force pods to pick up a new `:latest` image:
|
||||
|
||||
```bash
|
||||
kubectl rollout restart deployment/<name> -n <namespace>
|
||||
```
|
||||
|
||||
### Secrets
|
||||
|
||||
Secrets are managed via **Bitnami Sealed Secrets**. No plain Kubernetes secrets are used.
|
||||
|
||||
---
|
||||
|
||||
## Related Projects
|
||||
|
||||
- [StickerShock](https://github.com/cartsnitch/stickershock) — Price increase detection
|
||||
- [ShrinkRay](https://github.com/cartsnitch/shrinkray) — Shrinkflation monitoring
|
||||
- [ClipArtist](https://github.com/cartsnitch/clipartist) — Coupon/deal optimization
|
||||
- [Infra](https://github.com/cartsnitch/infra) — Kubernetes infrastructure
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT © 2025 CartSnitch
|
||||
|
||||
@@ -4,7 +4,7 @@ import { mockAuthRoutes } from '../fixtures';
|
||||
const uniqueEmail = () => `betty+e2e-${Date.now()}@cartsnitch.test`;
|
||||
|
||||
test.describe('J1: Registration and Login', () => {
|
||||
test('can register a new account and see check your email screen', async ({ page }) => {
|
||||
test('shows success message after registration', async ({ page }) => {
|
||||
await mockAuthRoutes(page, false);
|
||||
await page.goto('/register');
|
||||
await page.fill('[placeholder="Full Name"]', 'Betty Tester');
|
||||
@@ -12,7 +12,8 @@ test.describe('J1: Registration and Login', () => {
|
||||
await page.fill('[placeholder="Password (min. 8 characters)"]', 'TestPass123!');
|
||||
await page.click('button[type="submit"]');
|
||||
|
||||
await expect(page.getByRole('heading', { name: /check your email/i })).toBeVisible();
|
||||
// Registration now shows "Account created! Please sign in." message
|
||||
await expect(page.locator('.bg-red-50')).toContainText('Account created! Please sign in.');
|
||||
});
|
||||
|
||||
test('shows validation error when registration fields are empty', async ({ page }) => {
|
||||
@@ -30,8 +31,16 @@ test.describe('J1: Registration and Login', () => {
|
||||
await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
|
||||
});
|
||||
|
||||
test('can sign in with credentials and land on dashboard', async ({ page }) => {
|
||||
test('can sign in with valid credentials', async ({ page }) => {
|
||||
await mockAuthRoutes(page, true);
|
||||
const email = uniqueEmail();
|
||||
await page.goto('/register');
|
||||
await page.fill('[placeholder="Full Name"]', 'Login Betty');
|
||||
await page.fill('[placeholder="Email"]', email);
|
||||
await page.fill('[placeholder="Password (min. 8 characters)"]', 'TestPass123!');
|
||||
await page.click('button[type="submit"]');
|
||||
await expect(page.locator('.bg-red-50')).toContainText('Account created! Please sign in.');
|
||||
|
||||
await page.goto('/login');
|
||||
await page.fill('[placeholder="Email"]', 'test@cartsnitch.test');
|
||||
await page.fill('[placeholder="Password"]', 'TestPass123!');
|
||||
|
||||
Generated
+3
-3
@@ -8164,9 +8164,9 @@
|
||||
}
|
||||
},
|
||||
"node_modules/postcss": {
|
||||
"version": "8.5.8",
|
||||
"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.8.tgz",
|
||||
"integrity": "sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==",
|
||||
"version": "8.5.13",
|
||||
"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.13.tgz",
|
||||
"integrity": "sha512-qif0+jGGZoLWdHey3UFHHWP0H7Gbmsk8T5VEqyYFbWqPr1XqvLGBbk/sl8V5exGmcYJklJOhOQq1pV9IcsiFag==",
|
||||
"devOptional": true,
|
||||
"funding": [
|
||||
{
|
||||
|
||||
+1
-8
@@ -1,14 +1,12 @@
|
||||
import { useState } from 'react'
|
||||
import { Link } from 'react-router-dom'
|
||||
import { authClient } from '../lib/auth-client.ts'
|
||||
import { useAuthStore } from '../stores/auth.ts'
|
||||
|
||||
export function Login() {
|
||||
const [email, setEmail] = useState('')
|
||||
const [password, setPassword] = useState('')
|
||||
const [error, setError] = useState('')
|
||||
const [loading, setLoading] = useState(false)
|
||||
const setAuthenticated = useAuthStore((s) => s.setAuthenticated)
|
||||
|
||||
async function handleSubmit(e: React.FormEvent) {
|
||||
e.preventDefault()
|
||||
@@ -40,12 +38,7 @@ export function Login() {
|
||||
setError('Sign in failed. Please try again.')
|
||||
}
|
||||
} catch {
|
||||
if (import.meta.env.VITE_MOCK_AUTH === 'true') {
|
||||
setAuthenticated(true)
|
||||
window.location.href = '/'
|
||||
} else {
|
||||
setError('Invalid email or password. Please try again.')
|
||||
}
|
||||
setError('Invalid email or password. Please try again.')
|
||||
} finally {
|
||||
setLoading(false)
|
||||
}
|
||||
|
||||
+1
-47
@@ -8,9 +8,6 @@ export function Register() {
|
||||
const [password, setPassword] = useState('')
|
||||
const [error, setError] = useState('')
|
||||
const [loading, setLoading] = useState(false)
|
||||
const [registrationComplete, setRegistrationComplete] = useState(false)
|
||||
const [resendLoading, setResendLoading] = useState(false)
|
||||
const [resendMessage, setResendMessage] = useState('')
|
||||
|
||||
async function handleSubmit(e: React.FormEvent) {
|
||||
e.preventDefault()
|
||||
@@ -38,7 +35,7 @@ export function Register() {
|
||||
throw new Error(authError.message ?? 'Registration failed')
|
||||
}
|
||||
|
||||
setRegistrationComplete(true)
|
||||
setError('Account created! Please sign in.')
|
||||
} catch {
|
||||
setError('Registration failed. Please try again.')
|
||||
} finally {
|
||||
@@ -46,49 +43,6 @@ export function Register() {
|
||||
}
|
||||
}
|
||||
|
||||
async function handleResendVerification() {
|
||||
setResendLoading(true)
|
||||
setResendMessage('')
|
||||
try {
|
||||
const { error } = await authClient.sendVerificationEmail({ email })
|
||||
if (error) {
|
||||
setResendMessage('Failed to resend. Please try again.')
|
||||
} else {
|
||||
setResendMessage('Verification email sent!')
|
||||
}
|
||||
} finally {
|
||||
setResendLoading(false)
|
||||
}
|
||||
}
|
||||
|
||||
if (registrationComplete) {
|
||||
return (
|
||||
<div className="flex min-h-screen flex-col items-center justify-center px-4">
|
||||
<h1 className="mb-2 text-3xl font-bold text-gray-900">Check your email</h1>
|
||||
<p className="mb-8 text-sm text-gray-500">
|
||||
We sent a verification link to {email}. Click it to activate your account.
|
||||
</p>
|
||||
<button
|
||||
type="button"
|
||||
onClick={handleResendVerification}
|
||||
disabled={resendLoading}
|
||||
className="min-h-12 rounded-xl bg-brand-blue px-6 py-3 text-base font-medium text-white active:bg-brand-blue/90 disabled:opacity-60"
|
||||
>
|
||||
{resendLoading ? 'Sending...' : 'Resend email'}
|
||||
</button>
|
||||
{resendMessage && (
|
||||
<p className="mt-4 text-sm text-gray-500">{resendMessage}</p>
|
||||
)}
|
||||
<p className="mt-6 text-sm text-gray-500">
|
||||
Already have an account?{' '}
|
||||
<Link to="/login" className="text-brand-blue">
|
||||
Sign in
|
||||
</Link>
|
||||
</p>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
return (
|
||||
<div className="flex min-h-screen flex-col items-center justify-center px-4">
|
||||
<h1 className="mb-2 text-3xl font-bold text-gray-900">Create Account</h1>
|
||||
|
||||
Reference in New Issue
Block a user