# brilliantlabsar/noa-flutter architecture

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

- Interactive diagram: https://gitdiagram.com/brilliantlabsar/noa-flutter
- Repository: https://github.com/brilliantlabsar/noa-flutter

## Overview

##### Project Type and Purpose
- This is a cross-platform mobile application built in Flutter, targeting both iOS and Android.
- Purpose: to serve as a companion app (“Noa”) for the Frame hardware device, demonstrating Bluetooth connectivity, GPS/location services, Google OAuth, and real-time device control.

##### File Structure
- Top-Level Folders
– android/ and ios/: Native project scaffolding and platform-specific code (Bluetooth permissions, manifests, Gradle and Xcode projects).
– lib/: Main Flutter code. Subfolders:
- pages/: UI screens and navigation (login.dart, pairing.dart, noa.dart, hack.dart, tune.dart, etc.).
- widgets/: Reusable UI components (bottom_nav_bar, top_title_bar).
- models/: Data and business-logic models (app_logic_model.dart).
- util/: Services and helpers (bluetooth.dart, location.dart, foreground_service.dart, state_machine.dart, noa_api.dart, sign_in.dart, etc.).
– assets/: Static assets (images, firmware ZIP, Lua scripts).
– docs/: Documentation and screenshots.
- Configurations and Build Scripts
– pubspec.yaml/pubspec.lock: Flutter dependencies.
– .env.template: Environment variables (e.g., Google OAuth client IDs).
– Android Gradle files and iOS plist/config for permissions.

##### Extract Additional Insights from README
- Confirms use of Flutter, Google OAuth, Bluetooth Central & Peripheral, background modes, and location permissions.
- Describes regeneration of platform folders, hinting at platform channels for native-Flutter integration.

##### Of Main Components
a. Presentation Layer (Flutter UI)
- Pages (login, splash, pairing, noa, hack, tune, regulatory, account)
- Widgets (navigation bars, dialogs)
b. State & Business Logic Layer
- app_logic_model.dart
- state_machine.dart
- noa_api.dart (abstracts device or cloud API)
c. Services Layer
- BluetoothService (lib/util/bluetooth.dart)
- LocationService (lib/util/location.dart)
- ForegroundService (background execution code)
- AuthService (lib/util/sign_in.dart using Google OAuth)
d. Data & Device Layer
- Frame Hardware Device via BLE (connect, pair, send Lua scripts)
- Assets (Lua scripts for firmware control)
e. External Services
- Google OAuth endpoints
- Potential Cloud API (if noa_api.dart calls a remote server)

##### Relationships and Data Flows
- User interacts with Flutter UI → triggers AuthService → Google OAuth → returns tokens → stored in app_logic_model.
- UI navigates to Pairing → BluetoothService scans and pairs with Frame → underlying platform-specific code in android/ and ios/ invokes native BLE APIs → returns device handle.
- UI invokes commands (tune/hack pages) → StateMachine applies transitions → BluetoothService writes data (e.g., Lua scripts) → Frame executes firmware commands.
- LocationService fetches GPS data → used for regulatory compliance pages.
- ForegroundService keeps BLE connection alive in background.

##### Architectural Patterns and Principles
- Separation of Concerns: UI vs business logic vs services.
- Platform Abstraction: util/bluetooth.dart and util/location.dart wrap platform channels.
- State Machine: Handles complex device interaction flows.
- Modular Widgets: Reusable UI components for consistent design.

##### Detail Level
- Config files (.env, Info.plist entries) in a side note or callout.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Platform Layer
    subgraph "Platform Layer"
        A1["android/"]:::platform
        A2["ios/"]:::platform
    end

    %% Flutter Engine
    subgraph "Flutter Engine"
        %% Presentation
        subgraph "Presentation Layer"
            P1["login.dart"]:::flutter
            P2["splash.dart"]:::flutter
            P3["pairing.dart"]:::flutter
            P4["noa.dart"]:::flutter
            P5["hack.dart"]:::flutter
            P6["tune.dart"]:::flutter
            P7["regulatory.dart"]:::flutter
            P8["account.dart"]:::flutter
            W1["bottom_nav_bar.dart"]:::flutter
            W2["top_title_bar.dart"]:::flutter
        end

        %% Logic & Services
        subgraph "Logic & Services"
            M1["app_logic_model.dart"]:::flutter
            SM["state_machine.dart"]:::flutter
            API["noa_api.dart"]:::flutter
            BT["BluetoothService"]:::flutter
            LOC["LocationService"]:::flutter
            FG["ForegroundService"]:::flutter
            AUTH["AuthService"]:::flutter
        end

        %% Assets
        subgraph "Assets (Lua Scripts)"
            L1["main.lua"]:::flutter
            L2["graphics.lua"]:::flutter
            L3["state.lua"]:::flutter
        end
    end

    %% External Layer
    subgraph "External Layer"
        E1["Frame Device (BLE)"]:::external
        E2["Google OAuth Server"]:::external
    end

    %% Connections
    A1 -->|"BLE & location perms"| BT
    A2 -->|"BLE & location perms"| BT

    P1 & P2 & P3 & P4 & P5 & P6 & P7 & P8 -->|"signInWithGoogle()"| AUTH
    AUTH -->|"returns tokens"| M1

    P3 -->|"scanForDevices()"| BT
    BT -->|"deviceHandle"| M1

    P5 & P6 -->|"invokeCommands()"| SM
    SM -->|"writeCharacteristic()"| BT

    P7 -->|"getLocation()"| LOC
    LOC -->|"GPS data"| M1

    FG -.->|"keeps BLE alive"| BT

    BT -->|"BLE communication"| E1
    AUTH -->|"OAuth flow"| E2

    %% Click events
    click P1 "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/pages/login.dart"
    click P2 "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/pages/splash.dart"
    click P3 "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/pages/pairing.dart"
    click P4 "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/pages/noa.dart"
    click P5 "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/pages/hack.dart"
    click P6 "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/pages/tune.dart"
    click P7 "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/pages/regulatory.dart"
    click P8 "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/pages/account.dart"
    click W1 "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/widgets/bottom_nav_bar.dart"
    click W2 "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/widgets/top_title_bar.dart"
    click M1 "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/models/app_logic_model.dart"
    click SM "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/util/state_machine.dart"
    click API "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/noa_api.dart"
    click BT "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/bluetooth.dart"
    click LOC "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/util/location.dart"
    click FG "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/util/foreground_service.dart"
    click AUTH "https://github.com/brilliantlabsar/noa-flutter/blob/main/lib/util/sign_in.dart"
    click L1 "https://github.com/brilliantlabsar/noa-flutter/blob/main/assets/lua_scripts/main.lua"
    click L2 "https://github.com/brilliantlabsar/noa-flutter/blob/main/assets/lua_scripts/graphics.lua"
    click L3 "https://github.com/brilliantlabsar/noa-flutter/blob/main/assets/lua_scripts/state.lua"
    click A1 "https://github.com/brilliantlabsar/noa-flutter/tree/main/android/"
    click A2 "https://github.com/brilliantlabsar/noa-flutter/tree/main/ios/"

    %% Styles
    classDef flutter fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef platform fill:#CFF7AE,stroke:#333,stroke-width:1px
    classDef external fill:#F7DFAE,stroke:#333,stroke-width:1px
```
