Grand Diomande Research · Full HTML Reader

BrewsWithBeats - Three-App Architecture Implementation Plan

This document outlines the comprehensive plan to restructure BrewsWithBeats from a unified app into three separate components:

Business Systems architecture technical paper candidate score 56 .md

Full Public Reader

BrewsWithBeats - Three-App Architecture Implementation Plan

Overview

This document outlines the comprehensive plan to restructure BrewsWithBeats from a unified app into three separate components:

1. BWBCore - Shared Swift Package (models, services, networking, theme)
2. BWB-Customer - Customer-facing iPhone/iPad app (ordering, rewards, dance)
3. BWB-POS - Staff iPad app (order queue, inventory, analytics, admin)

---

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                      BWBCore (Swift Package)                │
├─────────────────────────────────────────────────────────────┤
│  Models/           Services/           Utilities/           │
│  ├── User          ├── AuthService     ├── Logger           │
│  ├── Order         ├── SupabaseManager ├── Haptics          │
│  ├── MenuItem      ├── CartService     ├── Extensions       │
│  ├── Event         ├── OrderRepository │                    │
│  └── ...           └── ...             │                    │
├─────────────────────────────────────────────────────────────┤
│  Theme/            Networking/         Voice/               │
│  ├── Colors        ├── APIClient       ├── VoiceLogger      │
│  ├── Typography    ├── Endpoints       ├── SpeechService    │
│  └── Spacing       └── ...             └── ...              │
└─────────────────────────────────────────────────────────────┘
          │                                      │
          ▼                                      ▼
┌──────────────────────────┐    ┌──────────────────────────┐
│     BWB-Customer App     │    │       BWB-POS App        │
├──────────────────────────┤    ├──────────────────────────┤
│ Target: iPhone, iPad     │    │ Target: iPad only        │
│                          │    │                          │
│ Features:                │    │ Features:                │
│ • Menu browsing          │    │ • Order queue mgmt       │
│ • Voice ordering         │    │ • Dual-cart checkout     │
│ • Cart & checkout        │    │ • Staff authentication   │
│ • Order tracking         │    │ • Waste tracking         │
│ • Rewards & loyalty      │    │ • Inventory management   │
│ • Dance challenges       │    │ • Performance analytics  │
│ • Events calendar        │    │ • Admin dashboard        │
│ • Profile management     │    │ • Real-time updates      │
│ • HealthKit integration  │    │ • Push notifications     │
│ • Push notifications     │    │ • Daily reports          │
└──────────────────────────┘    └──────────────────────────┘

---

Phase 1: BWBCore Swift Package

1.1 Package Structure

BWBCore/
├── Package.swift
├── Sources/
│   └── BWBCore/
│       ├── Models/
│       │   ├── User.swift
│       │   ├── Order.swift
│       │   ├── MenuItem.swift
│       │   ├── Customization.swift
│       │   ├── Event.swift
│       │   ├── CartItem.swift
│       │   ├── Reward.swift
│       │   ├── WasteRecord.swift
│       │   └── StaffPerformance.swift
│       │
│       ├── Services/
│       │   ├── Auth/
│       │   │   └── AuthService.swift
│       │   ├── Supabase/
│       │   │   └── SupabaseManager.swift
│       │   ├── Repository/
│       │   │   ├── UserRepository.swift
│       │   │   ├── MenuRepository.swift
│       │   │   └── OrderRepository.swift
│       │   ├── CartService.swift
│       │   ├── RewardsService.swift
│       │   └── PushNotificationService.swift
│       │
│       ├── Networking/
│       │   ├── APIClient.swift
│       │   ├── Endpoints.swift
│       │   └── NetworkError.swift
│       │
│       ├── Theme/
│       │   ├── BWBColors.swift
│       │   ├── BWBTypography.swift
│       │   ├── BWBSpacing.swift
│       │   └── BWBShadows.swift
│       │
│       ├── Utilities/
│       │   ├── Logger.swift
│       │   ├── Haptics.swift
│       │   ├── Config.swift
│       │   └── Extensions/
│       │       ├── Color+Theme.swift
│       │       ├── Font+Theme.swift
│       │       ├── View+Shadows.swift
│       │       └── Date+Formatting.swift
│       │
│       ├── Voice/
│       │   ├── VoiceLogger.swift
│       │   ├── SpeechRecognitionService.swift
│       │   ├── TextToSpeechService.swift
│       │   └── VoiceOrderProcessor.swift
│       │
│       └── Components/
│           ├── BWBButton.swift
│           ├── BWBCard.swift
│           ├── BWBTextField.swift
│           ├── LoadingOverlay.swift
│           └── ErrorView.swift
│
└── Tests/
    └── BWBCoreTests/
        ├── ModelTests/
        ├── ServiceTests/
        └── UtilityTests/

