# romero-romero-romero/beti architecture

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

- Interactive diagram: https://gitdiagram.com/romero-romero-romero/beti
- Repository: https://github.com/romero-romero-romero/beti

## Overview

1. **Overall shape**
   - Beti is a **Flutter mobile app for Android/iOS** built as an **offline-first personal finance system**.
   - The main architectural decision is that **Isar is the local source of truth**; network/services are secondary and mostly used for auth and synchronization.

2. **Top-level composition**
   - The app is organized by **feature modules** under `lib/features/*`, with shared cross-cutting code in `lib/core/*`.
   - Each feature generally follows a **presentation → domain → data** structure, though some features are still partial or service-only.
   - The entrypoints are `lib/main.dart`, `lib/app.dart`, and routing in `lib/router/app_router.dart`.

3. **UI shell and navigation**
   - `MainShell` in `lib/core/widgets/main_shell.dart` appears to provide the persistent app scaffold/navigation container.
   - `GoRouter` drives screen-level navigation across modules, which is important for diagramming the UI boundary separately from feature logic.
   - The UI layer is mainly composed of feature screens plus shared widgets such as password requirements and theme-aware shell components.

4. **State management layer**
   - The app uses **Riverpod** extensively: each feature has providers in `presentation/providers`.
   - Providers are the main orchestration boundary between UI and data/services.
   - Shared providers live in `lib/core/providers`, including **connectivity** and **theme** state, plus a `core_providers.dart` composition file.

5. **Local persistence**
   - `lib/core/database/isar_instance.dart` centralizes access to **Isar**, which backs local models and offline storage.
   - Transactional data, sync state, auth session data, and other cached artifacts are likely persisted locally through Isar or local preferences.
   - In architecture terms, this is the most important infrastructure box: most app flows should connect back to local storage first.

6. **Sync and backend boundary**
   - The sync subsystem in `lib/features/sync` is a clear integration boundary around **Supabase**.
   - Key parts include local and remote datasources, a pull datasource, a repository implementation, a merge service, a realtime service, and a sync queue model.
   - This suggests a pipeline of **local change capture → queued sync → remote push/pull → merge/conflict handling → realtime updates**.
   - The presence of `supabase/migrations/*` confirms backend schema/RLS management lives outside the Flutter app.

7. **Authentication**
   - Auth is isolated in `lib/features/auth`, with separate **local** and **remote** datasources, a repository implementation, and presentation providers/screens.
   - The auth feature includes login, registration, and password update flows.
   - This feature likely feeds session state into the sync layer and gates access to user-scoped data.

8. **Transactions as core domain**
   - `lib/features/transactions` is one of the primary business domains, with local datasource, repository implementation, domain entity, and UI for listing, creating, and correcting transactions.
   - It also includes `category_model.dart`, implying categorization is part of transaction handling.
   - This feature likely acts as the central data producer for budgets, health, intelligence, and sync.

9. **Capture and intelligence pipeline**
   - `lib/features/input_capture` handles **OCR capture** and **voice capture** using local/native mechanisms.
   - The intelligence module processes captured content through a **text preprocessor**, **NLP entity extractor**, **categorization engine**, and a **TFLite categorizer service**.
   - The assets under `assets/ml` (`beti_categorizer.tflite`, `labels.json`, `vocab.json`) show that model inference is bundled locally, supporting offline classification.
   - A reasonable diagram boundary is: **camera/audio input → local extraction → NLP/ML categorization → transaction preview/correction → transaction storage**.

10. **Financial analytics and advisory features**
   - `budgets_goals` contains models plus services for budgeting, spending calculation, inflation adjustment, and budget alerting.
   - `financial_health` has a health engine and snapshot model, with a dashboard UI that likely computes an app-specific financial health metric.
   - `alerts` orchestrates alert delivery logic, while `notifications` stores user notification preferences and exposes notification settings.
   - These features are driven by transaction and budget data rather than external services.

11. **Education and profile utilities**
   - `financial_education` is backed by a local terms catalog and a preferences datasource for tracking what the user has seen.
   - `profile` includes a data export service and provider, indicating user data portability is part of the product boundary.
   - `cards_credits` models credit cards and credit simulation, with a local catalog and simulator service.
   - These are all supporting domains around the financial core rather than infrastructure.

12. **Core shared services and utilities**
   - `lib/core` holds cross-cutting concerns: constants, enums, error types, mappers, utils, theming, platform helpers, UUID generation, date/currency formatting, image compression, and notification service wiring.
   - `connectivity_provider` and `platform_helper` are especially relevant to architecture because they influence offline-first behavior and platform-specific integrations.
   - `app_theme.dart` and `theme_provider.dart` separate presentation theming from business logic.

