docs: add complete project documentation

- SPEC.md: project specification and goals - ARCHITECTURE.md: system design and component descriptions - database-schema.md: PostgreSQL schema with all tables - implementation-plan.md: 12-phase implementation guide - RUNNING.md: deployment and troubleshooting guide - ORIENTATION.md: context compaction recovery guide - README.md: project overview and quick start Family profile: 2 adults, 2 children. Mushroom avoidance for 3/4. Approval workflow: email proposals, one denial swaps meal. Tech stack: FastAPI, PostgreSQL, React, Playwright, SendGrid.
2026-05-04 19:27:22 -07:00
commit 0c5b0aa5ed
10 changed files with 2347 additions and 0 deletions
@@ -0,0 +1,346 @@
+# Running the Meal Planner
+
+## Prerequisites
+
+- Docker and Docker Compose
+- Git
+- SendGrid account (for email)
+- Lucky California store access (for scraping)
+
+## Environment Setup
+
+### 1. Clone Repository
+
+```bash
+git clone <repository-url>
+cd MealPlanner
+```
+
+### 2. Create Environment File
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your values:
+
+```bash
+# Database
+POSTGRES_PASSWORD=your_secure_password
+
+# SendGrid
+SENDGRID_API_KEY=SG.your_sendgrid_api_key
+
+# Family Emails
+FAMILY_EMAIL_1=you@example.com
+FAMILY_EMAIL_2=spouse@example.com
+
+# Lucky California (for scraping)
+LUCKY_CA_URL=https://www.luckyncal.com
+
+# AI Images (optional)
+AI_IMAGE_ENABLED=false
+AI_IMAGE_PROVIDER=openai
+AI_IMAGE_API_KEY=sk-your-key
+```
+
+### 3. Create SSL Certificates (for remote access)
+
+```bash
+mkdir -p nginx/ssl
+# Option 1: Let's Encrypt with Certbot
+certbot certonly --nginx -d your-domain.com
+
+# Option 2: Self-signed for local testing
+openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+  -keyout nginx/ssl/key.pem -out nginx/ssl/cert.pem
+```
+
+## Starting Services
+
+### Local Development
+
+```bash
+# Start all services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f backend
+docker-compose logs -f frontend
+
+# Stop all services
+docker-compose down
+```
+
+### Production Deployment
+
+```bash
+# Start with production settings
+docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+
+# Check service status
+docker-compose ps
+
+# View resource usage
+docker stats
+```
+
+## Accessing the Application
+
+### Local Access
+
+- **Web UI**: http://localhost:3000
+- **API**: http://localhost:8000
+- **API Docs**: http://localhost:8000/docs
+
+### Remote Access (with reverse proxy)
+
+Configure your domain and SSL in nginx/nginx.conf, then access via:
+- **Web UI**: https://your-domain.com
+- **API**: https://your-domain.com/api
+
+## Database Management
+
+### Initial Migration
+
+```bash
+# Run migrations
+docker-compose exec backend alembic upgrade head
+
+# Check current migration
+docker-compose exec backend alembic current
+
+# Create new migration after model changes
+docker-compose exec backend alembic revision --autogenerate -m "Description"
+```
+
+### Backup Database
+
+```bash
+# Backup to file
+docker-compose exec db pg_dump -U mealplanner mealplanner > backup_$(date +%Y%m%d).sql
+
+# Restore from backup
+cat backup_20240101.sql | docker-compose exec -T db psql -U mealplanner mealplanner
+```
+
+### Reset Database
+
+```bash
+# Danger: Drops and recreates all data
+docker-compose down -v
+docker-compose up -d
+docker-compose exec backend alembic upgrade head
+```
+
+## Scraping
+
+### Manual Scrape Trigger
+
+```bash
+# Scrape Lucky California weekly ad
+curl -X POST http://localhost:8000/api/admin/scrape \
+  -H "Content-Type: application/json" \
+  -d '{"source": "lucky_california", "type": "weekly_ad"}'
+```
+
+### Check Scrape Logs
+
+```bash
+# View recent scrape operations
+curl http://localhost:8000/api/admin/logs?limit=10
+```
+
+### Scheduling
+
+Scrape runs automatically:
+- Weekly: Sunday at 8 PM (before meal planning)
+- Daily: 6 AM (price updates)
+
+## Email Testing
+
+### Test Email Send
+
+```bash
+# Send test email
+curl -X POST http://localhost:8000/api/admin/test-email \
+  -H "Content-Type: application/json" \
+  -d '{"to": "test@example.com", "template": "meal_proposal"}'
+```
+
+### View Email Logs
+
+```bash
+curl http://localhost:8000/api/admin/email-logs
+```
+
+## Troubleshooting
+
+### Backend Won't Start
+
+```bash
+# Check logs
+docker-compose logs backend
+
+# Common issues:
+# - Database not ready: wait for db to be healthy
+# - Port conflict: check if port 8000 is in use
+# - Missing env vars: verify .env file exists and is valid
+```
+
+### Frontend Build Fails
+
+```bash
+# Check for Node version issues
+node --version  # Should be 18+
+
+# Clear cache and rebuild
+docker-compose exec frontend npm cache clean --force
+docker-compose exec frontend rm -rf node_modules package-lock.json
+docker-compose exec frontend npm install
+```
+
+### Database Connection Errors
+
+```bash
+# Verify database is running
+docker-compose ps db
+
+# Test connection from backend
+docker-compose exec backend python -c "from app.database import engine; print(engine.url)"
+
+# Check credentials
+docker-compose exec backend python -c "from app.database import SessionLocal; print('OK')"
+```
+
+### Scraping Failures
+
+```bash
+# Check Lucky California is accessible
+curl -I https://www.luckyncal.com
+
+# Verify Playwright browser installed
+docker-compose exec backend python -c "from playwright.sync_api import sync_playwright; print('OK')"
+
+# Manual retry
+docker-compose exec backend python -c "from app.scraper.lucky_ca import LuckyCaliforniaScraper; s = LuckyCaliforniaScraper(); s.scrape_weekly_ad()"
+```
+
+### Email Not Sending
+
+```bash
+# Verify SendGrid API key
+docker-compose exec backend python -c "import sendgrid; print('SendGrid imported')"
+
+# Check SendGrid dashboard for failures
+# Ensure sender email is verified in SendGrid
+```
+
+## Development
+
+### Backend Development
+
+```bash
+# Enter backend container
+docker-compose exec backend bash
+
+# Run tests
+pytest
+
+# Run with hot reload
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### Frontend Development
+
+```bash
+# Enter frontend container
+docker-compose exec frontend sh
+
+# Run dev server with hot reload
+npm run dev
+```
+
+### Database Migrations
+
+```bash
+# Create migration
+alembic revision --autogenerate -m "add_new_table"
+
+# Upgrade
+alembic upgrade head
+
+# Downgrade
+alembic downgrade -1
+
+# Show migration history
+alembic history
+```
+
+## Health Checks
+
+```bash
+# Check backend health
+curl http://localhost:8000/health
+
+# Check database connectivity
+curl http://localhost:8000/health/db
+
+# Check all services
+docker-compose ps
+```
+
+## Logs
+
+### View All Logs
+
+```bash
+docker-compose logs -f
+```
+
+### View Specific Service
+
+```bash
+docker-compose logs -f backend
+docker-compose logs -f frontend
+docker-compose logs -f db
+```
+
+### Configure Log Level
+
+In `backend/app/config.py`:
+```python
+LOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR
+```
+
+## Security Notes
+
+- Change default passwords in `.env`
+- Use strong SSL certificates for production
+- Consider VPN for remote database access
+- Regularly update Docker images
+- Review nginx access logs for suspicious activity
+
+## Updating
+
+```bash
+# Pull latest code
+git pull
+
+# Rebuild images
+docker-compose build
+
+# Run migrations
+docker-compose exec backend alembic upgrade head
+
+# Restart services
+docker-compose up -d
+```
+
+## Stopping Completely
+
+```bash
+docker-compose down        # Stop containers
+docker-compose down -v     # Stop and remove volumes (DELETES DATA)
+docker-compose down --rmi all  # Stop and remove images
+```