Shaker Mobile App - Technical Documentation

Shaker Mobile App - Technical Documentation

Welcome to the technical documentation for Shaker, the mobile application component of the Bartendie home bar management system.

Overview

Shaker is a React Native mobile application built with Expo that enables cocktail enthusiasts to manage their home bar inventory, discover and create recipes, plan events, and generate shopping lists. The app features a modern NeoBrutalism design system (RetroUI) and integrates with the Well backend for data persistence and real-time updates.

Quick Links

• System Overview - Architecture, tech stack, and domain concepts
• Navigation & Routing - App structure and navigation patterns
• Component Architecture - UI components and design patterns
• Styling & Theming - RetroUI design system and NativeWind

Technology Stack

Core Technologies

• React Native - Cross-platform mobile framework
• Expo (SDK 54) - Development platform and tooling
• TypeScript - Type-safe development
• Expo Router - File-based navigation

State Management & Data

• Apollo Client - GraphQL client and state management
• GraphQL - API communication with Well backend
• Local Data Layer - TypeScript-based data structures for recipes, ingredients, products
• MMKV (react-native-mmkv) - Fast on-device persistence for domain data

Styling

• NativeWind - Tailwind CSS for React Native
• RetroUI Design System - NeoBrutalism design tokens and components
• Tailwind Variants - Type-safe component styling

Backend Integration

• Well - Elixir/Phoenix GraphQL backend
• Phoenix Channels - Real-time subscriptions
• Clerk - Authentication and user management

Key Features

• Barcode Scanning - expo-camera for UPC lookup
• Image Handling - expo-image for optimized images
• Secure Storage - expo-secure-store for sensitive data
• Haptic Feedback - expo-haptics for tactile responses
• Keep Awake - expo-keep-awake keeps screen on during bar service

App Structure

shaker/
├── app/                    # Expo Router screens
│   ├── (tabs)/            # Tab navigation screens
│   │   ├── index.tsx      # Dashboard
│   │   ├── events/        # Event planning (+ batch management)
│   │   ├── recipes/       # Recipe management (+ batch cocktails, make flow)
│   │   ├── inventory/     # Inventory tracking (+ products, ingredients, shopping)
│   │   ├── settings/      # App settings + user profile
│   │   └── venues/        # Venue management (hidden tab)
│   ├── terms/             # Privacy policy and terms of service
│   ├── _layout.tsx        # Root layout (fonts, hydration, keep-awake)
│   └── modal.tsx          # Modal screens
├── components/            # Reusable UI components (+ batch/, recipes/, tags/, skeletons/)
├── data/                  # Local data layer
├── infra/                 # Infrastructure (Clerk, MMKV storage, hooks)
├── lib/                   # Business logic utilities
├── services/              # External services (UPC lookup)
├── store/                 # Lightweight in-memory stores (make completion state)
├── styles/                # Design system and themes
├── types/                 # TypeScript type definitions
└── utils/                 # Helper functions

Core Concepts

Domain Model

Shaker follows Domain-Driven Design principles aligned with the Bartendie domain:

• Recipes - Cocktail recipes with ingredients, instructions, and metadata
• Ingredients - Abstract ingredient concepts (e.g., “Vodka”, “Lime Juice”)
• Products - Physical items in inventory (e.g., “Tito’s Vodka 750ml”)
• Inventory - Stock tracking for products, equipment, glassware, tools
• Events - Occasions with menus, guest lists, and bar setups
• Shopping Lists - Auto-generated procurement lists based on recipes and events

Key Distinctions

• Ingredient vs Product: Ingredients are abstract concepts; Products are specific physical items
• Recipe Ingredients: Recipes reference ingredient names, which map to products in inventory
• Flavor Profiles: 8-dimensional flavor vectors for ingredient matching and substitutions

Getting Started

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm
• Expo CLI
• iOS Simulator (Mac) or Android Emulator

Development Setup

# Navigate to shaker directory
cd shaker

# Install dependencies
pnpm install

# Start development server
pnpm start

# Run on iOS
pnpm ios

# Run on Android
pnpm android

Testing

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run with coverage
pnpm test:coverage

Documentation Sections

Architecture & Setup

1. System Overview - High-level architecture, tech stack, local storage layer
2. Navigation & Routing - Expo Router, screen structure, Make Recipe flow, Batch Cocktails
3. Component Architecture - Component patterns and organization

Design & UI

4. Styling & Theming - RetroUI design system and NativeWind

Features (Coming Soon)

• Recipe Management - Recipe CRUD, batch scaling, make-a-recipe flow
• Inventory & Products - Inventory tracking, barcode scanning, import/export
• Shopping Lists - Auto-generation and consolidation
• Cost Analytics - Price tracking and spending analytics

Data & State (Coming Soon)

• State Management - Apollo Client and data flow
• Authentication - Clerk integration and security

Development (Coming Soon)

• Custom Hooks - Reusable hooks and utilities
• Development & Testing - Dev workflow and testing practices
• Deployment & Builds - Expo builds and deployment

Integration (Coming Soon)

• Real-time Features - Phoenix channels and subscriptions
• Backend Integration - Well backend and GraphQL

Contributing

When contributing to Shaker documentation:

1. Follow the existing documentation style and format
2. Include code examples for new features
3. Update cross-references when adding new sections
4. Test all code examples against the current codebase
5. Update the “Last modified” date in YYYY-MM-DD format

Last Modified

2026-03-06