99 lines
3.1 KiB
Markdown
99 lines
3.1 KiB
Markdown
# 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.
|