System Architecture

System Architecture

React + Elixir/Phoenix Backend with Event Sourcing

This document outlines a comprehensive architecture for a bar inventory and event management system using React with barcode scanning on the frontend and Elixir/Phoenix with Event Sourcing for the backend.

System Architecture Overview

Frontend (React with Scandit)

1. Main Application

   • User authentication module
   • Dashboard for quick inventory status and upcoming events
   • Navigation to scanning, inventory, event planning, and recipe screens

2. Barcode Integration

   • A component for barcode scanning
   • Custom UI overlay for bar-specific actions:
     • “Add to inventory” flow
     • “Set bottle level” flow
     • “Restock” flow
     • “Add to bar setup” flow

3. Key Screens

   • Dashboard (overview of events, inventory status, and shortcuts)
   • Event planning screen (create/edit events, themes, guest lists)
   • Menu design screen (create/edit menus for events)
   • Inventory screen (current stock levels)
   • Scan screen (for adding/using products)
   • Recipe management screen (browse, create, edit recipes)
   • Batch preparation screen (scale recipes for events)
   • Bar setup screen (manage tools, equipment, and glassware)
   • Reports screen (usage trends, popular drinks, event analytics)

Backend (Elixir/Phoenix with Event Sourcing)

1. Core Domains

   • Event Planning Domain: Managing events, themes, guests, and attendance
   • Menu Management Domain: Creating and organizing drink menus
   • Recipe Management Domain: Defining and maintaining cocktail recipes
   • Inventory Domain: Tracking products, ingredients, and generating shopping lists
   • Bar Setup Domain: Managing tools, equipment, and glassware

2. Core Aggregates

   • Event - Root entity for gatherings with themes, guest lists, and menus
   • Menu - Collections of drink items designed for events
   • Recipe - Definitions for cocktails with ingredients and preparation details
   • Inventory - Management of all available ingredients and products
   • BarSetup - Physical arrangement and tools needed for events
   • BatchedCocktail - Scaled recipes prepared in advance for events

3. Event Sourcing Components

   • Commands: Represent user intentions (CreateEvent, AddToInventory, etc.)
   • Events: Record state changes (EventCreated, InventoryItemAdded, etc.)
   • Aggregates: Enforce business rules and emit events
   • Projections: Build read models from event streams
   • Process Managers: Coordinate workflows across aggregates

4. Phoenix Contexts

   • Events context for event planning and guest management
   • Menus context for menu creation and drink suggestions
   • Recipes context for recipe creation, management, and batching
   • Inventory context for product and stock management
   • BarSetup context for managing tools, equipment, and glassware
   • Analytics context for reports and insights
   • Accounts context for user management

5. LiveView Components (for admin dashboard)

   • Real-time inventory monitoring
   • Low stock alerts
   • Upcoming event calendar
   • Event preparation progress tracking
   • Usage analytics graphs

6. API Endpoints (for mobile app)

   • GraphQL API to serve the React app
   • Authentication endpoints (JWT)
   • Product lookup by barcode
   • Inventory management endpoints
   • Recipe and menu endpoints
   • Event planning endpoints
   • Batch calculation endpoints

Data Flow

1. Event Planning Process

   • User creates an event with theme, date, and expected guests
   • System tracks guest RSVPs and preferences
   • Attendance estimates are generated for planning purposes

2. Menu Design Process

   • User creates menus for events with selected recipes
   • System suggests drinks based on guest preferences and inventory
   • Menu balance is analyzed for flavor diversity

3. Recipe Management Process

   • User browses, creates, and edits cocktail recipes
   • System maintains ingredient lists and preparation instructions
   • Recipes can be tagged for easy organization

4. Batch Preparation Process

   • User selects recipes to batch for an event
   • System calculates scaled ingredients and adjustments
   • Batch tracking monitors freshness and remaining servings

5. Scanning Process

   • User scans bottle with Scandit
   • App looks up product by barcode in local cache first
   • If not found, queries Phoenix backend
   • Shows product details and action options (add/use/restock)

6. Inventory Management Process

   • When products are scanned and used, transactions are recorded
   • Backend updates inventory levels in real-time
   • System generates shopping lists based on planned menus and current inventory
   • LiveView components reflect changes immediately for managers

7. Bar Setup Process

   • User defines bar layout and required tools for events
   • System verifies tool availability and suggests alternatives
   • Setup instructions guide event preparation

Event Sourcing Implementation

The system uses event sourcing to maintain a complete history of all domain events. This approach:

1. Records all changes as events:

   • Every state change is captured as an immutable event
   • Events are stored in chronological order in an event store