1.2 Package.swift Configuration

swift

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "BWBCore",
    platforms: [
        .iOS(.v17),
        .macOS(.v14)
    ],
    products: [
        .library(
            name: "BWBCore",
            targets: ["BWBCore"]
        )
    ],
    dependencies: [
        .package(url: "https://github.com/supabase/supabase-swift.git", from: "2.0.0")
    ],
    targets: [
        .target(
            name: "BWBCore",
            dependencies: [
                .product(name: "Supabase", package: "supabase-swift")
            ]
        ),
        .testTarget(
            name: "BWBCoreTests",
            dependencies: ["BWBCore"]
        )
    ]
)

1.3 Files to Move to BWBCore

Current Location	New Location in BWBCore	Notes
`Models/User.swift`	`Models/User.swift`	Shared user model
`Models/Order.swift`	`Models/Order.swift`	Order model with all states
`Models/MenuItem.swift`	`Models/MenuItem.swift`	Menu item model
`Models/Customization.swift`	`Models/Customization.swift`	Drink customization
`Models/Event.swift`	`Models/Event.swift`	Events model
`Services/Auth/AuthService.swift`	`Services/Auth/AuthService.swift`	Authentication service
`Services/Supabase/SupabaseManager.swift`	`Services/Supabase/SupabaseManager.swift`	Supabase client
`Services/Repository/*.swift`	`Services/Repository/*.swift`	All repositories
`Services/CartService.swift`	`Services/CartService.swift`	Cart management
`Services/RewardsService.swift`	`Services/RewardsService.swift`	Rewards system
`Services/PushNotificationService.swift`	`Services/PushNotificationService.swift`	Push notifications
`Utilities/Logger.swift`	`Utilities/Logger.swift`	Logging utilities
`Utilities/Haptics.swift`	`Utilities/Haptics.swift`	Haptic feedback
`Utilities/Config.swift`	`Utilities/Config.swift`	Configuration
`Components/BWBDesignTokens.swift`	`Theme/BWBDesignTokens.swift`	Design tokens
`Components/BWBComponents.swift`	`Components/BWBComponents.swift`	Shared components
`Voice/*.swift`	`Voice/*.swift`	Voice ordering services

---

Phase 2: BWB-Customer App

2.1 App Structure

BWB-Customer/
├── BWB-Customer.xcodeproj
├── BWB-Customer/
│   ├── App/
│   │   ├── BWBCustomerApp.swift
│   │   └── AppDelegate.swift
│   │
│   ├── Views/
│   │   ├── Home/
│   │   │   └── HomeView.swift
│   │   ├── Menu/
│   │   │   ├── MenuView.swift
│   │   │   └── MenuItemDetailView.swift
│   │   ├── Cart/
│   │   │   └── CartView.swift
│   │   ├── Checkout/
│   │   │   ├── CheckoutView.swift
│   │   │   └── CheckoutSteps/
│   │   ├── Orders/
│   │   │   ├── OrdersView.swift
│   │   │   └── OrderDetailView.swift
│   │   ├── Rewards/
│   │   │   └── RewardsView.swift
│   │   ├── Dance/
│   │   │   ├── DanceView.swift
│   │   │   └── DanceChallengeView.swift
│   │   ├── Events/
│   │   │   └── EventsView.swift
│   │   ├── Profile/
│   │   │   └── ProfileView.swift
│   │   └── Auth/
│   │       ├── LoginView.swift
│   │       └── RegisterView.swift
│   │
│   ├── Services/
│   │   ├── DanceTrackingService.swift
│   │   └── HealthKitService.swift
│   │
│   ├── ViewModels/
│   │   ├── HomeViewModel.swift
│   │   ├── MenuViewModel.swift
│   │   └── CheckoutViewModel.swift
│   │
│   ├── Resources/
│   │   ├── Assets.xcassets
│   │   ├── Localizable.strings
│   │   └── Info.plist
│   │
│   └── Entitlements/
│       └── BWB-Customer.entitlements
│
└── BWB-CustomerTests/

2.2 Feature List

Feature	Description	Priority
Menu Browsing	Browse coffee menu with categories	P0
Voice Ordering	Order via voice commands	P0
Cart Management	Add/remove/modify items	P0
4-Step Checkout	Review → Payment → Pickup → Confirm	P0
Order Tracking	Real-time order status	P0
Rewards System	Points, tiers, redemption	P1
Dance Challenges	Earn rewards through dancing	P1
Events Calendar	View upcoming events	P2
Profile Management	User settings, preferences	P1
HealthKit Integration	Sync dance data	P2
Push Notifications	Order updates, promotions	P1

