Bar Assistant

Bar Assistant is a purpose‑built, self‑hosted API server that powers cocktail recipe management. From a developer’s perspective it exposes a comprehensive RESTful interface for CRUD operations on recipes, ingredients, bars, users, and related entities. The API is versioned, fully documented through OpenAPI/Swagger, and supports fine‑grained authentication via personal access tokens and SSO. All business logic—ABV calculations, price estimation, substitute handling, and inventory‑based filtering—is encapsulated in the server, allowing client applications (e.g., Salt Rim or custom UIs) to remain lightweight and focused on presentation.

Architecture

• Language & Framework: PHP 8.2 with the Symfony framework (v6). Symfony’s modular architecture, Doctrine ORM, and built‑in security components give the application a solid foundation for rapid feature addition.
• Database: PostgreSQL 14 is the primary datastore, providing robust relational features (JSONB columns for flexible metadata, full‑text indexes). Doctrine handles schema migrations and query building.
• Search: Meilisearch 1.x is integrated for instant full‑text filtering of recipes and ingredients. The API exposes endpoints to re‑index data, while the server auto‑updates indices on CRUD events.
• Containerization: A ready‑made Docker image (barassistant/server) is available on Docker Hub and GHCR. The image uses a multi‑stage build to keep runtime size minimal, exposing only the API port (default 80) and supporting environment‑based configuration.

Core Capabilities

• Ingredient & Recipe Management: CRUD endpoints, batch import via JSON/YAML/URL, and advanced filtering (ABV range, tags, glass types).
• Inventory & Shopping: Endpoint to mark owned ingredients per bar; automatic shopping list generation for missing items.
• Pricing: Multi‑currency ingredient pricing, automatic cocktail price calculation based on ingredient costs and pours.
• Substitutions & Variations: API to define substitute chains and recipe variations, enabling dynamic recommendation logic.
• User & Role System: JWT‑based auth with role hierarchies (admin, editor, viewer) and per‑token permission scopes.
• Export/Import: CSV, JSON, YAML exports; bulk import of collections from external sites.
• Analytics: Endpoints for recipe popularity, user taste statistics, and bar usage metrics.

Deployment & Infrastructure

Bar Assistant is designed for self‑hosting on any Linux server that can run Docker or a native PHP environment. Key deployment considerations:

• Scalability: Stateless API containers allow horizontal scaling behind a load balancer. PostgreSQL can be sharded or read‑replicated for high read throughput.
• Persistence: Docker volumes persist database data; Meilisearch can be externalized for durability.
• CI/CD: The repository includes GitHub Actions that build Docker images, run tests, and push to registries automatically.
• Monitoring: Exposes Prometheus metrics; can be integrated with Grafana dashboards.

Integration & Extensibility

• Plugin System: While the core does not expose a formal plugin API, developers can fork the repository or use Symfony’s bundle system to add custom bundles (e.g., new authentication providers, external recipe scrapers).
• Webhooks: Event hooks are available for key actions (recipe created, inventory updated) allowing integration with external services such as Slack or home automation platforms.
• SDKs: No official SDKs exist yet, but the OpenAPI spec can be used to generate client libraries in any language.

Developer Experience

• Documentation: The official docs (docs.barassistant.app) cover API usage, data models, authentication flows, and example queries. Swagger UI is accessible at /docs.
• Community: The project is hosted on GitHub with an active issue tracker. Contributors are encouraged to submit PRs; the maintainers run tests on every pull request.
• Configuration: All settings are environment‑driven (APP_ENV, DATABASE_URL, MEILISEARCH_HOST, etc.), making it straightforward to adapt for development, staging, or production.

Use Cases

1. Custom Mobile App – Build a native iOS/Android app that consumes the API for on‑the‑go recipe lookup and inventory tracking.
2. Embedded Kiosk – Deploy the API on a Raspberry Pi behind a touch screen for a bar’s self‑service menu.
3. Enterprise Integration – Combine with ERP systems to pull ingredient prices and update cocktail pricing automatically.
4. Analytics Dashboard – Use the stats endpoints to feed a Power BI or Grafana dashboard for bar performance monitoring.

Advantages

• Domain‑Specific Features: Unlike generic recipe managers, Bar Assistant offers cocktail‑centric logic (ABV, pour costs, substitute chains) out of the box.
• Open Source & Self‑Hosted: Full control over data, compliance with privacy regulations, and no vendor lock‑in.
• Performance: Symfony’s HTTP cache, Meilisearch indexing, and PostgreSQL full‑text search provide fast responses even with large recipe collections.
• Extensibility: Symfony’s bundle architecture and the ability to expose webhooks make it easy to tailor the system to niche workflows.

In summary, Bar Assistant delivers a feature‑rich, API‑first solution for cocktail recipe management that is technically robust, highly configurable, and well suited to developers who need a self‑hosted, domain‑specific backend.