Grocery Tracker

A web application for tracking grocery prices and shopping events. Built with FastAPI (Python) backend and React (TypeScript) frontend.

Features

• Grocery Management: Add, edit, and track grocery items with prices, categories, and organic status
• Shop Management: Manage different shops with locations
• Shopping Events: Record purchases with multiple groceries and amounts
• Price Tracking: Monitor price changes over time
• Modern UI: Clean, responsive interface built with React and Tailwind CSS

Architecture

Technology Stack

Backend (Python):

• FastAPI - Modern, fast web framework
• SQLAlchemy - SQL toolkit and ORM
• PostgreSQL - Relational database
• Pydantic - Data validation and settings management
• Alembic - Database migrations

Frontend (React):

• React 18 with TypeScript
• React Router - Client-side routing
• Tailwind CSS - Utility-first CSS framework
• Axios - HTTP client for API calls
• React Hook Form - Form handling

Component Communication

┌─────────────────┐    HTTP/REST API    ┌─────────────────┐    SQL Queries    ┌─────────────────┐
│   React         │ ←─────────────────→ │   FastAPI       │ ←───────────────→ │   PostgreSQL    │
│   Frontend      │     JSON requests   │   Backend       │   SQLAlchemy ORM  │   Database      │
│   (Port 3000)   │     JSON responses  │   (Port 8000)   │                   │   (Port 5432)   │
└─────────────────┘                     └─────────────────┘                   └─────────────────┘

Data Model

Groceries

• id: Primary key
• name: Grocery name
• price: Current price
• category: Food category
• organic: Boolean flag
• weight: Weight/volume
• weight_unit: Unit (g, kg, ml, l, piece)

Shops

• id: Primary key
• name: Shop name
• city: Location city
• address: Optional full address

Shopping Events

• id: Primary key
• shop_id: Foreign key to shops
• date: Purchase date
• total_amount: Optional total cost
• notes: Optional notes
• groceries: Many-to-many relationship with amounts

Setup Instructions

Prerequisites

1. Python 3.8+ - For the backend
2. Node.js 16+ - For the frontend
3. PostgreSQL - Database

Backend Setup

1. Navigate to backend directory:

   cd backend
   

2. Create virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Setup database:

   # Create PostgreSQL database
   createdb grocery_tracker
   
   # Copy environment variables
   cp env.example .env
   
   # Edit .env with your database credentials
   nano .env
   

5. Run database migrations:

   alembic upgrade head  # After setting up alembic
   

6. Start the backend server:

   uvicorn main:app --reload
   

   The API will be available at http://localhost:8000 API docs at http://localhost:8000/docs

Frontend Setup

1. Navigate to frontend directory:

   cd frontend
   

2. Install dependencies:

   npm install
   

3. Start the development server:

   npm start
   

   The app will be available at http://localhost:3000

API Endpoints

Groceries

• GET /groceries/ - List all groceries
• POST /groceries/ - Create new grocery
• GET /groceries/{id} - Get specific grocery
• PUT /groceries/{id} - Update grocery
• DELETE /groceries/{id} - Delete grocery

Shops

• GET /shops/ - List all shops
• POST /shops/ - Create new shop
• GET /shops/{id} - Get specific shop

Shopping Events

• GET /shopping-events/ - List all shopping events
• POST /shopping-events/ - Create new shopping event
• GET /shopping-events/{id} - Get specific shopping event

Statistics

• GET /stats/categories - Category spending statistics
• GET /stats/shops - Shop visit statistics

Usage

1. Add Shops: Start by adding shops where you buy groceries
2. Add Groceries: Create grocery items with prices and categories
3. Record Purchases: Use the "Add Purchase" form to record shopping events
4. Track Prices: Monitor how prices change over time
5. View Statistics: Analyze spending patterns by category and shop

Development

Running Tests

Backend:

cd backend
pytest

Frontend:

cd frontend
npm test

Database Migrations

cd backend
alembic revision --autogenerate -m "Description"
alembic upgrade head

Docker Deployment

Create docker-compose.yml for easy deployment:

version: '3.8'
services:
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: grocery_tracker
      POSTGRES_USER: grocery_user
      POSTGRES_PASSWORD: your_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  backend:
    build: ./backend
    ports:
      - "8000:8000"
    depends_on:
      - db
    environment:
      DATABASE_URL: postgresql://grocery_user:your_password@db:5432/grocery_tracker

  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    depends_on:
      - backend

volumes:
  postgres_data:

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes
4. Add tests
5. Submit a pull request

License

MIT License