Tamari

Tamari is a Python‑based web application for recipe management that prioritizes extensibility and a clean developer experience. Built on the Flask microframework, it exposes a RESTful API for all core entities—recipes, shopping lists, meal plans—and relies on a relational database (PostgreSQL or SQLite by default) for persistence. The codebase follows conventional Flask patterns: blueprints separate concerns, Jinja2 templates drive the UI, and SQLAlchemy ORM abstracts database interactions. Because it is open source under GPL v3, developers can modify the entire stack, from authentication to image handling, without licensing constraints.

• User Management – Email/password authentication with optional SMTP‑based password reset.
• Recipe CRUD & Search – Full‑text search powered by SQLite’s FTS or PostgreSQL’s tsvector, live “search‑as‑you‑type” via AJAX.
• Import/Export – Bulk import from 50 recipe sites, JSON/ZIP export for backups.
• Shopping & Meal Planning – One‑click ingredient extraction, barcode scanning via external services, calendar integration.
• Customizable UI – Theme toggles, accent colors, photo sizing; all stored in user profiles.
• REST API – /api/v1/recipes, /api/v1/shopping_lists, /api/v1/plans with standard CRUD and pagination.

• Language: Python 3.10+
• Frameworks: Flask (core), SQLAlchemy, WTForms, Flask‑Login, Flask‑Mail
• Database: SQLite (dev), PostgreSQL (prod) – migrations via Flask‑Migrate
• Front‑end: Jinja2 templates, vanilla JS + Axios for API calls; CSS framework (Bootstrap/Tailwind) for responsive design
• Containerization: Official Docker image (alexbates/tamari) exposes port 4888; data persisted in a named volume.
• Testing: Pytest with Flask’s test client; CI via GitHub Actions.

The application follows a layered architecture:

1. Presentation Layer – Flask blueprints handle routing; Jinja2 renders HTML, while API endpoints return JSON.
2. Service Layer – Business logic (e.g., ingredient parsing, meal‑planner scheduling) lives in reusable service classes.
3. Data Layer – SQLAlchemy models map to tables; relationships (one‑to-many between users and recipes, many‑to-many for ingredients) are expressed via association tables.
4. Infrastructure Layer – Configurable email backend, optional Redis cache for search results, and a Celery worker can be wired in for background tasks (e.g., image processing).

This separation allows developers to swap out components (e.g., replace SQLite with MySQL) or extend functionality without touching the core.

• Self‑Hosting: A single Docker container is sufficient; the image ships with a preconfigured Flask app and uses appdata for persistence.
• Scalability: For high‑traffic scenarios, deploy behind a reverse proxy (NGINX/Traefik), use PostgreSQL with read replicas, and enable Redis caching.
• CI/CD: The repository includes Dockerfiles and GitHub Actions for automated builds; developers can fork the repo, push to their own registry, and deploy with minimal friction.
• Monitoring: Exposes Prometheus metrics via Flask‑Prometheus; logs are sent to stdout for container orchestration platforms.

• Plugins: The app exposes a simple plugin hook system where new Flask blueprints can be registered at runtime.
• Webhooks: Custom endpoints allow external services to trigger actions (e.g., add a recipe when a new blog post is published).
• API: Full CRUD with authentication tokens (JWT or session cookies) makes it straightforward to build mobile apps, CLI tools, or third‑party integrations.
• Customization: Themes and accent colors are stored in the database; developers can add new UI components by extending Jinja templates.

• Documentation: The README provides clear Docker instructions, API endpoint summaries, and a developer guide.
• Community: Active GitHub issues and pull requests indicate responsive maintainers; the GPL license encourages contribution.
• Configuration: Environment variables control everything from mail server settings to database URLs, making it easy to adapt to different hosting environments.
• Testing: The test suite covers core routes and services, giving confidence when extending the codebase.

1. Personal Kitchen Dashboard – Deploy on a Raspberry Pi or NAS to access recipes from any device, with local storage.
2. Corporate Food Service – Host on a private network; use the API to integrate with existing inventory systems or kitchen displays.
3. Recipe Blog Platform – Import thousands of recipes, expose a public API for the blog, and let users create private collections.
4. Meal‑Planning SaaS – Wrap Tamari in a front‑end framework, add multi‑tenant support, and offer subscription plans.

• Open Source & GPL – No vendor lock‑in; full source control.
• Python Ecosystem – Easy to extend with popular libraries (pandas for analytics, Pillow for image handling).
• Lightweight – A single Docker container runs on modest hardware.
• **