Overview

MacroMath is a Flutter app (iOS and Android) backed by Supabase, with AI from Google Gemini. It adopts a layered architecture driven by the single responsibility principle.

Layers

presentation  →  data  →  core
   (screens)      (models/      (singleton services,
                  repositories)  constants, utilities)

• Presentation (presentation) — screens and reusable visual components. The tabs are wrapped in an IndexedStack (in the MainShell class), which preserves the interface state during navigation.
• Data (data) — models with serialization (fromJson/toJson) and structural value equality (via Equatable); centralizes access to external services.
• Cross-cutting (core) — system constants, global settings and a schema compatibility shim, to safeguard the app during database maintenance windows.

State management

Reactive, lightweight state backed by ValueNotifier / ChangeNotifier. The UI reacts to data changes instantly — for example, the macro rings updating when you log a meal, without reprocessing the screen.

Source of truth and cache

On network failure, the app reads from the Hive cache; queued operations sync with Supabase when the network returns.

Actors and flows

The ecosystem orbits around a main actor — the User — supported by three external entities: Supabase, Google Gemini and Open Food Facts.

Example flow — logging by photo

1. The user photographs the plate (image_picker).
2. The image goes to the AiService, which calls Gemini 2.5 Flash with a strict JSON schema response.
3. The model returns a typed structure; the app parses it and normalizes the macros to the identified portion.
4. The data is saved transactionally to meals and meal_items in Supabase, updating Hive at the same time.
5. The progress rings react immediately via state notification.

Keep reading

• Tech stack — the technologies in detail.
• AI and automation — MacroAI under the hood.
• Security — authentication, encryption and isolation.
• Testing and validation — coverage and quality.