2. Rebuilds state from events:

   • Aggregates load their state by replaying events
   • Current state is a function of all past events

3. Provides complete audit trail:

   • All actions and changes are preserved
   • System state can be reconstructed for any point in time

4. Enables advanced analytics:

   • Historical data is available for trend analysis
   • Event patterns can reveal insights about usage and behavior

5. Supports eventual consistency:

   • Read models are updated asynchronously
   • Projections transform events into queryable views

Technology Stack

• Frontend: React with Vite, TypeScript, Tailwind CSS, shadcn/ui
• Backend: Elixir/Phoenix with Commanded for event sourcing
• Database: PostgreSQL for both event store and read models
• API: GraphQL with Absinthe
• Testing: Vitest for frontend, ExUnit for backend
• Deployment: Docker containers with CI/CD pipeline

Database Schema Design

Core Entities

Event Schema

id: uuid
name: string
date: datetime
description: text
expected_guest_count: integer
status: enum (planned, in_progress, completed, cancelled)
theme_id: uuid (foreign key)
created_at: timestamp
updated_at: timestamp

Theme Schema

id: uuid
name: string
color_scheme: string
style: string
description: text
suggested_ingredients: jsonb
created_at: timestamp
updated_at: timestamp

Guest Schema

id: uuid
event_id: uuid (foreign key)
name: string
email: string
preferred_spirits: array[string]
disliked_ingredients: array[string]
favorite_cocktails: array[string]
allergies: array[string]
rsvp_status: enum (invited, confirmed, declined, maybe, no_response)
created_at: timestamp
updated_at: timestamp

Menu Schema

id: uuid
name: string
description: text
event_id: uuid (foreign key)
is_final: boolean
created_at: timestamp
updated_at: timestamp

DrinkItem Schema

id: uuid
menu_id: uuid (foreign key)
recipe_id: uuid (foreign key)
name: string
description: text
category: enum (signature, classic, mocktail, etc.)
is_featured: boolean
image_url: string
created_at: timestamp
updated_at: timestamp

Recipe Schema

id: uuid
name: string
description: text
author: string
creation_date: datetime
instructions: text
prep_time: interval
glass_type: enum (coupe, rocks, highball, etc.)
ice_type: enum (cube, sphere, crushed, etc.)
garnish_instructions: text
rating: float
image_url: string
created_at: timestamp
updated_at: timestamp

RecipeIngredient Schema

id: uuid
recipe_id: uuid (foreign key)
ingredient_id: uuid (foreign key)
quantity: float
unit: enum (oz, ml, dash, etc.)
is_optional: boolean
substitute_group: string
created_at: timestamp
updated_at: timestamp

BatchRecipe Schema

id: uuid
base_recipe_id: uuid (foreign key)
serving_count: integer
batch_instructions: text
prep_time: interval
dilution_factor: float
stability_duration: interval
created_at: timestamp
updated_at: timestamp

Product Schema

id: uuid
barcode: string
name: string
brand: string
type: enum (spirit, wine, beer, mixer, etc.)
category: string (vodka, gin, rum, etc.)
alcohol_content: float
volume: float
volume_unit: enum (oz, ml, liter, etc.)
current_amount: float
current_unit: enum (oz, ml, liter, etc.)
percentage_full: float
is_low: boolean
is_empty: boolean
cost_price: decimal
selling_price: decimal
supplier_id: uuid (foreign key)
storage_location: string
expiration_date: date
image_url: string
created_at: timestamp
updated_at: timestamp

Ingredient Schema

id: uuid
name: string
type: enum (spirit, mixer, modifier, sweetener, garnish, other)
current_stock: float
unit: enum (oz, ml, count, etc.)
storage_location: string
product_id: uuid (foreign key, optional)
created_at: timestamp
updated_at: timestamp

ShoppingList Schema

id: uuid
event_id: uuid (foreign key)
generated_date: datetime
status: enum (draft, final, in_progress, completed)
guest_count: integer
created_at: timestamp
updated_at: timestamp

ShoppingItem Schema

id: uuid
shopping_list_id: uuid (foreign key)
ingredient_id: uuid (foreign key, optional)
product_id: uuid (foreign key, optional)
tool_id: uuid (foreign key, optional)
equipment_id: uuid (foreign key, optional)
quantity: float
unit: enum (oz, ml, count, etc.)
is_optional: boolean
is_purchased: boolean
barcode: string
created_at: timestamp
updated_at: timestamp

BarSetup Schema

id: uuid
event_id: uuid (foreign key)
layout: text
setup_instructions: text
created_at: timestamp
updated_at: timestamp

BarTool Schema

