diff --git a/README.md b/README.md index 7b1dd70..44c4477 100644 --- a/README.md +++ b/README.md @@ -46,12 +46,13 @@ cd pantry ## 📚 Documentation -- [**Project Plan**](docs/PROJECT_PLAN.md) — Vision, roadmap, phases -- [**Architecture**](docs/ARCHITECTURE.md) — Tech stack, data model, design decisions -- [**Database Schema**](docs/DATABASE.md) — Tables, relationships, RLS policies -- [**API Reference**](docs/API.md) — Endpoints, Supabase functions -- [**Development Guide**](docs/DEVELOPMENT.md) — Setup, workflow, conventions -- [**Deployment**](docs/DEPLOYMENT.md) — Docker, Coolify, production setup +- **[Getting Started](docs/development/getting-started.md)** — First-time setup (5 minutes) +- **[Local Setup Guide](docs/development/local-setup.md)** — Detailed Docker Compose setup +- **[Project Plan](docs/PROJECT_PLAN.md)** — Vision, roadmap, MVP phases +- **[Architecture](docs/architecture/overview.md)** — Tech stack, design decisions +- **[Database Schema](docs/architecture/database.md)** — Tables, RLS policies, migrations +- **[Development Workflow](docs/development/workflow.md)** — Git flow, conventions +- **[Full Documentation Index](docs/README.md)** — Complete docs navigation ## 🛠️ Tech Stack diff --git a/SETUP.md b/SETUP.md deleted file mode 100644 index 1442ee2..0000000 --- a/SETUP.md +++ /dev/null @@ -1,214 +0,0 @@ -# Pantry - Setup Guide - -## ✅ Current Status - -### Infrastructure (Complete) - -- **Supabase Dev Instance**: Running on Coolify - - URL: `https://supabasekong-ewo8wssk4gs8cgg0c8kosk40.jeanlucmakiola.de` - - Status: ✅ Healthy - - Services: PostgreSQL, Auth (GoTrue), Realtime, Storage, PostgREST - -### Environment Configuration (Complete) - -- `.env.example` - Template for all environments -- `.env.development` - Dev credentials (Coolify Supabase) -- `.gitignore` - Protects secrets - ---- - -## 🚀 Quick Start (Development) - -### Prerequisites - -- **Bun** 1.0+ (or Node.js 20+) -- **Git** access to repository -- **Access to Coolify** Supabase instance (credentials in `.env.development`) - -### Setup Steps - -1. **Clone Repository** - ```bash - git clone https://gitea.jeanlucmakiola.de/pantry-app/pantry.git - cd pantry - ``` - -2. **Copy Development Environment** - ```bash - cp .env.development .env - ``` - -3. **Install Dependencies** (once `app/` exists) - ```bash - cd app - bun install - ``` - -4. **Apply Database Migrations** (once created) - ```bash - cd supabase - # TBD: Migration command - ``` - -5. **Start Development Server** - ```bash - cd app - bun run dev - ``` - -6. **Access App** - - App: `http://localhost:3000` - - Supabase API: `https://supabasekong-ewo8wssk4gs8cgg0c8kosk40.jeanlucmakiola.de` - ---- - -## 🗄️ Supabase Instance Details - -### Endpoints - -| Service | URL | -|---------|-----| -| API (PostgREST) | `https://supabasekong-ewo8wssk4gs8cgg0c8kosk40.jeanlucmakiola.de/rest/v1/` | -| Auth | `https://supabasekong-ewo8wssk4gs8cgg0c8kosk40.jeanlucmakiola.de/auth/v1/` | -| Realtime | `wss://supabasekong-ewo8wssk4gs8cgg0c8kosk40.jeanlucmakiola.de/realtime/v1/` | -| Storage | `https://supabasekong-ewo8wssk4gs8cgg0c8kosk40.jeanlucmakiola.de/storage/v1/` | - -### Credentials - -**Public (safe to use in frontend):** -- Anon Key: In `.env.development` - -**Secret (server-side only):** -- Service Role Key: In `.env.development` -- JWT Secret: In `.env.development` -- Postgres Password: In `.env.development` - -### Dashboard Access - -**Supabase Studio:** -- URL: `https://supabasekong-ewo8wssk4gs8cgg0c8kosk40.jeanlucmakiola.de` (check Coolify for Studio port/subdomain) -- Username: `wJZbjs3Yd5P63cs9` -- Password: `Qv3byDujNzYe8r7YRxhNwh3DPTvZBWtN` - -**Direct PostgreSQL Access** (for migrations/debugging): -- Host: `supabase-db` (or Coolify service FQDN) -- Database: `postgres` -- User: `postgres` -- Password: `55P0NVRUltRqzZYksuXTFli5iXwbQvgu` -- Port: `5432` - -**MinIO (Storage):** -- Admin User: `EaTXrXvjo1R4hsaI` -- Admin Password: `gCZOphxAExNC17GYFwtw60WzTU0P8HW8` - ---- - -## 📋 Next Steps - -### Week 1: Foundation (In Progress) - -- [x] ~~Supabase dev environment setup~~ (Complete) -- [x] ~~Environment configuration~~ (Complete) -- [ ] Create database schema (`supabase/migrations/`) -- [ ] Scaffold Nuxt 4 app (`app/`) -- [ ] Implement email/password auth -- [ ] Deploy first version to Coolify - -### Immediate Tasks - -1. **Database Schema** (#10) - - Create migration files in `supabase/migrations/` - - Tables: `inventory_items`, `products`, `tags`, `item_tags`, `units` - - See: `docs/DATABASE.md` - -2. **Nuxt Scaffold** (#8) - - Initialize Nuxt 4 project in `app/` - - Install dependencies: `@nuxtjs/supabase`, `@nuxt/ui`, Tailwind - - Configure `nuxt.config.ts` - -3. **Auth Implementation** (#11) - - Supabase Auth integration - - Login/signup pages - - Protected routes - ---- - -## 🔧 Development Workflow - -### Making Changes - -```bash -# 1. Create feature branch -git checkout -b feature/your-feature - -# 2. Make changes -# Edit files... - -# 3. Test locally -bun run dev - -# 4. Commit and push -git add . -git commit -m "feat: Your feature description" -git push origin feature/your-feature - -# 5. Create PR on Gitea -``` - -### Database Migrations - -```bash -# Create new migration -cd supabase/migrations -touch 001_initial_schema.sql - -# Edit migration file (SQL) -# Test locally against Coolify Supabase instance - -# Apply migration (TBD - once we set up migration tooling) -``` - ---- - -## 🚨 Troubleshooting - -### Can't connect to Supabase - -**Test connection:** -```bash -curl -s "https://supabasekong-ewo8wssk4gs8cgg0c8kosk40.jeanlucmakiola.de/rest/v1/" \ - -H "apikey: " -``` - -Should return OpenAPI spec. If not: -- Check Coolify service status -- Verify URL in `.env` -- Check network/firewall - -### Environment variables not loading - -- Ensure `.env` exists in project root -- Check `.env` has no syntax errors -- Restart dev server after changes - -### Database migration issues - -- Verify `SUPABASE_SERVICE_ROLE_KEY` is set -- Check migration SQL syntax -- Review Supabase logs in Coolify - ---- - -## 📚 Documentation - -- [Project Plan](docs/PROJECT_PLAN.md) - Vision, roadmap -- [Architecture](docs/ARCHITECTURE.md) - Tech stack, design -- [Database Schema](docs/DATABASE.md) - Tables, RLS, functions -- [API Reference](docs/API.md) - Endpoints, usage -- [Development Guide](docs/DEVELOPMENT.md) - Conventions, workflow -- [Deployment](docs/DEPLOYMENT.md) - Docker, Coolify - ---- - -**Last Updated:** 2026-02-08 -**Status:** Week 1 - Foundation in progress diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e699520 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,84 @@ +# Pantry Documentation + +Complete documentation for the Pantry household inventory management system. + +## 📚 Documentation Structure + +### 🚀 Getting Started + +- **[Project Overview](PROJECT_PLAN.md)** - Vision, roadmap, and MVP phases +- **[Local Setup Guide](development/local-setup.md)** - Docker Compose development environment +- **[Getting Started](development/getting-started.md)** - Quick start for new developers + +### 🏗️ Architecture + +- **[Architecture Overview](architecture/overview.md)** - Tech stack, design decisions, data flow +- **[Database Schema](architecture/database.md)** - Tables, relationships, RLS policies, migrations +- **[API Reference](architecture/api.md)** - Supabase endpoints, Edge Functions, helpers + +### 💻 Development + +- **[Development Workflow](development/workflow.md)** - Daily workflow, conventions, best practices +- **[Git Workflow](development/git-workflow.md)** - Branching strategy, PR process, reviews + +### 🚢 Deployment + +- **[Production Deployment](deployment/production.md)** - Docker, Coolify, environment setup +- **[CI/CD Pipeline](deployment/ci-cd.md)** - Automated testing, builds, deployments + +--- + +## 🎯 Quick Links by Role + +### New Developer +1. [Local Setup Guide](development/local-setup.md) - Get running in 5 minutes +2. [Architecture Overview](architecture/overview.md) - Understand the stack +3. [Development Workflow](development/workflow.md) - Daily development process + +### Feature Implementation +1. [Database Schema](architecture/database.md) - Table structure and queries +2. [API Reference](architecture/api.md) - Available endpoints +3. [Git Workflow](development/git-workflow.md) - Branch naming, PR checklist + +### Deployment & Operations +1. [Production Deployment](deployment/production.md) - Deploy to production +2. [CI/CD Pipeline](deployment/ci-cd.md) - Automated workflows + +--- + +## 📊 Current Status + +**MVP Progress:** 14/34 issues complete (41.2%) + +- ✅ Week 1: Database + Frontend Foundation (6/6) +- ✅ Week 2: Core Inventory Management (8/8) +- 🔄 Week 3: Barcode Scanning (1/5) +- ⏸️ Week 4-6: Tag UI, PWA, Deployment (20 remaining) + +See [PROJECT_PLAN.md](PROJECT_PLAN.md) for detailed roadmap. + +--- + +## 🤝 Contributing + +For contribution guidelines, see [Development Workflow](development/workflow.md). + +Key points: +- Feature branches off `develop` +- PRs require review before merge +- Follow conventional commits +- Write tests for new features + +--- + +## 🔗 External Resources + +- **Repository:** https://gitea.jeanlucmakiola.de/pantry-app/pantry +- **Supabase Docs:** https://supabase.com/docs +- **Nuxt 4 Docs:** https://nuxt.com +- **Open Food Facts API:** https://wiki.openfoodfacts.org/API + +--- + +**Last Updated:** 2026-02-09 +**Version:** 0.1.0-alpha (MVP in progress) diff --git a/docs/API.md b/docs/architecture/api.md similarity index 100% rename from docs/API.md rename to docs/architecture/api.md diff --git a/docs/DATABASE.md b/docs/architecture/database.md similarity index 100% rename from docs/DATABASE.md rename to docs/architecture/database.md diff --git a/docs/ARCHITECTURE.md b/docs/architecture/overview.md similarity index 100% rename from docs/ARCHITECTURE.md rename to docs/architecture/overview.md diff --git a/docs/CI_CD.md b/docs/deployment/ci-cd.md similarity index 100% rename from docs/CI_CD.md rename to docs/deployment/ci-cd.md diff --git a/docs/DEPLOYMENT.md b/docs/deployment/production.md similarity index 100% rename from docs/DEPLOYMENT.md rename to docs/deployment/production.md diff --git a/docs/development/getting-started.md b/docs/development/getting-started.md new file mode 100644 index 0000000..cfe6b83 --- /dev/null +++ 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)! diff --git a/docs/BRANCHING.md b/docs/development/git-workflow.md similarity index 100% rename from docs/BRANCHING.md rename to docs/development/git-workflow.md diff --git a/DEV_SETUP.md b/docs/development/local-setup.md similarity index 100% rename from DEV_SETUP.md rename to docs/development/local-setup.md diff --git a/docs/DEVELOPMENT.md b/docs/development/workflow.md similarity index 100% rename from docs/DEVELOPMENT.md rename to docs/development/workflow.md