How romero-romero-romero/beti works
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: transaction_repository_impl.dart Transactions · sync_repository_impl.dart Sync · isar_instance.dart Isar store · categorization_engine.dart Intelligence
Components 25
App Shell
Flutter entrypoints, routing, and persistent UI scaffold.
- App entry · Bootstraps the app and wires shared providers.
lib/main.dart - App root · Top-level app composition and dependency wiring.
lib/app.dart - Router · GoRouter-based screen routing across features.
lib/router/app_router.dart - Main shell · 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 · Shared app-wide providers such as connectivity and theme.
lib/core/providers/core_providers.dart - Theme state · Theme provider and app theme definition.
lib/core/providers/theme_provider.dart - Connectivity · Connectivity awareness used to support offline-first behavior.
lib/core/providers/connectivity_provider.dart - Isar store · Central local source of truth for offline persistence.
lib/core/database/isar_instance.dart - Core utils · Formatting, platform, UUID, compression, and other shared helpers.
lib/core/utils/platform_helper.dart - Notify 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 · Login, registration, password update, and session handling.
lib/features/auth/data/repositories/auth_repository_impl.dart - Transactions · Local transaction storage, listing, creation, and correction.
lib/features/transactions/data/repositories/transaction_repository_impl.dart - Budgets · Budgeting, spending calculation, goals, and alert logic.
lib/features/budgets_goals/data/services/budget_spending_calculator.dart - Health · Financial health scoring and dashboard snapshot generation.
lib/features/financial_health/data/datasources/health_engine.dart - Education · Financial terms catalog and seen-term tracking.
lib/features/financial_education/data/financial_terms_catalog.dart - Cards · Credit card cataloging and credit simulation tools.
lib/features/cards_credits/data/services/credit_simulator_service.dart - Profile export · User data export and profile utilities.
lib/features/profile/data/services/data_export_service.dart - Alerts · Alert orchestration for app-side financial notifications.
lib/features/alerts/data/services/alert_orchestrator.dart - Notification prefs · 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 · OCR and voice capture for entering financial data.
lib/features/input_capture/data/datasources/ocr_local_ds.dart - Intelligence · Text preprocessing, entity extraction, and categorization pipeline.
lib/features/intelligence/data/datasources/categorization_engine.dart
External Boundaries
Backend, platform, and native capability integrations.
- Sync · Offline-first synchronization, merge, queue, and realtime update flow.
lib/features/sync/data/repositories/sync_repository_impl.dart - Supabase · Remote auth and sync backend managed through Flutter integration and migrations.
supabase/migrations/20260422_rls_role_hardening.sql - Native host · Android and iOS host layers for plugins, capture, OCR, and ML runtime.
android/app/src/main/kotlin/mx/beti/app/MainActivity.kt - ML assets · Bundled TFLite categorization model and vocab/labels for offline inference.
assets/ml/beti_categorizer.tflite
Connections 28
- 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.