BWB — App Architecture

BWB — App Architecture

Document ID: BWB-ARCH-001
Version: 1.0.0
Last Updated: 2026-01-16

---

Overview

BWB (Brews With Beats) is a three-app coffee platform built on iOS with a shared Swift package architecture. All apps share a common codebase through BWBCore and connect to Supabase as the backend.

---

Architecture Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                      SUPABASE BACKEND                                │
│  PostgreSQL + Auth + Realtime + Storage                              │
└──────────────────────────────────┬──────────────────────────────────┘
                                   │
          ┌────────────────────────┼────────────────────────┐
          │                        │                        │
          ▼                        ▼                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  BWB-Customer   │    │    BWB-POS      │    │   BWB-Kiosk     │
│  (iPhone/iPad)  │    │    (iPad)       │    │    (iPad)       │
├─────────────────┤    ├─────────────────┤    ├─────────────────┤
│ • Menu browsing │    │ • Order queue   │    │ • Self-service  │
│ • Voice order   │    │ • POS checkout  │    │ • Voice order   │
│ • Cart/checkout │    │ • Staff auth    │    │ • QR linking    │
│ • Order track   │    │ • Waste track   │    │ • Quick order   │
│ • Rewards       │    │ • Analytics     │    │                 │
│ • Events/RSVP   │    │ • Admin panel   │    │                 │
└────────┬────────┘    └────────┬────────┘    └────────┬────────┘
         │                      │                      │
         └──────────────────────┼──────────────────────┘
                                │
                    ┌───────────▼───────────┐
                    │       BWBCore         │
                    │   (Swift Package)     │
                    ├───────────────────────┤
                    │ Models   Services     │
                    │ Theme    Utilities    │
                    │ Voice    Extensions   │
                    └───────────────────────┘

---

Platform Specifications

---

App Descriptions

BWB-Customer (iPhone/iPad)

Target: Customers ordering coffee and engaging with events

Tab Navigation:
| Tab | Function |
|-----|----------|
| Home | Welcome, quick actions, rewards summary |
| Menu | Browse, search, customize, add to cart |
| Events | DJ events, RSVP, featured lineup |
| Orders | Active orders, history, tracking |
| Profile | User info, rewards tier, settings |

Key Features:
- Voice ordering via iOS SpeechAnalyzer
- Cart management with customizations
- 4-step checkout (Review → Payment → Pickup → Confirm)
- Real-time order tracking via Supabase Realtime
- Rewards points and tier progression
- Event RSVP with guest management

Required Permissions:
- Microphone (voice ordering)
- Speech Recognition
- HealthKit (dance rewards)
- Motion (dance tracking)

BWB-POS (iPad Only)

Target: Staff and baristas managing orders

Sidebar Navigation:
| Section | Function |
|---------|----------|
| Queue | Kanban-style order status management |
| Kiosk | Voice-activated order entry |
| New Order | Walk-in POS checkout |
| Waste | Ingredient waste logging |
| Analytics | Real-time performance metrics |
| Admin | Store settings, staff management |

Key Features:
- Real-time order queue with drag-drop status updates
- Dual-cart routing for load balancing
- Staff authentication with role-based access
- Waste tracking with cost estimation
- Performance analytics and daily reports

iPad Optimizations:
- Large touch targets for speed
- Split-view navigation
- Landscape layout
- External keyboard support
- Swipe gestures for quick actions

BWB-Kiosk (iPad)

Target: Self-service ordering at events

Features:
- Voice-activated ordering
- QR code linking to mobile app
- Simplified menu interface
- Quick order flow

---

BWBCore Package Structure

BWBCore/Sources/BWBCore/
├── Models/
│   ├── User.swift          # User profiles, preferences, stats
│   ├── MenuItem.swift      # Menu items, complexity, nutrition
│   ├── Order.swift         # Orders, status, routing
│   ├── Event.swift         # Events, DJs, RSVPs
│   └── Customization.swift # Cart items, rewards, waste
├── Services/
│   ├── AuthService.swift
│   ├── SupabaseService.swift
│   ├── CartService.swift
│   └── RepositoryProtocol.swift
├── Theme/
│   ├── BWBColors.swift     # Coffee/cream/vinyl/gold palette
│   ├── BWBTypography.swift # Inter + Outfit fonts
│   └── BWBSpacing.swift
├── Voice/
│   ├── Embeddings/         # Semantic menu matching
│   ├── Slots/              # Order detail extraction
│   ├── Dialogue/           # Clarification policy
│   ├── Constraints/        # Menu rule validation
│   └── EnhancedVoiceNLUEngine.swift
└── Utilities/
    ├── Logger.swift
    ├── Haptics.swift
    └── Extensions/

---

Data Models Summary

### User
| Field | Type | Purpose |
|-------|------|---------|
| id | UUID | Primary key |
| email | String | Authentication |
| name | String | Display name |
| role | UserRole | customer/staff/manager/admin |
| preferredCart | String | Cart A or B preference |
| dietaryRestrictions | [String] | Allergen tracking |
| rewardPoints | Int | Loyalty points |
| totalOrders | Int | Order count |

### MenuItem
| Field | Type | Purpose |
|-------|------|---------|
| id | UUID | Primary key |
| name | String | Item name |
| category | MenuCategory | Espresso/Latte/etc. |
| price | Decimal | Base price |
| preparationTime | Int | Seconds to make |
| complexity | DrinkComplexity | Simple/medium/complex/premium |
| customizationOptions | [Option] | Available customizations |

### Order
| Field | Type | Purpose |
|-------|------|---------|
| id | UUID | Primary key |
| orderNumber | String | Human-readable number |
| userId | UUID | Customer reference |
| status | OrderStatus | Lifecycle state |
| assignedCart | AssignedCart | Routing destination |
| items | [OrderItem] | Line items |
| totalAmount | Decimal | Order total |

### Event
| Field | Type | Purpose |
|-------|------|---------|
| id | UUID | Primary key |
| title | String | Event name |
| date | Date | Event date |
| location | String | Venue |
| djs | [DJ] | Performing DJs |
| capacity | Int | Max attendees |
| status | EventStatus | Draft/Published/etc. |

---

Service Layer

Authentication Flow

Firebase Auth ─────▶ Supabase JWT ─────▶ App Session
                                              │
                                              ▼
                                    Role-based Access
                                    (customer/staff/admin)

Real-time Sync

Supabase Realtime
       │
       ├──▶ Order Status Updates ──▶ Customer App (tracking)
       │
       └──▶ Queue Updates ──▶ POS App (queue management)

Cart Management

CartService
    │
    ├── addItem(MenuItem, customizations)
    ├── updateQuantity(item, qty)
    ├── removeItem(item)
    ├── clearCart()
    └── checkout() ──▶ Order Creation

---

Entry Points

---

Change Log