2.3 Info.plist Requirements

xml

<!-- Required Permissions -->
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is needed for voice ordering</string>

<key>NSSpeechRecognitionUsageDescription</key>
<string>Speech recognition is used for voice ordering</string>

<key>NSHealthShareUsageDescription</key>
<string>We use your activity data to track dance rewards</string>

<key>NSHealthUpdateUsageDescription</key>
<string>We record your dance activity for rewards</string>

<key>NSMotionUsageDescription</key>
<string>Motion data is used to track your dance moves</string>

---

Phase 3: BWB-POS App

3.1 App Structure

BWB-POS/
├── BWB-POS.xcodeproj
├── BWB-POS/
│   ├── App/
│   │   ├── BWBPOSApp.swift
│   │   └── AppDelegate.swift
│   │
│   ├── Views/
│   │   ├── Dashboard/
│   │   │   ├── DashboardView.swift
│   │   │   └── QueueStatsDashboard.swift
│   │   ├── Queue/
│   │   │   ├── BaristaQueueView.swift
│   │   │   └── OrderCardView.swift
│   │   ├── NewOrder/
│   │   │   ├── DualCartView.swift
│   │   │   └── QuickOrderView.swift
│   │   ├── Waste/
│   │   │   ├── WasteTrackingView.swift
│   │   │   └── WasteReportView.swift
│   │   ├── Inventory/
│   │   │   └── InventoryView.swift
│   │   ├── Analytics/
│   │   │   ├── StaffPerformanceView.swift
│   │   │   └── DailySummaryView.swift
│   │   ├── Admin/
│   │   │   ├── AdminDashboardView.swift
│   │   │   ├── StaffManagementView.swift
│   │   │   └── SettingsView.swift
│   │   └── Auth/
│   │       └── StaffLoginView.swift
│   │
│   ├── Services/
│   │   ├── QueueService.swift
│   │   ├── WasteService.swift
│   │   ├── InventoryService.swift
│   │   └── AnalyticsService.swift
│   │
│   ├── ViewModels/
│   │   ├── QueueViewModel.swift
│   │   ├── WasteViewModel.swift
│   │   └── AnalyticsViewModel.swift
│   │
│   ├── Resources/
│   │   ├── Assets.xcassets
│   │   ├── Localizable.strings
│   │   └── Info.plist
│   │
│   └── Entitlements/
│       └── BWB-POS.entitlements
│
└── BWB-POSTests/

3.2 Feature List

Feature	Description	Priority
Order Queue	Real-time order management	P0
Queue Stats Dashboard	Live metrics display	P0
Dual-Cart Checkout	Walk-in customer orders	P0
Staff Authentication	Role-based access	P0
Order Status Updates	Update order progress	P0
Waste Tracking	Log waste with reasons	P1
Staff Performance	Track individual metrics	P1
Daily Reports	End-of-day summaries	P1
Inventory Management	Track stock levels	P2
Admin Dashboard	Store management	P1
Staff Management	Manage employees	P2
Real-time Sync	Supabase realtime	P0

3.3 iPad-Specific UI Considerations

Split view navigation (master/detail)
Large touch targets for busy baristas
High contrast mode option
Landscape-optimized layouts
External keyboard support
Quick gestures (swipe to complete)

---

Phase 4: Implementation Steps

Step 1: Create BWBCore Package (Days 1-2)

1. Create `BWBCore` directory in project root
2. Initialize Swift Package with `Package.swift`
3. Create folder structure
4. Move model files with necessary imports
5. Move service files with necessary imports
6. Move utility files
7. Move theme/design token files
8. Move shared components
9. Update all `import` statements
10. Add Supabase dependency
11. Test package compilation

Step 2: Create BWB-Customer App (Days 3-4)

1. Create new Xcode project: iOS App
2. Add BWBCore as local package dependency
3. Create app structure folders
4. Move customer-facing views
5. Move customer-specific services
6. Create `BWBCustomerApp.swift` entry point
7. Configure entitlements (HealthKit, Push)
8. Configure Info.plist
9. Add asset catalogs
10. Test build and run

Step 3: Create BWB-POS App (Days 5-6)

1. Create new Xcode project: iOS App (iPad only)
2. Add BWBCore as local package dependency
3. Create app structure folders
4. Move POS-specific views
5. Move POS-specific services
6. Create `BWBPOSApp.swift` entry point
7. Configure entitlements
8. Configure Info.plist
9. Add asset catalogs
10. Test build and run

Step 4: Integration & Testing (Days 7-8)

1. Test BWBCore in both apps
2. Test authentication flow in both apps
3. Test real-time sync between apps
4. Test push notifications
5. Fix any cross-app issues
6. Optimize shared code
7. Add unit tests to BWBCore
8. Add UI tests to both apps

