forked from cartsnitch/cartsnitch
docs: expand README with architecture and contribution guide (#190)
* 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>
This commit is contained in:
cartsnitch-engineer[bot]
committed by
GitHub
GitHub
parent
8a44ee9c38
commit
48a999d569
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user