id: uuid
name: string
type: enum (shaker, strainer, jigger, etc.)
quantity: integer
is_essential: boolean
category_id: uuid (foreign key)
barcode: string
created_at: timestamp
updated_at: timestamp

Equipment Schema

id: uuid
name: string
type: enum (blender, ice_crusher, carbonator, etc.)
quantity: integer
is_essential: boolean
category_id: uuid (foreign key)
barcode: string
created_at: timestamp
updated_at: timestamp

Glassware Schema

id: uuid
type: enum (coupe, rocks, highball, etc.)
quantity: integer
is_essential: boolean
barcode: string
created_at: timestamp
updated_at: timestamp

BatchedCocktail Schema

id: uuid
recipe_id: uuid (foreign key)
event_id: uuid (foreign key)
batch_recipe_id: uuid (foreign key)
creation_time: datetime
expiration_time: datetime
storage_instructions: text
serving_instructions: text
remaining_servings: integer
created_at: timestamp
updated_at: timestamp

Tag Schema

id: uuid
name: string
type: enum (occasion, season, flavor, technique, etc.)
created_at: timestamp
updated_at: timestamp

Taggable Schema (polymorphic)

id: uuid
tag_id: uuid (foreign key)
taggable_id: uuid
taggable_type: string
created_at: timestamp
updated_at: timestamp

Transaction Schema

id: uuid
product_id: uuid (foreign key, optional)
ingredient_id: uuid (foreign key, optional)
quantity: float
unit: string
transaction_type: string (addition, usage, waste, etc.)
user_id: uuid (who performed the action)
recipe_id: uuid (optional, if used in a recipe)
event_id: uuid (optional, if related to an event)
notes: text
timestamp: timestamp

Technical Implementation Details

React + Scandit

• Implement offline-first approach with local storage
• Cache product data for fast lookup even without network
• Implement batch syncing for when connectivity is restored
• Use Scandit’s MatrixScan for batch scanning during restocking
• Handle low-light scanning conditions typical in bar environments
• Customize the scanning UI for easy one-handed operation
• Develop intuitive event planning and menu creation interfaces
• Implement flavor profile visualization for balanced menu design

Elixir/Phoenix Backend with Event Sourcing

• Use domain-driven design with clearly defined bounded contexts
• Implement event sourcing using Commanded framework
• Store events in EventStore with PostgreSQL
• Create projections for read models using Ecto
• Use Phoenix PubSub for real-time inventory and event updates
• Create GenServers for handling background jobs like notifications
• Set up periodic inventory checks to alert on low stock
• Use Phoenix LiveView for real-time admin dashboard
• Implement GraphQL API with Absinthe for flexible mobile queries
• Develop batch scaling algorithms for cocktail preparation
• Implement proper context boundaries for maintainable code

Integration Points

• GraphQL API for flexible communication between frontend and backend
• WebSockets for real-time updates to inventory, events, and menus
• Secure authentication using JWT tokens
• API versioning for future compatibility
• Phoenix Channels for real-time communication
• Barcode scanning integration with product database
• External calendar integration for event planning

Deployment Architecture

• Web app distributed through standard web hosting
• Phoenix backend deployed on cloud service with PostgreSQL database
• Implement CQRS pattern for read/write optimization
• Consider containerization for easy deployment and scaling
• Set up CI/CD pipeline for both frontend and backend
• Implement automated backups and disaster recovery
• Configure monitoring and alerting for system health

Security Considerations

• Role-based access control (RBAC) for different staff levels
• Encrypt sensitive data in transit and at rest
• Implement proper authentication and authorization
• Regular security audits and updates
• Consider compliance with local regulations regarding alcohol inventory
• Secure guest data with appropriate privacy controls
• Implement API rate limiting to prevent abuse

Future Expansion

• Integration with POS systems
• Automatic reordering based on inventory levels
• Customer-facing drink menu app that shows available drinks
• AI-powered drink recommendations based on inventory and guest preferences
• Sales analytics and predictive modeling
• Voice commands for hands-free operation during busy events
• Augmented reality overlay for bar setup guidance
• Integration with smart devices (scales, automatic pourers)

Implementation Phases

1. Phase 1: Core Functionality

   • Basic inventory management
   • Barcode scanning with Scandit
   • Simple recipe database
   • Event and menu creation

2. Phase 2: Enhanced Features

   • Real-time inventory updates
   • Recipe suggestions and menu balancing
   • Basic reporting
   • Shopping list generation
   • Batch recipe calculation

3. Phase 3: Advanced Features

   • Advanced analytics
   • Integration with suppliers
   • Guest preference tracking
   • AI-driven inventory optimization
   • Bar setup optimization
   • Mobile ordering for guests