# 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.