# graphefruit/beanconqueror architecture

> Architecture diagram of the GitHub repository graphefruit/beanconqueror, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/graphefruit/beanconqueror
- Repository: https://github.com/graphefruit/beanconqueror

## Overview

##### Project Type and Purpose
- Beanconqueror is a cross-platform mobile application (iOS & Android) built with the Ionic framework (Angular) and Capacitor.
- Its goal is to let coffee aficionados record, track, and optimize every stage of their coffee journey—from green-bean management and roasting, through brewing and cupping, to data export and integration with Bluetooth devices and Apple Health.

##### File Structure & Architectural Patterns
- Top-Level Folders
– android/, ios/: Native platform projects generated by Capacitor.
– src/: The entire Ionic/Angular client, subdivided into app modules, pages, components, services, classes, directives, pipes, etc.
– capacitor.config.ts: Configures Capacitor plugins and app IDs.
– e2e/, hooks/: End-to-end tests and build/deploy hooks.
- Angular Modularization
– src/app/*.module.ts and routing modules define feature boundaries: beans, brew, roasting-section, water-section, etc.
– Each feature folder contains pages, subcomponents, popovers, and routing for that domain.
– Shared services under src/services handle data persistence, device communication, analytics, and UI helpers.
- Native Bridging
– capacitor plugins and custom native code live under android/ and ios/, plus native-calls-plugin in src/native and src/classes/devices.
– Bluetooth communication and file system access are provided via Capacitor’s native bridge.
- Data Flow Patterns
– UI Components → Angular Services (business logic) → Storage (Ionic Storage/SQLite, FileSystem via Capacitor) and Device APIs (Bluetooth, Camera, FileSystem) → Native platform → External systems (Apple Health, optional analytics server).

##### How to Represent This
1. Mobile UI Layer (Angular pages & components)
2. Angular Business Logic Layer (Services, Classes, Mappers)
3. Data Layer
- Local Storage (Ionic Storage / SQLite)
- File System (images, exports)
4. Device Integration Layer (Capacitor Plugins)
- Bluetooth device service
- Native calls plugin
5. Native Platforms
- Android project (Java/Kotlin)
- iOS project (Swift/Objective-C)
6. External Integrations
- Apple Health
- Analytics & optional server-communication
- User taps UI → Component invokes Service → Service reads/writes Local Storage or calls Device Integration → Capacitor Bridge → Native Platform → Bluetooth device or FileSystem
- Services may post events back to UI (Observables) or trigger navigation.
- Data export/import flows through FileSystem to share files.
- Analytics calls flow from Services → HTTP (optional) → Analytics endpoint.
- Apple Health calls flow from Services → Capacitor Bridge → iOS HealthKit.
c. Key Architectural Patterns
- Modular feature organization (Angular modules + lazy routing)
- Separation of concerns: UI (components) vs. business logic (services) vs. persistence (storage)
- Observer pattern (RxJS) for real-time updates (e.g., live brew graphs)
- Bridge pattern (Capacitor) for platform-specific capabilities
d. Technologies & Frameworks
- Ionic & Angular (UI, routing, modules, components)
- Capacitor (native bridge, plugins)
- SQLite / Ionic Storage (persistent data)
- Bluetooth LE (via Capacitor plugins + custom native device classes)
- Apple HealthKit (iOS)
- FileSystem & Camera plugins
- RxJS for reactive data flows

##### Detail & Granularity
- Major services under the business logic layer (e.g., uiBeanStorage, server-communication, qr-scanner)
- How native-calls-plugin links the Angular layer to android/BCAndroidNativeCallsPlugin.java and AppDelegate.swift
- Essential device classes (e.g., AcaiaScale, DecentScale) under the Device Integration layer

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Mobile UI Layer"
        BeansModule["Beans Module"]:::ui
        BrewModule["Brew Module"]:::ui
        RoastingModule["Roasting Section Module"]:::ui
        WaterModule["Water Section Module"]:::ui
        GraphModule["Graph Section Module"]:::ui
    end

    subgraph "Business Logic Layer"
        BeanStorage["Bean Storage Service"]:::logic
        BrewStorage["Brew Storage Service"]:::logic
        GreenBeanStorage["Green-Bean Storage Service"]:::logic
        GraphStorage["Graph Storage Service"]:::logic
        PreparationStorage["Preparation Storage Service"]:::logic
        WaterStorage["Water Storage Service"]:::logic
        ServerComm["Server Communication Service"]:::logic
        AnalyticsHelper["Analytics Helper Service"]:::logic
        ExcelExport["Excel Export Service"]:::logic
    end

    subgraph "Data Layer"
        UnifiedStorage["Unified Storage Service"]:::data
        FileHelper["File System Helper"]:::data
    end

    subgraph "Device Integration Layer"
        BluetoothService["Bluetooth Device Service"]:::bridge
        NativePluginAngular["Native Calls Plugin (Angular)"]:::bridge
    end

    subgraph "Native Platforms"
        AndroidPluginEntry["Android Native Plugin Entry"]:::native
        AndroidMainActivity["Android Main Activity"]:::native
        iOSAppDelegate["iOS AppDelegate"]:::native
    end

    subgraph "External Integrations"
        AppHealth["Apple HealthKit"]:::external
        AnalyticsEndpoint["Analytics Endpoint"]:::external
        AnalyticsPopover["Analytics Popover Component"]:::external
        ProtoDef["bean.proto"]:::external
        ProtoTs["bean.ts"]:::external
    end

    BeansModule -->|invokes| BeanStorage
    BrewModule -->|invokes| BrewStorage
    RoastingModule -->|invokes| GreenBeanStorage
    RoastingModule -->|invokes| PreparationStorage
    WaterModule -->|invokes| WaterStorage
    GraphModule -->|invokes| GraphStorage

    BeanStorage -->|reads/writes| UnifiedStorage
    BrewStorage -->|reads/writes| UnifiedStorage
    GreenBeanStorage -->|reads/writes| UnifiedStorage
    GraphStorage -->|reads/writes| UnifiedStorage
    PreparationStorage -->|reads/writes| UnifiedStorage
    WaterStorage -->|reads/writes| UnifiedStorage

    ExcelExport -->|exports to| FileHelper

    BluetoothService -->|calls| NativePluginAngular
    ServerComm -->|HTTP calls| AnalyticsEndpoint
    AnalyticsHelper -->|triggers| AnalyticsEndpoint
    ServerComm -->|uses| ProtoDef
    ServerComm -->|uses| ProtoTs
    AnalyticsHelper -->|opens| AnalyticsPopover

    NativePluginAngular -->|bridges| AndroidPluginEntry
    NativePluginAngular -->|bridges| iOSAppDelegate
    AndroidPluginEntry -->|runs on| AndroidMainActivity
    iOSAppDelegate -->|writes to| AppHealth

    classDef ui fill:#D0E6FF,stroke:#0366d6
    classDef logic fill:#DFFFE0,stroke:#28a745
    classDef data fill:#FFE5B4,stroke:#FFA500
    classDef bridge fill:#E0E0E0,stroke:#666666
    classDef native fill:#C0C0C0,stroke:#333333
    classDef external fill:#EAD1DC,stroke:#9B2D75

    click BeansModule "https://github.com/graphefruit/beanconqueror/blob/master/src/app/beans/beans.module.ts"
    click BrewModule "https://github.com/graphefruit/beanconqueror/blob/master/src/app/brew/brew.module.ts"
    click RoastingModule "https://github.com/graphefruit/beanconqueror/blob/master/src/app/roasting-section/roasting-section.module.ts"
    click WaterModule "https://github.com/graphefruit/beanconqueror/blob/master/src/app/water-section/water-section.module.ts"
    click GraphModule "https://github.com/graphefruit/beanconqueror/blob/master/src/app/graph-section/graph-section.module.ts"

    click BeanStorage "https://github.com/graphefruit/beanconqueror/blob/master/src/services/uiBeanStorage.ts"
    click BrewStorage "https://github.com/graphefruit/beanconqueror/blob/master/src/services/uiBrewStorage.ts"
    click GreenBeanStorage "https://github.com/graphefruit/beanconqueror/blob/master/src/services/uiGreenBeanStorage.ts"
    click GraphStorage "https://github.com/graphefruit/beanconqueror/blob/master/src/services/uiGraphStorage.service.ts"
    click PreparationStorage "https://github.com/graphefruit/beanconqueror/blob/master/src/services/uiPreparationStorage.ts"
    click WaterStorage "https://github.com/graphefruit/beanconqueror/blob/master/src/services/uiWaterStorage.ts"
    click ServerComm "https://github.com/graphefruit/beanconqueror/blob/master/src/services/serverCommunication/server-communication.service.ts"
    click AnalyticsHelper "https://github.com/graphefruit/beanconqueror/blob/master/src/services/uiAnalytics.ts"
    click ExcelExport "https://github.com/graphefruit/beanconqueror/blob/master/src/services/uiExcel.ts"

    click UnifiedStorage "https://github.com/graphefruit/beanconqueror/blob/master/src/services/uiStorage.ts"
    click FileHelper "https://github.com/graphefruit/beanconqueror/blob/master/src/services/uiFileHelper.ts"

    click BluetoothService "https://github.com/graphefruit/beanconqueror/blob/master/src/services/coffeeBluetoothDevices/coffee-bluetooth-devices.service.ts"
    click NativePluginAngular "https://github.com/graphefruit/beanconqueror/blob/master/src/native/android-native-calls-plugin.ts"

    click AndroidPluginEntry "https://github.com/graphefruit/beanconqueror/blob/master/android/app/src/main/java/com/beanconqueror/BCAndroidNativeCallsPlugin.java"
    click AndroidMainActivity "https://github.com/graphefruit/beanconqueror/blob/master/android/app/src/main/java/com/beanconqueror/MainActivity.java"
    click iOSAppDelegate "https://github.com/graphefruit/beanconqueror/blob/master/ios/App/App/AppDelegate.swift"

    click AppHealth "https://github.com/graphefruit/beanconqueror/blob/master/src/services/uiHealthKit.ts"
    click AnalyticsPopover "https://github.com/graphefruit/beanconqueror/blob/master/src/popover/analytics-popover/analytics-popover.component.ts"
    click ProtoDef "https://github.com/graphefruit/beanconqueror/blob/master/src/classes/bean/bean.proto"
    click ProtoTs "https://github.com/graphefruit/beanconqueror/blob/master/src/generated/src/classes/bean/bean.ts"
```
