pantry/docs/development/getting-started.md

Getting Started with Pantry Development

Welcome! This guide will get you from zero to running Pantry locally in ~5 minutes.

🎯 What You'll Build

A self-hosted kitchen inventory app with:

• Inventory management (add, edit, delete items)
• Tag-based organization (Fridge, Freezer, Dairy, etc.)
• Unit conversions (g, kg, L, cups)
• Barcode scanning (coming soon)
• PWA features (offline, installable)

⚡ Quick Start

Prerequisites

• Docker & Docker Compose - Install
• Bun - Install: curl -fsSL https://bun.sh/install | bash
• Git

One-Command Setup

# Clone the repo
git clone https://gitea.jeanlucmakiola.de/pantry-app/pantry.git
cd pantry

# Run the setup script
./dev.sh

That's it! The script will:

1. ✅ Start Supabase services (Docker Compose)
2. ✅ Wait for services to initialize
3. ✅ Install frontend dependencies
4. ✅ Launch Nuxt dev server

Access the App

Service	URL	Purpose
App	http://localhost:3000	Main frontend
Supabase Studio	http://localhost:54323	Database admin UI
API	http://localhost:54321	Backend API

🎮 Try It Out

1. Open http://localhost:3000
2. Click "Add Manually" to create your first item
3. Fill in:
   • Name: "Milk"
   • Quantity: 1
   • Unit: Liter
   • Tags: Fridge, Dairy
   • Expiry: Set a date
4. Click "Add Item" and see it in the grid!

Explore Features

• Edit item: Click "Edit" on any card
• Adjust quantity: Use +/- buttons
• Delete item: Click "Delete" (confirms first)
• View database: Open Supabase Studio at :54323

📁 Project Structure

pantry/
├── app/                      # Nuxt 4 frontend
│   ├── components/           # Vue components
│   │   └── inventory/        # Inventory UI (List, Card, Forms)
│   ├── composables/          # Data hooks (useInventory, useSupabase)
│   ├── pages/                # Routes (index, scan, settings)
│   └── types/                # TypeScript definitions
├── supabase/
│   └── migrations/           # Database schema (001-005)
├── docker-compose.yml        # Supabase services
├── docker/
│   └── kong.yml              # API gateway config
└── docs/                     # Documentation

🛠️ Common Tasks

View Logs

# All services
docker-compose logs -f

# Just the database
docker-compose logs -f db

Reset Database

# Stop and remove volumes (fresh start)
docker-compose down -v

# Restart (migrations auto-apply)
docker-compose up -d

Access Database Directly

# psql CLI
docker-compose exec db psql -U postgres -d postgres

# Or use Supabase Studio (GUI)
open http://localhost:54323

Stop Everything

# Stop services (keep data)
docker-compose stop

# Stop and remove everything
docker-compose down -v

🔍 What's Included

Database (Pre-seeded)

30 Units:

• Weight: g, kg, mg, lb, oz
• Volume: mL, L, cup, tbsp, tsp
• Count: piece, dozen, bottle, can, jar

33 Tags:

• Position: Fridge, Freezer, Pantry
• Type: Dairy, Meat, Vegetables, Fruits
• Dietary: Vegan, Gluten-Free, Organic
• Custom: Low Stock, To Buy, Meal Prep

Features (Working Now)

• ✅ Add/Edit/Delete inventory items
• ✅ Tag selection (multi-select)
• ✅ Unit conversions
• ✅ Expiry date tracking with warnings
• ✅ Responsive layout (mobile-ready)
• ✅ Quantity quick actions (+/- buttons)

Features (Coming Soon)

• ⏳ Barcode scanning (Week 3)
• ⏳ User authentication UI
• ⏳ Tag management
• ⏳ PWA (offline mode)

📚 Next Steps

Learn the Stack

1. Architecture Overview - Tech stack and design decisions
2. Database Schema - Tables and relationships
3. Development Workflow - Daily development process

Make Your First Change

1. Pick an issue from Gitea
2. Create a branch: git checkout -b feature/your-feature
3. Make changes, test locally
4. Commit: git commit -m "feat: your feature"
5. Push and create PR

Troubleshooting

See Local Setup Guide for:

• Port conflicts
• Database connection issues
• Frontend errors
• Environment variables

🤝 Need Help?

• Documentation: Browse /docs folder
• Issues: Create an issue on Gitea
• Local setup: See local-setup.md

---

Ready to code? Check out the Development Workflow!