A family-friendly list management PWA with AI-powered categorization and real-time sync.
- Multiple List Types: Grocery, packing, and task lists
- AI Categorization: Automatic item categorization using embeddings
- Natural Language Parsing: "Meal mode" lets you type dishes and AI extracts ingredients
- Learning System: Remembers user corrections to improve over time
- Real-Time Sync: See changes instantly across all devices
- Shared Lists: Share lists with family members
See TODO.md for current bugs and planned improvements.
- Python 3.12+
- uv package manager
# Clone and enter directory
cd familylist
# Copy environment file
cp .env.example .env
# Edit .env and set your API_KEY
# Install dependencies
cd backend
uv sync
# Run development server
uv run uvicorn app.main:app --reloadOnce running, visit:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
cd backend
uv run pytest# Build and run
docker-compose up -d
# View logs
docker-compose logs -fThe GitHub Actions workflow automatically builds and pushes a new Docker image to ghcr.io on every push to master. To auto-update your running container, use Watchtower:
docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
containrrr/watchtower \
--interval 300This checks every 5 minutes for new images and automatically recreates containers with the latest version.
Manual update (Portainer):
- Go to Containers → click your familylist container
- Click Recreate
- Check "Re-pull image" before confirming
All API endpoints (except health check) require an API key:
curl -H "X-API-Key: your-api-key" http://localhost:8000/api/listsfamilylist/
├── backend/ # FastAPI backend
│ ├── app/
│ │ ├── api/ # Route handlers
│ │ └── services/ # Business logic
│ └── tests/
├── frontend/ # PWA frontend (Phase 2)
├── data/ # SQLite database
├── Dockerfile
└── docker-compose.yml
Private - Family use only