RecipeSage

RecipeSage is a full‑stack, self‑hosted solution for managing recipes, meal plans, and shopping lists. From a developer’s perspective it behaves like a modern single‑page application (SPA) backed by a REST/GraphQL API that exposes every domain entity—recipes, tags, meal plans, and shopping lists. The front‑end is written in Vue 3 with Pinia for state management, while the back‑end is a Node.js/TypeScript service built on Express and Prisma ORM. The database layer can be swapped between PostgreSQL, MySQL or SQLite via a simple environment variable, making it ideal for both lightweight dev environments and production deployments.

Architecture & Technical Stack

• Front‑end: Vue 3 + Pinia, Vite build tooling, TypeScript. The SPA consumes a GraphQL endpoint for all CRUD operations and uses WebSockets (via Socket.io) for real‑time updates on shared meal plans. The UI is fully responsive and supports PWA installation, enabling offline usage through Service Workers.
• Back‑end: Express.js (Node 14+) wrapped in a TypeScript codebase. The API layer is split into modular routers, each exposing strongly‑typed request/response contracts. Prisma acts as the ORM; migrations are versioned in Git and can be run via prisma migrate. Authentication is JWT‑based, with optional OAuth2 support for third‑party login providers.
• Database: PostgreSQL is the recommended engine, but Prisma supports MySQL and SQLite out of the box. The schema includes tables for recipes, ingredients, tags, meal_plans, and a many‑to‑many relation table for shared lists.
• Containerization: A fully‑featured docker-compose.yml ships with the self‑host repo, exposing separate services for the API, front‑end, and a reverse proxy (Traefik). The image layers are lightweight (node:18-alpine for the API, nginx:alpine for static assets) and include health‑check endpoints.

Core Capabilities & Developer APIs

• Recipe Import: A background worker (written in Go, bundled as a Docker container) scrapes any URL or PDF and normalizes it into the RecipeSage schema. The worker exposes a simple HTTP API (/import) that accepts raw HTML or a URL, returning the parsed recipe object. Developers can hook into this endpoint to build custom import pipelines.
• Search & Tagging: The API offers a full‑text search endpoint (/search) powered by PostgreSQL’s tsvector. It supports fuzzy matching, typo tolerance, and field‑specific queries. Tagging is a many‑to‑many relationship; the API exposes CRUD endpoints for tags and allows bulk assignment.
• Meal Planning: Drag‑and‑drop scheduling is implemented via a calendar component that communicates with the API using GraphQL subscriptions. Developers can expose their own calendar integrations (e.g., Google Calendar) by consuming the GraphQL mutation addMealToPlan.
• Shopping List Aggregation: The back‑end aggregates ingredients across selected recipes, grouping by category and unit. An API endpoint (/shopping-list) returns the consolidated list in JSON or CSV format, ready for consumption by external services.
• Webhooks & Extensibility: RecipeSage supports outgoing webhooks on events such as recipe.created, mealplan.updated. The webhook payload is JSON and can be verified via HMAC signatures. This makes it trivial to integrate with CI/CD pipelines, notification services, or custom dashboards.

Deployment & Infrastructure

The recommended deployment pattern is a single Docker Compose stack:

services:
  api:
    image: recipesage/api:latest
    environment:
      - DATABASE_URL=postgres://user:pass@db/recipesage
  frontend:
    image: recipesage/frontend:latest
    environment:
      - VUE_APP_API_URL=http://api:3000/graphql
  db:
    image: postgres:15

The stack scales horizontally by replicating the api service behind a load balancer; Prisma’s connection pool handles multiple instances. For high‑availability, you can run the database in a PostgreSQL cluster (Patroni) and use Traefik’s sticky session routing. The PWA capabilities mean that once the front‑end is cached, users can still view their data offline, reducing load on the API during peak hours.

Integration & Extensibility

• Plugin System: While RecipeSage does not ship a formal plugin API, its modular architecture allows developers to fork the repository and add new routes or middleware. The plugins/ directory is a convention for placing such extensions, and the Docker Compose file exposes an environment variable to mount additional code.
• API Clients: Official SDKs are available in JavaScript/TypeScript, but the GraphQL schema is self‑documenting via introspection. Developers can generate clients in any language using tools like graphql-codegen or Apollo.
• Custom Importers: The import worker accepts a plugin interface (Importer) that can be implemented in Go or Node. This lets teams create custom parsers for niche formats (e.g., proprietary recipe file types).
• Webhooks: Developers can subscribe to events via a simple HTTP endpoint, enabling integrations with Slack, Discord, or custom dashboards.

Developer Experience

The project follows clean code practices: TypeScript everywhere, linting with ESLint/Prettier, and CI pipelines that run tests, build artifacts, and Docker image scans. Documentation is hosted at `docs.recipesage.com