---

Migration Checklist

### Models Migration
- [ ] User.swift → BWBCore
- [ ] Order.swift → BWBCore
- [ ] MenuItem.swift → BWBCore
- [ ] Customization.swift → BWBCore
- [ ] Event.swift → BWBCore
- [ ] CartItem (from CartService) → BWBCore
- [ ] Reward.swift → BWBCore
- [ ] WasteRecord.swift → BWBCore
- [ ] StaffPerformance.swift → BWBCore

### Services Migration
- [ ] AuthService.swift → BWBCore
- [ ] SupabaseManager.swift → BWBCore
- [ ] UserRepository.swift → BWBCore
- [ ] MenuRepository.swift → BWBCore
- [ ] OrderRepository.swift → BWBCore
- [ ] CartService.swift → BWBCore
- [ ] RewardsService.swift → BWBCore
- [ ] PushNotificationService.swift → BWBCore

### Theme Migration
- [ ] BWBDesignTokens.swift → BWBCore/Theme
- [ ] Color+Theme.swift → BWBCore/Theme
- [ ] Font+Theme.swift → BWBCore/Theme
- [ ] Spacing constants → BWBCore/Theme
- [ ] Shadow modifiers → BWBCore/Theme

### Utilities Migration
- [ ] Logger.swift → BWBCore
- [ ] Haptics.swift → BWBCore
- [ ] Config.swift → BWBCore
- [ ] All Extensions → BWBCore

### Voice Services Migration
- [ ] VoiceLogger.swift → BWBCore
- [ ] SpeechRecognitionService.swift → BWBCore
- [ ] TextToSpeechService.swift → BWBCore
- [ ] Voice routing engine → BWBCore

### Components Migration
- [ ] BWBButton.swift → BWBCore
- [ ] BWBCard.swift → BWBCore
- [ ] BWBTextField.swift → BWBCore
- [ ] LoadingOverlay.swift → BWBCore
- [ ] ErrorView.swift → BWBCore

---

Configuration Management

Environment Variables

Both apps will read from a shared configuration:

swift

// BWBCore/Utilities/Config.swift
public enum BWBEnvironment {
    case development
    case staging
    case production

    public static var current: BWBEnvironment {
        #if DEBUG
        return .development
        #else
        return .production
        #endif
    }

    public var supabaseURL: String {
        switch self {
        case .development: return "https://dev.supabase.co"
        case .staging: return "https://staging.supabase.co"
        case .production: return "https://prod.supabase.co"
        }
    }
}

App-Specific Configurations

BWB-Customer:
- Voice ordering enabled
- HealthKit enabled
- Dance tracking enabled
- Customer-facing checkout flow

BWB-POS:
- Voice ordering disabled (optional)
- HealthKit disabled
- Staff authentication required
- Admin features enabled
- Real-time order updates

---

Database Schema Considerations

Both apps share the same Supabase database. Key tables:

Table	Used By	Description
`users`	Both	User profiles (customers & staff)
`orders`	Both	All orders
`menu_items`	Both	Menu catalog
`order_items`	Both	Line items in orders
`rewards`	Customer	Reward definitions
`user_rewards`	Customer	User's earned rewards
`waste_logs`	POS	Waste tracking records
`staff_performance`	POS	Staff metrics
`pos_configurations`	POS	POS device settings
`device_tokens`	Both	Push notification tokens

---

Testing Strategy

### Unit Tests (BWBCore)
- Model serialization/deserialization
- Service business logic
- Repository operations (mocked)
- Utility functions

### Integration Tests
- Supabase connectivity
- Authentication flows
- Real-time subscriptions

### UI Tests (Per App)
- Critical user flows
- Accessibility compliance
- Different device sizes

---

Deployment Strategy

1. BWBCore: Version-tagged releases
2. BWB-Customer: App Store (customer distribution)
3. BWB-POS: TestFlight/MDM (internal distribution)

---

Risk Mitigation

Risk	Mitigation
Breaking shared code	Comprehensive tests in BWBCore
Version drift	Semantic versioning, changelogs
Build complexity	Clear documentation, CI/CD
Feature parity issues	Shared feature flags in database

---

Next Steps

1. Review and approve this plan
2. Create progress tracking document
3. Begin Phase 1: BWBCore Package
4. Iterate through remaining phases
5. Final testing and polish

---

Document Version: 1.0
Last Updated: December 17, 2024

Promotion Decision

Promote into a technical note or architecture paper with implementation anchors.

Source Anchor

BWB/docs/ARCHITECTURE_PLAN.md

Detected Structure

Method · References · Figures · Code Anchors · Architecture