# salf423/app-nvel-burbuja architecture

> Architecture diagram of the GitHub repository salf423/app-nvel-burbuja, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/salf423/app-nvel-burbuja
- Repository: https://github.com/salf423/app-nvel-burbuja

## Overview

1. **Project type and scope**
   - This is a **.NET MAUI Android app** for a bubble level / inclinometer, not a multi-service system.
   - The architecture is intentionally small: one UI screen, one sensor-driven interaction loop, and Android-specific packaging/build configuration.

2. **Application composition**
   - The repo is split into **XAML UI** and **C# code-behind**.
   - The main functional boundary is between:
     - **visual layout** (`buendia/XAML`)
     - **runtime behavior and sensor handling** (`buendia/C#`)
   - There is no backend, database, or network layer in the repository.

3. **Startup and host layer**
   - `App.xaml.cs` and `MauiProgram.cs` define the app startup path.
   - `MainActivity.cs` is the Android entry host that connects the MAUI app to the Android runtime.
   - `App.xaml` provides the application-level shell/resources, while `MainPage.xaml` is the primary screen shown to the user.

4. **Main UI subsystem**
   - `MainPage.xaml` is the single visible interface for the level indicator.
   - The UI likely contains a movable visual element (`miBurbuja`) whose position represents tilt.
   - The UI is updated continuously from sensor events, so the page is both the display surface and the target of live state changes.

5. **Sensor processing subsystem**
   - The core logic is in `MainPage.xaml.cs`, where the accelerometer change handler is registered and executed.
   - The app listens to **accelerometer readings** and uses them as the raw input stream.
   - This is the central data source of the whole application.

6. **Signal processing and motion logic**
   - Each accelerometer update reads the X, Y, and Z axes.
   - The values are smoothed with an **exponential filter** using `Alpha`, reducing jitter.
   - From the filtered values, the app computes:
     - **pitch** from X relative to Y/Z magnitude
     - **roll** from Y and Z
   - These angles are then converted into visual offsets for the bubble.

7. **UI update flow**
   - Sensor callbacks are not applied directly to the visual tree; updates are marshaled through the **main thread**.
   - The bubble position is changed via `TranslationX` and `TranslationY`.
   - The final displacement is scaled and clamped, which keeps the UI stable and prevents the bubble from moving outside the intended range.

8. **Android platform boundary**
   - `buendia/Propiedaes/AndroidManifest.xml` defines Android-specific capabilities and app metadata.
   - The manifest declares:
     - app name/label
     - minimum and target SDK levels
     - required accelerometer hardware
   - This means the app is explicitly tied to devices with an accelerometer.

9. **Permissions and device constraints**
   - The README highlights that sensor permissions must be handled for Android runtime behavior.
   - It also notes that testing should be done on a **real Android device**, which is important because the app depends on actual motion hardware.
   - This is not an emulator-first design; physical sensor input is the critical dependency.

10. **Build and packaging**
   - `AccelerometerEssential.Android.csproj` is the Android project definition.
   - `Directory-Build.props` and `global.json` provide repo-wide build consistency and SDK pinning.
   - The repository includes a GitHub Actions workflow at `.github/workflows/build-android.yml`, indicating automated Android builds/CI.

11. **Runtime behavior summary**
   - The app’s data flow is linear:
     - accelerometer hardware → change event → filtering → angle computation → UI translation
   - The screen is continuously driven by live sensor input, so the system behaves like a real-time control loop rather than a request/response application.

12. **Architecture diagram boundaries to show**
   - A good diagram should include these distinct blocks:
     - **Android device hardware** (accelerometer)
     - **Android runtime / MainActivity**
     - **MAUI app shell and page layer**
     - **sensor processing logic**
     - **bubble UI element**
     - **build/CI pipeline**
   - The key dependency direction is from hardware input into the page logic, then outward to the UI.