13. **Platform integration**
   - The repository contains full **Android** and **iOS** native folders, which matters because OCR, speech-to-text, notifications, and possibly TFLite/native plugins rely on platform channels or plugin integrations.
   - Android and iOS are thin host shells around the Flutter app, not separate application stacks.

14. **Testing and quality boundary**
   - Tests are concentrated around core services and the more algorithmic/data-heavy features: intelligence, sync, financial health, and budgets.
   - This implies the most critical logic is intentionally kept testable outside the UI, which is consistent with the feature/provider/service separation.

15. **How to draw the architecture**
   - A good diagram would center on **Flutter UI + Riverpod providers** at the top, **feature-specific services/repositories** in the middle, and **Isar local storage** as the base system of record.
   - From the middle layer, draw one external boundary to **Supabase** for auth and sync, and another to **native on-device ML/capture capabilities** for OCR, speech, and TFLite inference.
   - Most business features should be shown as consumers of the same local financial data model rather than as independent silos.

Main entry points: [`lib/features/transactions/data/repositories/transaction_repository_impl.dart`](https://github.com/romero-romero-romero/beti/blob/main/lib/features/transactions/data/repositories/transaction_repository_impl.dart) (Transactions), [`lib/features/sync/data/repositories/sync_repository_impl.dart`](https://github.com/romero-romero-romero/beti/blob/main/lib/features/sync/data/repositories/sync_repository_impl.dart) (Sync), [`lib/core/database/isar_instance.dart`](https://github.com/romero-romero-romero/beti/blob/main/lib/core/database/isar_instance.dart) (Isar store), [`lib/features/intelligence/data/datasources/categorization_engine.dart`](https://github.com/romero-romero-romero/beti/blob/main/lib/features/intelligence/data/datasources/categorization_engine.dart) (Intelligence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App Shell"]
  node_node_main["App entry<br/>flutter entrypoint<br/>[main.dart]"]
  node_node_app["App root<br/>flutter root<br/>[app.dart]"]
  node_node_router["Router<br/>navigation<br/>[app_router.dart]"]
  node_node_shell["Main shell<br/>ui scaffold<br/>[main_shell.dart]"]
end

subgraph group_group_core["Core Infra"]
  node_node_core_providers["Core providers<br/>riverpod core"]
  node_node_theme["Theme state<br/>ui state"]
  node_node_connectivity["Connectivity<br/>network state"]
  node_node_isar[("Isar store<br/>local database<br/>[isar_instance.dart]")]
  node_node_utils["Core utils<br/>shared helpers"]
  node_node_notifications_core["Notify service<br/>system service"]
end

subgraph group_group_finance["Financial Core"]
  node_node_auth["Auth<br/>feature"]
  node_node_transactions["Transactions<br/>feature"]
  node_node_budgets["Budgets<br/>feature"]
  node_node_health["Health<br/>feature<br/>[health_engine.dart]"]
  node_node_education["Education<br/>feature"]
  node_node_cards["Cards<br/>feature"]
  node_node_profile["Profile export<br/>feature"]
  node_node_alerts["Alerts<br/>feature service"]
  node_node_notifications["Notification prefs<br/>feature"]
end

subgraph group_group_input["Capture & Intelligence"]
  node_node_input_capture["Capture<br/>feature<br/>[ocr_local_ds.dart]"]
  node_node_intelligence["Intelligence<br/>feature"]
end

subgraph group_group_integrations["External Boundaries"]
  node_node_sync["Sync<br/>feature"]
  node_node_supabase[("Supabase<br/>backend boundary")]
  node_node_native["Native host<br/>platform shell<br/>[MainActivity.kt]"]
  node_node_ml["ML assets<br/>on-device model"]
end

node_node_main -->|"starts"| node_node_app
node_node_app -->|"composes"| node_node_core_providers
node_node_app -->|"uses"| node_node_router
node_node_router -->|"hosts"| node_node_shell
node_node_core_providers -->|"includes"| node_node_theme
node_node_core_providers -->|"includes"| node_node_connectivity
node_node_theme -->|"styles"| node_node_shell
node_node_connectivity -->|"guards"| node_node_sync
node_node_isar -->|"stores"| node_node_transactions
node_node_isar -->|"stores"| node_node_auth
node_node_isar -->|"stores"| node_node_sync
node_node_transactions -->|"feeds"| node_node_budgets
node_node_transactions -->|"feeds"| node_node_health
node_node_transactions -->|"routes data"| node_node_intelligence
node_node_input_capture -->|"extracts"| node_node_intelligence
node_node_intelligence -->|"creates"| node_node_transactions
node_node_intelligence -->|"runs on"| node_node_ml
node_node_auth -->|"gates"| node_node_sync
node_node_sync -->|"syncs with"| node_node_supabase
node_node_auth -->|"auths with"| node_node_supabase
node_node_sync -->|"updates"| node_node_transactions
node_node_budgets -->|"triggers"| node_node_alerts
node_node_alerts -->|"configures"| node_node_notifications
node_node_notifications -->|"uses"| node_node_notifications_core
node_node_profile -->|"exports from"| node_node_isar
node_node_input_capture -->|"uses"| node_node_native
node_node_ml -->|"loads via"| node_node_native
node_node_utils -->|"supports"| node_node_transactions

click node_node_main "https://github.com/romero-romero-romero/beti/blob/main/lib/main.dart"
click node_node_app "https://github.com/romero-romero-romero/beti/blob/main/lib/app.dart"
click node_node_router "https://github.com/romero-romero-romero/beti/blob/main/lib/router/app_router.dart"
click node_node_shell "https://github.com/romero-romero-romero/beti/blob/main/lib/core/widgets/main_shell.dart"
click node_node_core_providers "https://github.com/romero-romero-romero/beti/blob/main/lib/core/providers/core_providers.dart"
click node_node_theme "https://github.com/romero-romero-romero/beti/blob/main/lib/core/providers/theme_provider.dart"
click node_node_connectivity "https://github.com/romero-romero-romero/beti/blob/main/lib/core/providers/connectivity_provider.dart"
click node_node_isar "https://github.com/romero-romero-romero/beti/blob/main/lib/core/database/isar_instance.dart"
click node_node_utils "https://github.com/romero-romero-romero/beti/blob/main/lib/core/utils/platform_helper.dart"
click node_node_notifications_core "https://github.com/romero-romero-romero/beti/blob/main/lib/core/services/notification_service.dart"
click node_node_auth "https://github.com/romero-romero-romero/beti/blob/main/lib/features/auth/data/repositories/auth_repository_impl.dart"
click node_node_transactions "https://github.com/romero-romero-romero/beti/blob/main/lib/features/transactions/data/repositories/transaction_repository_impl.dart"
click node_node_budgets "https://github.com/romero-romero-romero/beti/blob/main/lib/features/budgets_goals/data/services/budget_spending_calculator.dart"
click node_node_health "https://github.com/romero-romero-romero/beti/blob/main/lib/features/financial_health/data/datasources/health_engine.dart"
click node_node_education "https://github.com/romero-romero-romero/beti/blob/main/lib/features/financial_education/data/financial_terms_catalog.dart"
click node_node_cards "https://github.com/romero-romero-romero/beti/blob/main/lib/features/cards_credits/data/services/credit_simulator_service.dart"
click node_node_profile "https://github.com/romero-romero-romero/beti/blob/main/lib/features/profile/data/services/data_export_service.dart"
click node_node_alerts "https://github.com/romero-romero-romero/beti/blob/main/lib/features/alerts/data/services/alert_orchestrator.dart"
click node_node_notifications "https://github.com/romero-romero-romero/beti/blob/main/lib/features/notifications/data/models/notification_preferences_model.dart"
click node_node_input_capture "https://github.com/romero-romero-romero/beti/blob/main/lib/features/input_capture/data/datasources/ocr_local_ds.dart"
click node_node_intelligence "https://github.com/romero-romero-romero/beti/blob/main/lib/features/intelligence/data/datasources/categorization_engine.dart"
click node_node_sync "https://github.com/romero-romero-romero/beti/blob/main/lib/features/sync/data/repositories/sync_repository_impl.dart"
click node_node_supabase "https://github.com/romero-romero-romero/beti/blob/main/supabase/migrations/20260422_rls_role_hardening.sql"
click node_node_native "https://github.com/romero-romero-romero/beti/blob/main/android/app/src/main/kotlin/mx/beti/app/MainActivity.kt"
click node_node_ml "https://github.com/romero-romero-romero/beti/blob/main/assets/ml/beti_categorizer.tflite"

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_node_main,node_node_app,node_node_router,node_node_shell toneBlue
class node_node_core_providers,node_node_theme,node_node_connectivity,node_node_isar,node_node_utils,node_node_notifications_core toneAmber
class node_node_auth,node_node_transactions,node_node_budgets,node_node_health,node_node_education,node_node_cards,node_node_profile,node_node_alerts,node_node_notifications toneMint
class node_node_input_capture,node_node_intelligence toneRose
class node_node_sync,node_node_supabase,node_node_native,node_node_ml toneIndigo
```

## Components

### App Shell

Flutter entrypoints, routing, and persistent UI scaffold.

- [App entry](https://github.com/romero-romero-romero/beti/blob/main/lib/main.dart): flutter entrypoint · Bootstraps the app and wires shared providers. · `lib/main.dart`
- [App root](https://github.com/romero-romero-romero/beti/blob/main/lib/app.dart): flutter root · Top-level app composition and dependency wiring. · `lib/app.dart`
- [Router](https://github.com/romero-romero-romero/beti/blob/main/lib/router/app_router.dart): navigation · GoRouter-based screen routing across features. · `lib/router/app_router.dart`
- [Main shell](https://github.com/romero-romero-romero/beti/blob/main/lib/core/widgets/main_shell.dart): ui scaffold · Persistent navigation container for the mobile app. · `lib/core/widgets/main_shell.dart`

### Core Infra

Shared infrastructure for state, storage, theming, utilities, and app-wide services.

- [Core providers](https://github.com/romero-romero-romero/beti/blob/main/lib/core/providers/core_providers.dart): riverpod core · Shared app-wide providers such as connectivity and theme. · `lib/core/providers/core_providers.dart`
- [Theme state](https://github.com/romero-romero-romero/beti/blob/main/lib/core/providers/theme_provider.dart): ui state · Theme provider and app theme definition. · `lib/core/providers/theme_provider.dart`
- [Connectivity](https://github.com/romero-romero-romero/beti/blob/main/lib/core/providers/connectivity_provider.dart): network state · Connectivity awareness used to support offline-first behavior. · `lib/core/providers/connectivity_provider.dart`
- [Isar store](https://github.com/romero-romero-romero/beti/blob/main/lib/core/database/isar_instance.dart): local database · Central local source of truth for offline persistence. · `lib/core/database/isar_instance.dart`
- [Core utils](https://github.com/romero-romero-romero/beti/blob/main/lib/core/utils/platform_helper.dart): shared helpers · Formatting, platform, UUID, compression, and other shared helpers. · `lib/core/utils/platform_helper.dart`
- [Notify service](https://github.com/romero-romero-romero/beti/blob/main/lib/core/services/notification_service.dart): system service · Core notification wiring used by feature-level alerting. · `lib/core/services/notification_service.dart`

### Financial Core

Primary business domains built around local financial data.

- [Auth](https://github.com/romero-romero-romero/beti/blob/main/lib/features/auth/data/repositories/auth_repository_impl.dart): feature · Login, registration, password update, and session handling. · `lib/features/auth/data/repositories/auth_repository_impl.dart`
- [Transactions](https://github.com/romero-romero-romero/beti/blob/main/lib/features/transactions/data/repositories/transaction_repository_impl.dart): feature · Local transaction storage, listing, creation, and correction. · `lib/features/transactions/data/repositories/transaction_repository_impl.dart`
- [Budgets](https://github.com/romero-romero-romero/beti/blob/main/lib/features/budgets_goals/data/services/budget_spending_calculator.dart): feature · Budgeting, spending calculation, goals, and alert logic. · `lib/features/budgets_goals/data/services/budget_spending_calculator.dart`
- [Health](https://github.com/romero-romero-romero/beti/blob/main/lib/features/financial_health/data/datasources/health_engine.dart): feature · Financial health scoring and dashboard snapshot generation. · `lib/features/financial_health/data/datasources/health_engine.dart`
- [Education](https://github.com/romero-romero-romero/beti/blob/main/lib/features/financial_education/data/financial_terms_catalog.dart): feature · Financial terms catalog and seen-term tracking. · `lib/features/financial_education/data/financial_terms_catalog.dart`
- [Cards](https://github.com/romero-romero-romero/beti/blob/main/lib/features/cards_credits/data/services/credit_simulator_service.dart): feature · Credit card cataloging and credit simulation tools. · `lib/features/cards_credits/data/services/credit_simulator_service.dart`
- [Profile export](https://github.com/romero-romero-romero/beti/blob/main/lib/features/profile/data/services/data_export_service.dart): feature · User data export and profile utilities. · `lib/features/profile/data/services/data_export_service.dart`
- [Alerts](https://github.com/romero-romero-romero/beti/blob/main/lib/features/alerts/data/services/alert_orchestrator.dart): feature service · Alert orchestration for app-side financial notifications. · `lib/features/alerts/data/services/alert_orchestrator.dart`
- [Notification prefs](https://github.com/romero-romero-romero/beti/blob/main/lib/features/notifications/data/models/notification_preferences_model.dart): feature · User notification settings and stored preferences. · `lib/features/notifications/data/models/notification_preferences_model.dart`

### Capture & Intelligence

On-device capture and ML-assisted transaction understanding.

- [Capture](https://github.com/romero-romero-romero/beti/blob/main/lib/features/input_capture/data/datasources/ocr_local_ds.dart): feature · OCR and voice capture for entering financial data. · `lib/features/input_capture/data/datasources/ocr_local_ds.dart`
- [Intelligence](https://github.com/romero-romero-romero/beti/blob/main/lib/features/intelligence/data/datasources/categorization_engine.dart): feature · Text preprocessing, entity extraction, and categorization pipeline. · `lib/features/intelligence/data/datasources/categorization_engine.dart`

### External Boundaries

Backend, platform, and native capability integrations.

- [Sync](https://github.com/romero-romero-romero/beti/blob/main/lib/features/sync/data/repositories/sync_repository_impl.dart): feature · Offline-first synchronization, merge, queue, and realtime update flow. · `lib/features/sync/data/repositories/sync_repository_impl.dart`
- [Supabase](https://github.com/romero-romero-romero/beti/blob/main/supabase/migrations/20260422_rls_role_hardening.sql): backend boundary · Remote auth and sync backend managed through Flutter integration and migrations. · `supabase/migrations/20260422_rls_role_hardening.sql`
- [Native host](https://github.com/romero-romero-romero/beti/blob/main/android/app/src/main/kotlin/mx/beti/app/MainActivity.kt): platform shell · Android and iOS host layers for plugins, capture, OCR, and ML runtime. · `android/app/src/main/kotlin/mx/beti/app/MainActivity.kt`
- [ML assets](https://github.com/romero-romero-romero/beti/blob/main/assets/ml/beti_categorizer.tflite): on-device model · Bundled TFLite categorization model and vocab/labels for offline inference. · `assets/ml/beti_categorizer.tflite`

## Connections

- App entry → App root: starts · Main entrypoint launches the app root.
- App root → Core providers: composes · App root wires global providers and shared state.
- App root → Router: uses · Top-level composition delegates screen navigation to the router.
- Router → Main shell: hosts · Router places feature screens inside the persistent shell.
- Core providers → Theme state: includes · Shared provider composition includes theme state.
- Core providers → Connectivity: includes · Shared provider composition includes connectivity state.
- Theme state → Main shell: styles · Theme state drives the app shell appearance.
- Connectivity → Sync: guards · Connectivity influences when sync work can proceed.
- Isar store → Transactions: stores · Local database backs transaction persistence.
- Isar store → Auth: stores · Local database backs session and auth cache.
- Isar store → Sync: stores · Sync queue and local state live in local storage.
- Transactions → Budgets: feeds · Budgeting consumes transaction data.
- Transactions → Health: feeds · Financial health is computed from transaction activity.
- Transactions → Intelligence: routes data · Captured content is converted into transaction-ready data.
- Capture → Intelligence: extracts · OCR and voice capture feed the intelligence pipeline.
- Intelligence → Transactions: creates · Categorized results flow into transaction preview and storage.
- Intelligence → ML assets: runs on · Categorization uses bundled on-device ML assets.
- Auth → Sync: gates · Authentication establishes the user context for synchronization.
- Sync → Supabase: syncs with · Sync subsystem talks to the remote backend boundary.
- Auth → Supabase: auths with · Authentication feature integrates with the backend.
- Sync → Transactions: updates · Sync reconciles remote and local transaction state.
- Budgets → Alerts: triggers · Budget thresholds can generate alerts.
- Alerts → Notification prefs: configures · Alert delivery depends on notification preferences.
- Notification prefs → Notify service: uses · Notification settings connect to core notification wiring.
- Profile export → Isar store: exports from · Export service reads local user data for portability.
- Capture → Native host: uses · Capture flows rely on platform plugins and native capabilities.
- ML assets → Native host: loads via · On-device model execution depends on the native runtime layer.
- Core utils → Transactions: supports · Shared helpers support domain calculations and formatting.
