initial boilerplate

2026-05-03 16:43:53 +03:00
parent bea266e066
commit 2e63e0e95b
18 changed files with 1878 additions and 1 deletions
@@ -1,2 +1,98 @@
-# Deflated
+# Deflated.fyi — Crowdsourced Inflation Tracker

+A Go backend + React frontend for tracking real grocery prices over time,
+aggregated from user-submitted receipts.
+
+## Project structure
+
+```
+deflated/
+├── cmd/server/main.go          # Entrypoint — starts HTTP server
+├── internal/
+│   ├── api/
+│   │   ├── router.go           # Chi router, all routes registered here
+│   │   └── handlers.go         # One handler per endpoint
+│   ├── db/
+│   │   ├── connect.go          # pgxpool setup
+│   │   └── queries.go          # All SQL queries as typed Go methods
+│   ├── models/
+│   │   └── models.go           # Shared structs (DB rows, API shapes)
+│   ├── parser/
+│   │   └── normalize.go        # Receipt item → canonical name
+│   └── inflation/
+│       └── worker.go           # Background job: refresh price snapshots
+├── migrations/
+│   └── 001_initial.sql         # Database schema
+├── .env.example                # Copy to .env, fill in values
+├── Makefile                    # make run / test / migrate
+└── go.mod
+```
+
+## Prerequisites
+
+- Go 1.23+
+- PostgreSQL 15+
+
+## Quick start
+
+```bash
+# 1. Clone and enter the project
+git clone https://github.com/yourname/deflated
+cd deflated
+
+# 2. Set up environment
+cp .env.example .env
+# Edit .env with your DATABASE_URL
+
+# 3. Create the database
+createdb deflated
+make migrate
+
+# 4. Install dependencies and run
+go mod tidy
+make run
+```
+
+Server starts on http://localhost:8080
+
+## API
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | /health | Health check |
+| POST | /api/receipts | Submit a receipt with line items |
+| GET | /api/receipts/:id | Get a receipt and its items |
+| GET | /api/items/:name/history | Price history for a canonical item |
+| GET | /api/items/movers | Top price movers (last 12 months) |
+| GET | /api/inflation/summary | Purchasing power summary |
+
+### Submit a receipt
+
+```bash
+curl -X POST http://localhost:8080/api/receipts \
+  -H "Content-Type: application/json" \
+  -d '{
+    "store_name": "Trader Joes",
+    "receipt_date": "2024-11-15",
+    "city": "Austin, TX",
+    "items": [
+      { "name": "Whole Milk 1 Gallon", "price": 4.29 },
+      { "name": "Large Eggs Dozen",    "price": 3.49 },
+      { "name": "White Bread Loaf",    "price": 2.99, "quantity": 1 }
+    ]
+  }'
+```
+
+## Go learning path
+
+This project is intentionally structured to teach Go incrementally:
+
+1. **`cmd/server/main.go`** — entry point, signals, graceful shutdown
+2. **`internal/db/connect.go`** — connection pools, context, timeouts
+3. **`internal/api/router.go`** — Chi router, middleware
+4. **`internal/api/handlers.go`** — request parsing, error handling, JSON responses
+5. **`internal/db/queries.go`** — raw SQL with pgx, scanning rows into structs
+6. **`internal/parser/normalize.go`** — pure functions, string processing
+7. **`internal/inflation/worker.go`** — goroutines, channels, context cancellation
+
+Read the files in that order and you'll have covered ~80% of idiomatic Go.