13. **Repo-specific note**
   - The folder names show a mix of Spanish labels and MAUI conventions, and `Propiedaes` appears to be a typo of `Propiedades`; architecturally, it still functions as the Android properties/manifest area.
   - The repo is tightly focused: the accelerometer-driven bubble indicator is the main product behavior, and everything else supports that single flow.

Main entry points: [`buendia/C#/MainPage.xaml.cs`](https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/C#/MainPage.xaml.cs) (Sensor logic), [`buendia/XAML/MainPage.xaml`](https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/XAML/MainPage.xaml) (Main screen), [`buendia/C#/AccelerometerEssential.Android.csproj`](https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/C#/AccelerometerEssential.Android.csproj) (Android csproj), [`buendia/C#/App.xaml.cs`](https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/C#/App.xaml.cs) (App startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hardware["Device input"]
  node_accelerometer(("Accelerometer<br/>hardware sensor"))
end

subgraph group_runtime["App runtime"]
  node_main_activity["MainActivity<br/>android host<br/>[MainActivity.cs]"]
  node_maui_program["MauiProgram<br/>app bootstrap<br/>[MauiProgram.cs]"]
  node_app_cs["App startup<br/>app shell code<br/>[App.xaml.cs]"]
  node_main_page_cs["Sensor logic<br/>sensor loop<br/>[MainPage.xaml.cs]"]
  node_app_xaml["App resources<br/>app shell xaml<br/>[App.xaml]"]
end

subgraph group_ui["Bubble UI"]
  node_main_page_xaml["Main screen<br/>view xaml<br/>[MainPage.xaml]"]
  node_bubble(("Bubble<br/>indicator element<br/>[MainPage.xaml]"))
end

subgraph group_platform["Android platform"]
  node_manifest["AndroidManifest<br/>android manifest"]
end

subgraph group_build["Build & CI"]
  node_project["Android csproj<br/>build project"]
  node_build_props["Build props<br/>repo build config"]
  node_sdk_pin["SDK pin<br/>toolchain config<br/>[global.json]"]
  node_workflow["Android CI<br/>github actions<br/>[build-android.yml]"]
end

node_accelerometer -->|"device input"| node_main_activity
node_main_activity -->|"bootstraps"| node_maui_program
node_maui_program -->|"creates app"| node_app_cs
node_app_cs -->|"loads resources"| node_app_xaml
node_app_cs -->|"opens page"| node_main_page_xaml
node_main_page_xaml -->|"contains"| node_bubble
node_main_page_xaml -->|"code-behind"| node_main_page_cs
node_main_page_cs -->|"reads"| node_accelerometer
node_main_page_cs -->|"moves"| node_bubble
node_main_page_cs -->|"updates UI"| node_main_page_xaml
node_manifest -->|"requires"| node_accelerometer
node_project -->|"packages"| node_manifest
node_build_props -->|"configures"| node_project
node_sdk_pin -->|"pins toolchain"| node_project
node_workflow -->|"builds"| node_project

click node_main_activity "https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/C#/MainActivity.cs"
click node_maui_program "https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/C#/MauiProgram.cs"
click node_app_cs "https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/C#/App.xaml.cs"
click node_main_page_cs "https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/C#/MainPage.xaml.cs"
click node_app_xaml "https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/XAML/App.xaml"
click node_main_page_xaml "https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/XAML/MainPage.xaml"
click node_bubble "https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/XAML/MainPage.xaml"
click node_manifest "https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/Propiedaes/AndroidManifest.xml"
click node_project "https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/C#/AccelerometerEssential.Android.csproj"
click node_build_props "https://github.com/salf423/app-nvel-burbuja/blob/main/Directory-Build.props"
click node_sdk_pin "https://github.com/salf423/app-nvel-burbuja/blob/main/global.json"
click node_workflow "https://github.com/salf423/app-nvel-burbuja/blob/main/.github/workflows/build-android.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_accelerometer toneBlue
class node_main_activity,node_maui_program,node_app_cs,node_main_page_cs,node_app_xaml toneAmber
class node_main_page_xaml,node_bubble toneMint
class node_manifest toneRose
class node_project,node_build_props,node_sdk_pin,node_workflow toneIndigo
```

## Components

### Device input

Physical accelerometer source on the Android device

- **Accelerometer**: hardware sensor · Physical motion sensor providing X/Y/Z readings

### App runtime

MAUI startup, page hosting, and sensor loop

- [MainActivity](https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/C#/MainActivity.cs): android host · Android entry point that boots the MAUI app · `buendia/C#/MainActivity.cs`
- [MauiProgram](https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/C#/MauiProgram.cs): app bootstrap · Registers MAUI services and configures the app host · `buendia/C#/MauiProgram.cs`
- [App startup](https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/C#/App.xaml.cs): app shell code · Connects application startup to the main page · `buendia/C#/App.xaml.cs`
- [Sensor logic](https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/C#/MainPage.xaml.cs): sensor loop · Handles accelerometer updates, filtering, angles, and UI translation · `buendia/C#/MainPage.xaml.cs`
- [App resources](https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/XAML/App.xaml): app shell xaml · Application-level resources and shell definition · `buendia/XAML/App.xaml`

### Bubble UI

Visible screen and animated level indicator

- [Main screen](https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/XAML/MainPage.xaml): view xaml · Primary UI layout for the inclinometer display · `buendia/XAML/MainPage.xaml`
- [Bubble](https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/XAML/MainPage.xaml): indicator element · Movable visual element whose position reflects tilt · `buendia/XAML/MainPage.xaml`

### Android platform

Android packaging, manifest, and device constraints

- [AndroidManifest](https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/Propiedaes/AndroidManifest.xml): android manifest · Android app metadata, SDK levels, and hardware requirements · `buendia/Propiedaes/AndroidManifest.xml`

### Build & CI

Repo-wide build settings and automated Android build

- [Android csproj](https://github.com/salf423/app-nvel-burbuja/blob/main/buendia/C#/AccelerometerEssential.Android.csproj): build project · MAUI Android project definition and packaging settings · `buendia/C#/AccelerometerEssential.Android.csproj`
- [Build props](https://github.com/salf423/app-nvel-burbuja/blob/main/Directory-Build.props): repo build config · Repository-wide build defaults and shared settings · `Directory-Build.props`
- [SDK pin](https://github.com/salf423/app-nvel-burbuja/blob/main/global.json): toolchain config · Pinned .NET SDK version for consistent builds · `global.json`
- [Android CI](https://github.com/salf423/app-nvel-burbuja/blob/main/.github/workflows/build-android.yml): github actions · Automated Android build workflow · `.github/workflows/build-android.yml`

## Connections

- Accelerometer → MainActivity: device input · Sensor hardware is accessed through the Android app host
- MainActivity → MauiProgram: bootstraps · Android entry point starts the MAUI application
- MauiProgram → App startup: creates app · Configures the app object and startup services
- App startup → App resources: loads resources · Application startup binds to app-level XAML resources
- App startup → Main screen: opens page · Startup routes the user into the main screen
- Main screen → Bubble: contains · The visible level indicator is part of the main screen layout
- Main screen → Sensor logic: code-behind · The page layout is paired with its runtime logic
- Sensor logic → Accelerometer: reads · Registers and consumes accelerometer change events
- Sensor logic → Bubble: moves · Computes translation offsets and updates the indicator
- Sensor logic → Main screen: updates UI · Sensor callbacks marshal changes back to the page thread
- AndroidManifest → Accelerometer: requires · Declares accelerometer hardware as a device dependency
- Android csproj → AndroidManifest: packages · Android project includes platform manifest and app packaging
- Build props → Android csproj: configures · Shared build defaults feed the Android project
- SDK pin → Android csproj: pins toolchain · Locks the .NET SDK used for local and CI builds
- Android CI → Android csproj: builds · GitHub Actions runs the Android project in CI