docs: restructure documentation into organized folders

Organized docs into logical subdirectories: **New Structure:** - docs/ - README.md (index with quick links) - PROJECT_PLAN.md (root level - main roadmap) - development/ - getting-started.md (5-min quickstart) - local-setup.md (detailed Docker Compose guide) - workflow.md (daily development) - git-workflow.md (branching strategy) - architecture/ - overview.md (tech stack, design) - database.md (schema, RLS, migrations) - api.md (endpoints, functions) - deployment/ - production.md (Docker, Coolify) - ci-cd.md (automated pipelines) **Cleaned Up:** - Moved DEV_SETUP.md → docs/development/local-setup.md - Removed outdated SETUP.md (referenced old Coolify setup) - Replaced with getting-started.md (current Docker Compose flow) - Updated README.md links to new structure All paths tested, no broken links.
2026-02-09 13:45:57 +00:00
parent 12bda4c08f
commit b1ef7e43be
12 changed files with 280 additions and 220 deletions
--- a/docs/development/getting-started.md
+++ b/docs/development/getting-started.md
@@ -0,0 +1,189 @@
+# 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](https://docs.docker.com/get-docker/)
+- **Bun** - [Install](https://bun.sh): `curl -fsSL https://bun.sh/install | bash`
+- **Git**
+
+### One-Command Setup
+
+```bash
+# 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
+
+```bash
+# All services
+docker-compose logs -f
+
+# Just the database
+docker-compose logs -f db
+```
+
+### Reset Database
+
+```bash
+# Stop and remove volumes (fresh start)
+docker-compose down -v
+
+# Restart (migrations auto-apply)
+docker-compose up -d
+```
+
+### Access Database Directly
+
+```bash
+# psql CLI
+docker-compose exec db psql -U postgres -d postgres
+
+# Or use Supabase Studio (GUI)
+open http://localhost:54323
+```
+
+### Stop Everything
+
+```bash
+# 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](../architecture/overview.md)** - Tech stack and design decisions
+2. **[Database Schema](../architecture/database.md)** - Tables and relationships
+3. **[Development Workflow](workflow.md)** - 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](local-setup.md)** 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](local-setup.md)
+
+---
+
+**Ready to code?** Check out the [Development Workflow](workflow.md)!
--- a/docs/development/git-workflow.md
+++ b/docs/development/git-workflow.md
@@ -0,0 +1,358 @@
+# Pantry - Branching Strategy
+
+## 🌿 Branch Structure
+
+```
+main (production)
+  ↑
+  └── develop (development)
+        ↑
+        ├── feature/barcode-scanner
+        ├── feature/tag-system
+        ├── fix/quantity-bug
+        └── chore/update-deps
+```
+
+---
+
+## 📋 Branch Types
+
+### `main` - Production
+
+- **Purpose:** Production-ready code
+- **Protection:** Require PR approval
+- **Deploy:** Auto-deploy to production on push
+- **Stability:** Must always be stable
+
+**Rules:**
+- Never commit directly
+- Only merge from `develop` via release PR
+- All merges must pass CI/CD checks
+
+### `develop` - Development
+
+- **Purpose:** Integration branch for features
+- **Protection:** Require PR approval (optional)
+- **Deploy:** Auto-deploy to dev environment on push
+- **Stability:** Should be stable, but can have minor issues
+
+**Rules:**
+- Never commit directly (except hotfixes)
+- Merge features via PR
+- Keep in sync with `main` regularly
+
+### `feature/*` - Features
+
+- **Purpose:** New features or enhancements
+- **Naming:** `feature/short-description`
+- **Base:** Branch from `develop`
+- **Merge:** PR to `develop`
+
+**Examples:**
+- `feature/barcode-scanner`
+- `feature/tag-management`
+- `feature/unit-conversions`
+
+### `fix/*` - Bug Fixes
+
+- **Purpose:** Fix bugs in `develop`
+- **Naming:** `fix/short-description`
+- **Base:** Branch from `develop`
+- **Merge:** PR to `develop`
+
+**Examples:**
+- `fix/quantity-validation`
+- `fix/tag-duplication`
+
+### `hotfix/*` - Production Hotfixes
+
+- **Purpose:** Critical fixes for production
+- **Naming:** `hotfix/short-description`
+- **Base:** Branch from `main`
+- **Merge:** PR to both `main` AND `develop`
+
+**Examples:**
+- `hotfix/auth-bypass`
+- `hotfix/data-corruption`
+
+**Process:**
+```bash
+git checkout main
+git pull
+git checkout -b hotfix/critical-bug
+# Fix bug
+git push origin hotfix/critical-bug
+# Create PR to main (deploy immediately)
+# Create second PR to develop (keep in sync)
+```
+
+### `release/*` - Releases
+
+- **Purpose:** Prepare for production release
+- **Naming:** `release/v0.1.0`
+- **Base:** Branch from `develop`
+- **Merge:** PR to `main` (then tag)
+
+**Process:**
+```bash
+git checkout develop
+git pull
+git checkout -b release/v0.1.0
+# Update version, changelog, docs
+git push origin release/v0.1.0
+# Create PR to main
+# After merge, tag main with v0.1.0
+```
+
+### `chore/*` - Maintenance
+
+- **Purpose:** Dependencies, configs, tooling
+- **Naming:** `chore/short-description`
+- **Base:** Branch from `develop`
+- **Merge:** PR to `develop`
+
+**Examples:**
+- `chore/update-nuxt`
+- `chore/eslint-config`
+- `chore/ci-improvements`
+
+---
+
+## 🔄 Workflow Examples
+
+### Adding a Feature
+
+```bash
+# 1. Start from develop
+git checkout develop
+git pull origin develop
+
+# 2. Create feature branch
+git checkout -b feature/barcode-scanner
+
+# 3. Work on feature
+# ... make changes ...
+
+# 4. Commit regularly
+git add .
+git commit -m "feat: Add barcode detection logic"
+
+# 5. Push to remote
+git push origin feature/barcode-scanner
+
+# 6. Create PR to develop on Gitea
+# Review → Merge → Auto-deploys to dev
+```
+
+### Releasing to Production
+
+```bash
+# 1. Ensure develop is stable
+git checkout develop
+git pull origin develop
+
+# 2. Create release branch
+git checkout -b release/v0.1.0
+
+# 3. Update version and changelog
+# Edit package.json, CHANGELOG.md
+
+# 4. Commit and push
+git commit -am "chore: Prepare v0.1.0 release"
+git push origin release/v0.1.0
+
+# 5. Create PR to main
+# Review → Merge → Auto-deploys to production
+
+# 6. Tag the release
+git checkout main
+git pull origin main
+git tag -a v0.1.0 -m "Release v0.1.0"
+git push origin v0.1.0
+
+# 7. Merge back to develop (keep in sync)
+git checkout develop
+git merge main
+git push origin develop
+```
+
+### Hotfix Production Issue
+
+```bash
+# 1. Branch from main
+git checkout main
+git pull origin main
+git checkout -b hotfix/auth-bypass
+
+# 2. Fix the issue
+# ... fix ...
+
+# 3. Commit and push
+git commit -am "fix: Patch authentication bypass"
+git push origin hotfix/auth-bypass
+
+# 4. Create PR to main
+# Urgent review → Merge → Immediate deploy
+
+# 5. Also PR to develop (keep in sync)
+git checkout develop
+git pull origin develop
+git checkout -b hotfix/auth-bypass-to-develop
+git merge hotfix/auth-bypass
+git push origin hotfix/auth-bypass-to-develop
+# Create second PR to develop
+```
+
+---
+
+## 📝 Commit Message Convention
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Types
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Code style (formatting, no logic change)
+- `refactor`: Code refactoring
+- `test`: Adding/updating tests
+- `chore`: Maintenance (deps, configs)
+- `perf`: Performance improvement
+
+### Examples
+
+```bash
+feat(scan): Add barcode scanner component
+fix(inventory): Prevent negative quantities
+docs(api): Update product lookup examples
+chore(deps): Upgrade Nuxt to 4.1.2
+refactor(tags): Simplify tag picker logic
+test(units): Add conversion edge cases
+```
+
+---
+
+## 🔒 Branch Protection Rules
+
+### `main` (Production)
+
+- ✅ Require pull request before merging
+- ✅ Require status checks to pass
+- ✅ Require review from code owner (1+)
+- ✅ Dismiss stale approvals
+- ❌ Allow force push
+- ❌ Allow deletions
+
+### `develop` (Development)
+
+- ✅ Require pull request before merging (optional)
+- ✅ Require status checks to pass
+- ⚠️  Require review (recommended, not enforced)
+- ❌ Allow force push
+- ❌ Allow deletions
+
+**Configure in Gitea:**
+Repository → Settings → Branches → Add rule
+
+---
+
+## 🎯 Best Practices
+
+### Keep Branches Short-Lived
+
+- Feature branches: 1-3 days max
+- Merge frequently to avoid conflicts
+- Delete after merge
+
+### Sync with Develop Regularly
+
+```bash
+# While on feature branch
+git checkout feature/my-feature
+git fetch origin
+git merge origin/develop
+# Resolve conflicts if any
+```
+
+### Clean Commit History
+
+```bash
+# Interactive rebase before PR (optional)
+git rebase -i develop
+
+# Squash WIP commits into logical commits
+```
+
+### Tag Releases
+
+```bash
+# After merging release to main
+git checkout main
+git pull
+git tag -a v0.1.0 -m "MVP Release - Week 6"
+git push origin v0.1.0
+```
+
+---
+
+## 🚫 Anti-Patterns (Don't Do This)
+
+❌ **Commit directly to `main`**
+- Always use PR workflow
+
+❌ **Long-lived feature branches**
+- Break into smaller features
+- Merge incrementally
+
+❌ **Merge without review**
+- At least one other person should review
+
+❌ **Push broken code to `develop`**
+- Test locally first
+- CI checks should pass
+
+❌ **Forget to sync hotfix to `develop`**
+- Hotfixes must go to both branches
+
+---
+
+## 📊 Branch Lifecycle
+
+```
+feature/barcode-scanner
+  Created: 2026-02-10
+  Author: Jean-Luc
+  Status: In Progress
+  PRs: #15 (to develop)
+  
+  ↓ (PR merged)
+  
+  Merged to develop: 2026-02-12
+  Deployed to dev: ✅
+  Deleted: 2026-02-12
+```
+
+**Keep branches clean:**
+```bash
+# List merged branches
+git branch --merged develop
+
+# Delete merged local branches
+git branch -d feature/barcode-scanner
+
+# Delete merged remote branches
+git push origin --delete feature/barcode-scanner
+```
+
+---
+
+**Summary:** Keep it simple. Feature → PR → Develop → Test → Release → Main → Production. Always review, always test, never break `main`.
--- a/docs/development/local-setup.md
+++ b/docs/development/local-setup.md
@@ -0,0 +1,335 @@
+# Pantry - Local Development Setup
+
+Self-hosted household pantry management app with barcode scanning.
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- **Docker** & **Docker Compose** (for Supabase backend)
+- **Bun** (for Nuxt frontend) - Install: `curl -fsSL https://bun.sh/install | bash`
+- **Git**
+
+### 1. Clone & Setup
+
+```bash
+git clone https://gitea.jeanlucmakiola.de/pantry-app/pantry.git
+cd pantry
+```
+
+### 2. Start Supabase (Backend)
+
+```bash
+# Start all Supabase services
+docker-compose up -d
+
+# Wait ~10 seconds for services to initialize
+# Check status
+docker-compose ps
+```
+
+**Services running:**
+- PostgreSQL: `localhost:5432`
+- Supabase API: `http://localhost:54321`
+- Supabase Studio: `http://localhost:54323` (admin UI)
+
+### 3. Apply Database Migrations
+
+The migrations are automatically applied on first startup via `/docker-entrypoint-initdb.d`.
+
+To verify:
+```bash
+docker-compose exec db psql -U postgres -d postgres -c "\dt"
+```
+
+You should see: `inventory_items`, `products`, `tags`, `units`, `item_tags`
+
+### 4. Start Nuxt App (Frontend)
+
+```bash
+cd app
+bun install
+bun run dev
+```
+
+**App running:** `http://localhost:3000`
+
+### 5. Open & Test
+
+1. Visit `http://localhost:3000`
+2. Click "Add Manually" to create your first inventory item
+3. Access Supabase Studio at `http://localhost:54323` to view database
+
+---
+
+## 📁 Project Structure
+
+```
+pantry/
+├── app/                    # Nuxt 4 frontend
+│   ├── components/         # Vue components
+│   │   └── inventory/      # Inventory CRUD UI
+│   ├── composables/        # Supabase client, data hooks
+│   ├── pages/              # Routes (index, scan, settings)
+│   └── types/              # TypeScript definitions
+├── supabase/
+│   └── migrations/         # SQL schema & seed data
+├── docker/
+│   └── kong.yml            # API gateway config
+├── docker-compose.yml      # Supabase services
+└── .env                    # Environment variables
+```
+
+---
+
+## 🔧 Common Tasks
+
+### View Logs
+
+```bash
+# All services
+docker-compose logs -f
+
+# Specific service
+docker-compose logs -f db
+docker-compose logs -f auth
+```
+
+### Reset Database
+
+```bash
+# Stop services
+docker-compose down -v
+
+# Restart (migrations auto-apply)
+docker-compose up -d
+```
+
+### Access Database
+
+```bash
+# psql
+docker-compose exec db psql -U postgres -d postgres
+
+# Supabase Studio (GUI)
+# http://localhost:54323
+```
+
+### Run Migrations Manually
+
+```bash
+# If you add new migrations after initial setup
+docker-compose exec db psql -U postgres -d postgres -f /docker-entrypoint-initdb.d/003_helper_functions.sql
+```
+
+### Create Test User
+
+```bash
+# Via Supabase Studio: http://localhost:54323
+# → Authentication → Add User
+# Email: test@example.com
+# Password: password123
+
+# Or via curl:
+curl http://localhost:54321/auth/v1/signup \
+  -H "apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","password":"password123"}'
+```
+
+---
+
+## 🧪 Testing Features
+
+### 1. Inventory Management
+- Add items manually via form
+- Edit quantities with +/- buttons
+- Delete items
+- View expiry warnings
+
+### 2. Tags & Organization
+- Pre-seeded tags: Fridge, Freezer, Pantry, Dairy, Vegan, etc.
+- Multi-select tags when adding items
+- Color-coded badges
+
+### 3. Units
+- 30 pre-seeded units (g, kg, L, cups, pieces, etc.)
+- Automatic conversion support
+
+### 4. Barcode Scanning (Week 3 - In Progress)
+- Camera access (requires HTTPS in production)
+- Manual barcode entry fallback
+
+---
+
+## 🐛 Troubleshooting
+
+### Port Conflicts
+
+If ports 5432, 54321, or 3000 are in use:
+
+```bash
+# Check what's using the port
+sudo lsof -i :5432
+
+# Option 1: Stop conflicting service
+# Option 2: Change port in docker-compose.yml
+```
+
+### Database Connection Refused
+
+```bash
+# Wait for PostgreSQL to fully start
+docker-compose logs db | grep "ready to accept connections"
+
+# If stuck, restart
+docker-compose restart db
+```
+
+### Migrations Not Applied
+
+```bash
+# Verify migrations directory is mounted
+docker-compose exec db ls -la /docker-entrypoint-initdb.d
+
+# Manually apply
+docker-compose exec db bash
+cd /docker-entrypoint-initdb.d
+for f in *.sql; do psql -U postgres -d postgres -f "$f"; done
+```
+
+### Frontend: Module Not Found
+
+```bash
+cd app
+rm -rf node_modules bun.lock .nuxt
+bun install
+bun run dev
+```
+
+---
+
+## 📊 Database Schema
+
+### Tables
+
+| Table | Purpose | Rows (Est.) |
+|-------|---------|-------------|
+| `inventory_items` | Current inventory | 100-500 |
+| `products` | Barcode cache (Open Food Facts) | 500-2000 |
+| `tags` | Organization labels | 50 (33 pre-seeded) |
+| `units` | Measurement units | 50 (30 pre-seeded) |
+| `item_tags` | Many-to-many item ↔ tag | 200-1000 |
+
+### Pre-Seeded Data
+
+**Units (30):**
+- Weight: g, kg, mg, lb, oz
+- Volume: mL, L, cup, tbsp, tsp, gal, qt, pt
+- Count: piece, dozen, package, bottle, can, jar, box, bag
+
+**Tags (33):**
+- Position: Fridge, Freezer, Pantry, Cabinet
+- Type: Dairy, Meat, Vegetables, Fruits, Snacks
+- Dietary: Vegan, Gluten-Free, Organic, Kosher, Halal
+- Custom: Low Stock, To Buy, Meal Prep, Leftovers
+
+---
+
+## 🔐 Authentication
+
+**Default Setup (Development):**
+- Auto-confirm emails (no SMTP needed)
+- Anyone can sign up
+- JWT tokens valid for 1 hour
+
+**Create Admin User:**
+
+```sql
+-- Via psql
+docker-compose exec db psql -U postgres -d postgres
+
+INSERT INTO auth.users (id, email, encrypted_password, email_confirmed_at)
+VALUES (
+  gen_random_uuid(),
+  'admin@pantry.local',
+  crypt('admin123', gen_salt('bf')),
+  NOW()
+);
+```
+
+---
+
+## 🌐 Environment Variables
+
+**.env** (root)
+```bash
+POSTGRES_PASSWORD=postgres
+JWT_SECRET=your-secret-here
+ANON_KEY=<supabase-anon-key>
+SERVICE_ROLE_KEY=<supabase-service-role-key>
+```
+
+**app/.env** (Nuxt)
+```bash
+NUXT_PUBLIC_SUPABASE_URL=http://localhost:54321
+NUXT_PUBLIC_SUPABASE_ANON_KEY=<same-as-above>
+```
+
+---
+
+## 📈 Development Workflow
+
+1. **Make changes** to Nuxt app → Hot reload at `localhost:3000`
+2. **Database changes** → Create new migration in `supabase/migrations/`
+3. **Test** → Add items, scan barcodes, check database
+4. **Commit** → Feature branch → PR to `develop`
+
+---
+
+## 🚢 Production Deployment (Coming Soon)
+
+See `docs/DEPLOYMENT.md` for:
+- Coolify setup
+- Environment configuration
+- SSL/HTTPS setup
+- Backups
+
+---
+
+## 📚 Documentation
+
+- [Architecture](docs/ARCHITECTURE.md)
+- [Database Schema](docs/DATABASE.md)
+- [API Reference](docs/API.md)
+- [Development Guide](docs/DEVELOPMENT.md)
+
+---
+
+## 🤝 Contributing
+
+This is a personal project, but issues and PRs welcome!
+
+1. Fork the repo
+2. Create feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit changes (`git commit -m 'Add amazing feature'`)
+4. Push to branch (`git push origin feature/amazing-feature`)
+5. Open Pull Request
+
+---
+
+## 📝 License
+
+MIT License - See LICENSE file
+
+---
+
+## 🙋 Support
+
+- Issues: https://gitea.jeanlucmakiola.de/pantry-app/pantry/issues
+- Docs: https://gitea.jeanlucmakiola.de/pantry-app/pantry/wiki
+
+---
+
+**Version:** 0.1.0-alpha (MVP in progress)  
+**Status:** Week 2 complete, Week 3 in progress (14/34 issues done)
--- a/docs/development/workflow.md
+++ b/docs/development/workflow.md
@@ -0,0 +1,678 @@
+# Pantry - Development Guide
+
+**Version:** 1.0  
+**Last Updated:** 2026-02-08
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- **Node.js** 20+ (or Bun 1.0+)
+- **Docker** & Docker Compose
+- **Git**
+- **Code editor** (VS Code recommended)
+
+### Clone & Setup
+
+```bash
+# Clone repository
+git clone https://gitea.jeanlucmakiola.de/pantry-app/pantry.git
+cd pantry
+
+# Install dependencies (using Bun)
+bun install
+
+# Copy environment template
+cp .env.example .env
+
+# Start Supabase (PostgreSQL + Auth + Realtime)
+docker-compose -f docker/docker-compose.dev.yml up -d
+
+# Run database migrations
+cd supabase
+supabase db reset  # Creates schema + seeds data
+
+# Start Nuxt dev server
+cd ../app
+bun run dev
+
+# Access app at http://localhost:3000
+```
+
+---
+
+## 📁 Project Structure
+
+```
+pantry/
+├── app/                      # Nuxt 4 frontend
+│   ├── components/
+│   │   ├── inventory/       # Inventory UI components
+│   │   ├── scan/            # Barcode scanner components
+│   │   ├── tags/            # Tag management
+│   │   └── common/          # Shared UI components
+│   ├── composables/         # Shared logic (Vue Composition API)
+│   │   ├── useBarcode.ts
+│   │   ├── useInventory.ts
+│   │   └── useSupabase.ts
+│   ├── pages/               # Route pages
+│   │   ├── index.vue       # Inventory list
+│   │   ├── scan.vue        # Barcode scanner
+│   │   └── settings.vue    # Settings
+│   ├── utils/               # Pure functions
+│   │   ├── conversions.ts  # Unit conversion math
+│   │   └── validation.ts
+│   ├── nuxt.config.ts       # Nuxt configuration
+│   └── package.json
+├── supabase/                 # Database & backend
+│   ├── migrations/          # SQL migrations
+│   │   ├── 001_schema.sql
+│   │   ├── 002_seed_units.sql
+│   │   └── 003_rls.sql
+│   ├── functions/           # Edge functions
+│   │   └── product-lookup/
+│   ├── seed/                # Seed data (JSON)
+│   │   ├── units.json
+│   │   └── tags.json
+│   └── config.toml          # Supabase config
+├── docker/                   # Docker configs
+│   ├── docker-compose.dev.yml    # Development
+│   └── docker-compose.prod.yml   # Production
+├── docs/                     # Documentation
+├── scripts/                  # Utility scripts
+│   ├── seed-db.ts
+│   └── export-schema.ts
+├── .env.example
+├── .gitignore
+└── README.md
+```
+
+---
+
+## 🛠️ Development Workflow
+
+### 1. Create a Feature Branch
+
+```bash
+git checkout -b feature/barcode-scanner
+```
+
+### 2. Make Changes
+
+**Add a new component:**
+```bash
+# Create component file
+touch app/components/scan/BarcodeScanner.vue
+
+# Use in a page
+# app/pages/scan.vue
+<template>
+  <BarcodeScanner @scan="handleScan" />
+</template>
+```
+
+**Add a database migration:**
+```bash
+cd supabase
+supabase migration new add_location_field
+
+# Edit supabase/migrations/XXX_add_location_field.sql
+ALTER TABLE inventory_items ADD COLUMN location TEXT;
+
+# Apply locally
+supabase db reset
+```
+
+### 3. Test Locally
+
+```bash
+# Run type check
+bun run typecheck
+
+# Run linter
+bun run lint
+
+# Run tests (when implemented)
+bun run test
+
+# E2E tests
+bun run test:e2e
+```
+
+### 4. Commit & Push
+
+```bash
+git add .
+git commit -m "feat: Add barcode scanner component"
+git push origin feature/barcode-scanner
+```
+
+### 5. Create Pull Request
+
+- Go to Gitea: https://gitea.jeanlucmakiola.de/pantry-app/pantry
+- Create PR from your branch to `main`
+- Request review
+- Merge when approved
+
+---
+
+## 📝 Code Conventions
+
+### Naming
+
+**Files:**
+- Components: `PascalCase.vue` (e.g., `BarcodeScanner.vue`)
+- Composables: `camelCase.ts` (e.g., `useBarcode.ts`)
+- Utils: `camelCase.ts` (e.g., `conversions.ts`)
+- Pages: `kebab-case.vue` (e.g., `item-detail.vue`)
+
+**Variables:**
+- `camelCase` for variables, functions
+- `PascalCase` for types, interfaces
+- `SCREAMING_SNAKE_CASE` for constants
+
+```typescript
+// Good
+const itemCount = 5
+const fetchProducts = () => {}
+interface Product { ... }
+const MAX_ITEMS = 100
+
+// Bad
+const ItemCount = 5
+const fetch_products = () => {}
+interface product { ... }
+const maxItems = 100  // for constants
+```
+
+### Vue Component Structure
+
+```vue
+<script setup lang="ts">
+// 1. Imports
+import { ref, computed } from 'vue'
+import type { InventoryItem } from '~/types'
+
+// 2. Props & Emits
+interface Props {
+  item: InventoryItem
+  editable?: boolean
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  editable: false
+})
+
+const emit = defineEmits<{
+  save: [item: InventoryItem]
+  cancel: []
+}>()
+
+// 3. Composables
+const { convert } = useUnits()
+const supabase = useSupabaseClient()
+
+// 4. State
+const quantity = ref(props.item.quantity)
+const isEditing = ref(false)
+
+// 5. Computed
+const displayQuantity = computed(() => 
+  `${quantity.value} ${props.item.unit.abbreviation}`
+)
+
+// 6. Methods
+const handleSave = async () => {
+  const { error } = await supabase
+    .from('inventory_items')
+    .update({ quantity: quantity.value })
+    .eq('id', props.item.id)
+  
+  if (!error) emit('save', { ...props.item, quantity: quantity.value })
+}
+
+// 7. Lifecycle (if needed)
+onMounted(() => {
+  console.log('Component mounted')
+})
+</script>
+
+<template>
+  <div class="item-card">
+    <h3>{{ item.name }}</h3>
+    <p>{{ displayQuantity }}</p>
+    
+    <button v-if="editable" @click="handleSave">
+      Save
+    </button>
+  </div>
+</template>
+
+<style scoped>
+.item-card {
+  /* Prefer Tailwind classes in template */
+  /* Use scoped styles only for complex/unique styles */
+}
+</style>
+```
+
+### TypeScript
+
+**Prefer interfaces over types:**
+```typescript
+// Good
+interface InventoryItem {
+  id: string
+  name: string
+  quantity: number
+}
+
+// Only use type for unions, intersections
+type Status = 'active' | 'expired'
+```
+
+**Use strict typing:**
+```typescript
+// Good
+const fetchItem = async (id: string): Promise<InventoryItem | null> => {
+  const { data } = await supabase
+    .from('inventory_items')
+    .select('*')
+    .eq('id', id)
+    .single()
+  
+  return data
+}
+
+// Bad (implicit any)
+const fetchItem = async (id) => {
+  const { data } = await supabase...
+  return data
+}
+```
+
+### Composables
+
+**Naming:** Always start with `use`
+
+**Structure:**
+```typescript
+// composables/useInventory.ts
+export function useInventory() {
+  const supabase = useSupabaseClient<Database>()
+  const items = ref<InventoryItem[]>([])
+  const loading = ref(false)
+  
+  const fetchItems = async () => {
+    loading.value = true
+    const { data, error } = await supabase
+      .from('inventory_items')
+      .select('*')
+    
+    if (data) items.value = data
+    loading.value = false
+  }
+  
+  const addItem = async (item: NewInventoryItem) => {
+    const { data, error } = await supabase
+      .from('inventory_items')
+      .insert(item)
+      .select()
+      .single()
+    
+    if (data) items.value.push(data)
+    return { data, error }
+  }
+  
+  // Return reactive state + methods
+  return {
+    items: readonly(items),
+    loading: readonly(loading),
+    fetchItems,
+    addItem
+  }
+}
+```
+
+### Database Migrations
+
+**Naming:**
+```
+001_initial_schema.sql
+002_seed_defaults.sql
+003_add_location_field.sql
+```
+
+**Structure:**
+```sql
+-- Migration: Add location field to inventory items
+-- Created: 2026-02-08
+
+BEGIN;
+
+ALTER TABLE inventory_items 
+  ADD COLUMN location TEXT;
+
+-- Update existing items (optional)
+UPDATE inventory_items 
+  SET location = 'Pantry' 
+  WHERE location IS NULL;
+
+COMMIT;
+```
+
+**Rollback (optional):**
+```sql
+-- To rollback:
+-- ALTER TABLE inventory_items DROP COLUMN location;
+```
+
+---
+
+## 🧪 Testing
+
+### Unit Tests (Vitest)
+
+```typescript
+// app/utils/conversions.test.ts
+import { describe, it, expect } from 'vitest'
+import { convertUnit } from './conversions'
+
+describe('convertUnit', () => {
+  it('converts grams to kilograms', () => {
+    const result = convertUnit(500, {
+      conversion_factor: 0.001,
+      base_unit_id: 'kg'
+    }, {
+      conversion_factor: 1,
+      base_unit_id: null
+    })
+    
+    expect(result).toBe(0.5)
+  })
+  
+  it('throws error for incompatible units', () => {
+    expect(() => {
+      convertUnit(1, 
+        { unit_type: 'weight', conversion_factor: 1 },
+        { unit_type: 'volume', conversion_factor: 1 }
+      )
+    }).toThrow('Cannot convert')
+  })
+})
+```
+
+**Run tests:**
+```bash
+bun test
+bun test --watch  # Watch mode
+```
+
+### E2E Tests (Playwright)
+
+```typescript
+// tests/e2e/inventory.spec.ts
+import { test, expect } from '@playwright/test'
+
+test('can add item to inventory', async ({ page }) => {
+  await page.goto('/')
+  
+  // Login
+  await page.fill('[name=email]', 'test@example.com')
+  await page.fill('[name=password]', 'password')
+  await page.click('button[type=submit]')
+  
+  // Add item
+  await page.click('[data-testid=add-item]')
+  await page.fill('[name=name]', 'Test Item')
+  await page.fill('[name=quantity]', '2')
+  await page.click('button:has-text("Add")')
+  
+  // Verify
+  await expect(page.locator('text=Test Item')).toBeVisible()
+})
+```
+
+**Run E2E:**
+```bash
+bun run test:e2e
+bun run test:e2e --ui  # Interactive mode
+```
+
+---
+
+## 🔧 Supabase Local Development
+
+### Start Supabase
+
+```bash
+cd supabase
+supabase start
+```
+
+**Outputs:**
+```
+API URL: http://localhost:54321
+Studio URL: http://localhost:54323
+Anon key: eyJhb...
+Service key: eyJhb...
+```
+
+**Access Supabase Studio:**
+- Open http://localhost:54323
+- View tables, run queries, manage auth
+
+### Apply Migrations
+
+```bash
+# Reset DB (drops all data, reapplies migrations)
+supabase db reset
+
+# Create new migration
+supabase migration new add_feature
+
+# Apply migrations (non-destructive)
+supabase migration up
+```
+
+### Generate Types
+
+```bash
+# Generate TypeScript types from database schema
+supabase gen types typescript --local > app/types/supabase.ts
+```
+
+**Usage:**
+```typescript
+import type { Database } from '~/types/supabase'
+
+const supabase = useSupabaseClient<Database>()
+```
+
+---
+
+## 🌐 Environment Variables
+
+### `.env` (Development)
+
+```bash
+# Supabase (from `supabase start`)
+SUPABASE_URL=http://localhost:54321
+SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+
+# App
+PUBLIC_APP_URL=http://localhost:3000
+
+# Open Food Facts (optional, no key needed)
+OPENFOODFACTS_API_URL=https://world.openfoodfacts.org
+```
+
+### `.env.production`
+
+```bash
+# Supabase (production)
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+
+# App
+PUBLIC_APP_URL=https://pantry.yourdomain.com
+```
+
+---
+
+## 🐛 Debugging
+
+### Nuxt DevTools
+
+**Enable:**
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  devtools: { enabled: true }
+})
+```
+
+**Access:** Press `Shift + Alt + D` or visit http://localhost:3000/__devtools__
+
+### Vue DevTools
+
+Install browser extension:
+- Chrome: [Vue DevTools](https://chrome.google.com/webstore/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
+- Firefox: [Vue DevTools](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)
+
+### Supabase Logs
+
+```bash
+# View realtime logs
+supabase logs --tail
+
+# Filter by service
+supabase logs --service postgres
+supabase logs --service auth
+```
+
+### Database Queries
+
+**Supabase Studio:**
+- Open http://localhost:54323
+- Go to "SQL Editor"
+- Run queries directly
+
+**CLI:**
+```bash
+# psql into local database
+supabase db shell
+
+# Run query
+SELECT * FROM inventory_items LIMIT 5;
+```
+
+---
+
+## 📦 Build & Preview
+
+### Build for Production
+
+```bash
+cd app
+bun run build
+```
+
+**Output:** `.output/` directory (ready for deployment)
+
+### Preview Production Build
+
+```bash
+bun run preview
+```
+
+**Access:** http://localhost:3000
+
+---
+
+## 🔄 Git Workflow
+
+### Branch Naming
+
+```
+feature/barcode-scanner
+fix/tag-duplication-bug
+chore/update-dependencies
+docs/api-reference
+```
+
+### Commit Messages (Conventional Commits)
+
+```bash
+# Format: <type>(<scope>): <subject>
+
+feat(scan): add barcode detection
+fix(inventory): prevent duplicate items
+chore(deps): update Nuxt to 4.1
+docs(api): add product lookup endpoint
+refactor(tags): simplify tag picker logic
+test(units): add conversion edge cases
+style(ui): apply Tailwind spacing
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `chore`: Maintenance (deps, config)
+- `docs`: Documentation
+- `refactor`: Code restructuring
+- `test`: Adding/updating tests
+- `style`: Code style (formatting, no logic change)
+
+---
+
+## 🚨 Common Issues
+
+### Supabase won't start
+
+```bash
+# Check Docker
+docker ps
+
+# Restart Supabase
+supabase stop
+supabase start
+```
+
+### Types out of sync
+
+```bash
+# Regenerate types after schema change
+supabase gen types typescript --local > app/types/supabase.ts
+```
+
+### Port already in use
+
+```bash
+# Nuxt (3000)
+lsof -ti:3000 | xargs kill
+
+# Supabase (54321)
+supabase stop
+```
+
+---
+
+## 📚 Resources
+
+**Docs:**
+- [Nuxt 4](https://nuxt.com)
+- [Supabase](https://supabase.com/docs)
+- [Vue 3](https://vuejs.org)
+- [Tailwind CSS](https://tailwindcss.com)
+
+**Community:**
+- [Pantry Discussions](https://gitea.jeanlucmakiola.de/pantry-app/pantry/issues)
+- [Nuxt Discord](https://discord.com/invite/ps2h6QT)
+- [Supabase Discord](https://discord.supabase.com)
+
+---
+
+**Next:** [Deployment Guide](./DEPLOYMENT.md)