Frontend Architecture

// Active indicator: small green dot below icon
if (isSelected)
    Container(
        width: 4, height: 4,
        decoration: BoxDecoration(
            color: VantageColors.growth,  // #10B981
            shape: BoxShape.circle,
        ),
    )

Services (singletons)
├── supabaseServiceProvider        → SupabaseService
├── marketDataServiceProvider      → MarketDataService
├── aiServiceProvider              → AiService
└── syncServiceProvider            → SyncService

Data providers (FutureProvider — Supabase queries)
├── accountsProvider               → List<Account>
├── transactionsProvider           → List<Transaction> (current month)
├── holdingsProvider               → List<Holding>
├── budgetsProvider                → List<Budget>
├── debtSummaryProvider            → DebtSummary
└── insightsProvider               → List<Insight> (undismissed)

Market providers (FutureProvider — FastAPI calls)
├── portfolioFxRatesProvider       → Map<String, double>
├── holdingsWithPricesProvider     → List<HoldingWithPrice>
├── portfolioCostBasisProvider     → double
├── portfolioMarketValueProvider   → double
├── portfolioReturnProvider        → double
└── portfolioSparklineProvider     → List<double> (14 days)

Computed providers
├── dashboardSummaryProvider       → DashboardSummary (net worth, spend, debts)
├── monthlyCashflowProvider        → List<MonthlyCashflow> (6 months)
├── spendByCategoryProvider        → Map<String, double>
└── assetHistoryProvider           → FutureProvider.family (symbol, period)

UI state
├── themeModeProvider              → StateNotifier<ThemeMode>
├── currencyProvider               → StateProvider<String>
└── chatProvider                   → StateNotifier<ChatState>

final transactionsProvider = FutureProvider<List<Transaction>>((ref) async {
    final supabase = ref.watch(supabaseServiceProvider);
    final userId = supabase.currentUserId;
    final startOfMonth = DateTime(DateTime.now().year, DateTime.now().month, 1);
    return supabase.getTransactions(userId, since: startOfMonth);
});

final assetHistoryProvider = FutureProvider.family<List<OhlcvPoint>, AssetHistoryParams>(
    (ref, params) async {
        final service = ref.watch(marketDataServiceProvider);
        return service.getHistory(params.symbol, params.period, params.assetType);
    },
);

class ChatNotifier extends StateNotifier<ChatState> {
    ChatNotifier(this._aiService) : super(ChatState.initial());

    Future<void> sendMessage(String text) async {
        state = state.copyWith(isLoading: true);
        await for (final event in _aiService.streamAsk(text, state.history)) {
            state = _applyEvent(state, event);
        }
    }
}

ref.watch(transactionsProvider).when(
    loading: () => const SkeletonList(),
    error: (e, _) => ErrorCard(message: e.toString()),
    data: (txns) => TransactionList(transactions: txns),
)

abstract final class VantageColors {
    // Semantic accents (shared light + dark)
    static const Color growth  = Color(0xFF10B981); // Mint — gains, positive
    static const Color warning = Color(0xFFF59E0B); // Amber — alerts
    static const Color info    = Color(0xFF3B82F6); // Blue — informational
    static const Color error   = Color(0xFFEF4444); // Red — errors only

    // Dark mode (deep navy — Revolut/Mercury style)
    static const Color darkBackground        = Color(0xFF0A0B0E); // scaffold
    static const Color darkSurface           = Color(0xFF131418); // cards
    static const Color darkSurfaceElevated   = Color(0xFF1C1E26); // elevated cards
    static const Color darkBorder            = Color(0xFF252830);
    static const Color darkTextPrimary       = Color(0xFFF0F2F5);
    static const Color darkTextSecondary     = Color(0xFF6B7280);

    // Light mode
    static const Color lightBackground       = Color(0xFFF1F5F9);
    static const Color lightSurface          = Color(0xFFFFFFFF);
    static const Color lightTextPrimary      = Color(0xFF0F172A);
    static const Color lightTextSecondary    = Color(0xFF64748B);
}

// UI text
static TextStyle headline(BuildContext context) =>
    GoogleFonts.inter(fontSize: 24, fontWeight: FontWeight.w700);

// Financial numbers
static TextStyle amount(BuildContext context) =>
    GoogleFonts.jetBrainsMono(fontSize: 28, fontWeight: FontWeight.w600);

static const double xs  = 4;
static const double sm  = 8;
static const double md  = 16;
static const double lg  = 24;
static const double xl  = 32;
static const double xxl = 48;

void didChangeAppLifecycleState(AppLifecycleState state) {
    if (state == AppLifecycleState.paused ||
        state == AppLifecycleState.hidden) {
        _lastPausedAt = DateTime.now();
    }

    if (state == AppLifecycleState.resumed) {
        // Biometric lock check
        final elapsed = DateTime.now().difference(_lastPausedAt).inSeconds;
        if (elapsed > 30 && _biometricEnabled) {
            _router.go('/lock');
            return;
        }

        // Refresh all providers
        _prefetchProviders();

        // Drain Android notification queue
        NotificationService.drainQueue();

        // Sync local → Supabase
        SyncService.syncAll();

        // Update home screen widgets
        WidgetService.updateAll();
    }
}

Widget buildWidget(Map<String, dynamic> json) => switch (json['type']) {
    'chart'        => AgentChart(data: json),
    'card'         => AgentSummaryCard(data: json),
    'alert'        => AgentAlertCard(data: json),
    'multi_widget' => Column(children: [
        for (final w in json['widgets']) buildWidget(w)
    ]),
    _ => const SizedBox.shrink(),
};