Recipya

Recipya is a self‑hosted, full‑stack web application that manages recipes, cookbooks, and nutritional data for personal or shared use. From a developer standpoint it is built with modern Go tooling, offers an HTTP REST API, and ships as a single binary that can be containerized or compiled for Windows, Linux, and macOS. The core business logic resides in Go, while the UI is a lightweight single‑page application that consumes the API via JSON over HTTPS. This separation allows developers to replace or extend either layer without touching the other.

Technical Stack

• Language & Runtime: Go 1.22+ (compiled to a single statically‑linked binary). The codebase follows idiomatic Go patterns, using interfaces for data access and the context package for request scoping.
• Web Framework: The server uses the standard library net/http with a minimal router (chi) for routing and middleware (CORS, logging, rate limiting). No heavy frameworks are required.
• Database: SQLite is the default persistent store, but a PostgreSQL driver is also bundled. This gives developers flexibility to run Recipya in lightweight setups or production clusters.
• Template Engine: The UI is a React‑like SPA built with SvelteKit, compiled to static assets that are served by the Go backend. This keeps the front‑end lightweight and avoids server‑side rendering complexity.
• Containerization: A Dockerfile is provided, plus a devcontainer definition that includes Go tooling, node, and the full build chain. The image is built with multi‑stage builds to keep runtime size under 50 MB.

Core Capabilities & APIs

Recipya exposes a RESTful API that covers CRUD operations for recipes, ingredients, cookbooks, and measurement units. Key endpoints include:

• /api/v1/recipes – create, read, update, delete recipes; supports bulk import via JSON or Markdown.
• /api/v1/ingredients – manage ingredient catalogs, including unit conversion rules.
• /api/v1/cookbooks – group recipes and apply access control (private/public).
• /api/v1/nutrition – calculates macro‑macro values automatically using a built‑in ingredient nutrition database.

The API is self‑documenting via OpenAPI/Swagger annotations, and the documentation site hosts an interactive sandbox. Developers can also hook into scheduled jobs (cron‑style, running every three days) to trigger background tasks such as re‑importing from external sources or recalculating nutrition.

Deployment & Infrastructure

Recipya is designed for single‑instance, self‑hosted deployments. It can run as a native binary on any OS with Go runtime, or inside Docker for CI/CD pipelines. The Docker image exposes port 8080 and accepts environment variables for database URL, secret keys, and feature flags. For larger deployments, the SQLite fallback can be swapped with PostgreSQL; the migration scripts are idempotent and use goose under the hood. Because the application is stateless except for its database, horizontal scaling can be achieved by load‑balancing multiple replicas behind a reverse proxy (e.g., Traefik) and sharing the same database.

Integration & Extensibility

Recipya’s plugin architecture is currently minimal but open for future expansion. Developers can:

• Extend the API by adding new routes or middleware in Go; the modular design encourages dependency injection.
• Consume webhooks: The app can emit events (e.g., recipe updated) that external services subscribe to via a simple HTTP callback.
• Integrate with other tools: The import feature already supports parsing recipes from Mealie, Tandoor, and Nextcloud Cookbook. Additional parsers can be added by implementing the RecipeImporter interface.
• Customize UI themes: 32 built‑in themes and a CSS variable system allow developers to tweak appearance without touching the source.

Developer Experience

The project follows a well‑structured repository layout: cmd/ for binaries, internal/ for core logic, and pkg/ for shared libraries. Documentation is hosted on a dedicated site (docs.recipya.musicavis.ca) and uses MkDocs with Mermaid diagrams for architecture overviews. The community is welcoming, as indicated by the badge and open issues; contributors are guided through a CONTRIBUTING.md that details linting, testing, and PR guidelines. Continuous integration with GitHub Actions ensures every push passes Go vetting, tests, and static analysis.

Use Cases

• Home‑brew recipe manager: A developer can host Recipya on a Raspberry Pi, expose it via VPN, and use the API to sync recipes across devices.
• Small business kitchen: A catering service can run Recipya on a Docker Swarm, use the nutrition API to generate menus, and integrate with their ordering system via webhooks.
• Academic research: Nutritionists can extend the ingredient database, run batch calculations, and expose results through a custom dashboard.

Advantages Over Alternatives

• Performance & Footprint: A single Go binary with SQLite keeps memory usage low; no JVM or Node runtime is required.
• Licensing: Recipya is MIT‑licensed, allowing unrestricted use in commercial or closed source projects.
• Extensibility: The clean separation of API and UI, combined with Go’s interface‑driven design, makes it straightforward to add features or replace components