vital_solver

Pure-Dart nutritional solver for the VITAL FlutterFlow app β€” extracted from 4 monolithic FlutterFlow custom code entities (applyQualityRulesBeforeSolver, macroOptimizerPQDynamicMaxAction, solveSingleMealWithTargets, buildRecipeCreationPreSolveReport) into a portable, testable library.

Status

🚧 Work in progress β€” currently in Phase 1 (bootstrap). See the migration plan at ~/.claude/plans/ok-maintenant-explique-moi-serene-firefly.md.

Phase Status
0 β€” Snapshot regression harness βœ… done (9 fixtures)
1 β€” Package skeleton βœ… done
2 β€” Helpers + portable types βœ… done (115 tests)
3 β€” Migration applyQualityRulesBeforeSolver βœ… done (203 tests, byte-equivalent legacy)
4 β€” Migration macroOptimizerPQDynamicMaxAction βœ… done (212 tests, byte-equivalent legacy)
5 β€” Pipeline + report βœ… done (232 tests, solvePipeline + buildPreSolveReport)
6 β€” Shims FlutterFlow βœ… artifacts ready (3-stage DSL + migration guide + shim refs); deploy gated on Phase 7
7 β€” Package publishable βœ… done (v0.7.0, LICENSE, example, dry-run clean); hosting decision pending (see PUBLISHING.md)
8 β€” Suppression legacy covered by Phase 6 Stage C cleanup

Goals

  1. Unblock SDK push β€” splitting 370KB of custom code into portable Dart so each FlutterFlow entity drops below the 64KB server limit.
  2. Enable automated tests β€” pure Dart logic is testable via dart test, unlike monolithic custom code closures.
  3. Eliminate duplication β€” ~13% of legacy code is duplicated helpers; centralized here.
  4. Decouple from FlutterFlow / Firestore β€” no DocumentReference, no FieldValue, no FF-specific types in the package surface.

Architecture

lib/
β”œβ”€β”€ vital_solver.dart             ← public API exports
└── src/
    β”œβ”€β”€ types/                    ← portable types (no Firestore)
    β”œβ”€β”€ helpers/                  ← toD, asMap, norm, macros (per100g)
    β”œβ”€β”€ quality/                  ← apply_quality_rules + sub-modules
    β”œβ”€β”€ optimizer/                ← coordinate descent + rescue passes
    β”œβ”€β”€ pipeline/                 ← orchestrators
    └── reporting/                ← pre-solve report (warnings, blocking, suggestions)

test/
β”œβ”€β”€ snapshots/                    ← real Firestore cases (Phase 0)
β”œβ”€β”€ legacy/                       ← frozen copies of FF functions (regression baseline)
β”œβ”€β”€ snapshot_regression_test.dart ← compares package output vs legacy
β”œβ”€β”€ sweet_batch_v22b_test.dart    ← V22b cascade scenarios
β”œβ”€β”€ helpers_test.dart
β”œβ”€β”€ quality_test.dart
β”œβ”€β”€ optimizer_test.dart
└── pipeline_test.dart

Usage (target API, Phase 5+)

import 'package:vital_solver/vital_solver.dart';

final output = solveSingleMeal(
  ingredients: [/* IngredientInput list from your data layer */],
  targets: SolverTargets(p: 52, c: 35, l: 17, fiMin: 8),
  context: RecipeContext.standard(),
);

if (output.constraintsOk) {
  // output.gramsById, output.totals, output.diagnostics
} else {
  // Inspect output.errors and output.diagnostics for guidance
}

Development

dart pub get
dart analyze
dart test

License

Private β€” internal use only for VITAL.

Libraries

vital_solver
vital_solver β€” Pure-Dart nutritional solver for the VITAL FlutterFlow app.