forked from cartsnitch/cartsnitch
cartsnitch-engineer[bot]
48a999d569
* docs: expand README with architecture and contribution guide * fix: address CTO review feedback on README * fix: align API Gateway box label padding in ASCII diagram --------- Co-authored-by: Barcode Betty <barcode-betty@cartsnitch.ing> Co-authored-by: Barcode Betty <barcode-betty@paperclip.ing> Co-authored-by: Chris Farhood <chris@farhood.org>
316 lines
9.4 KiB
Markdown
316 lines
9.4 KiB
Markdown
# 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
|