/
├── amplify/                    # Shared backend (Gen 2)
│   ├── auth/
│   ├── data/
│   └── functions/
├── packages/
│   ├── web/                    # Next.js app
│   │   ├── src/
│   │   ├── stories/           # Storybook
│   │   └── package.json
│   └── mobile/                # Flutter app
│       ├── lib/
│       ├── widgetbook/        # Widgetbook
│       └── pubspec.yaml
├── .claude/                    # AgentFlow (root level)
├── amplify_outputs.json        # Generated config (at root)
└── package.json               # Workspaces config

{
  "scripts": {
    "postinstall": "cp ../../amplify_outputs.json . 2>/dev/null || true"
  }
}

export PATH="/var/lib/tmux-shared/flutter/bin:$PATH"

flutter run -d web-server --web-port=73000 --web-hostname=0.0.0.0

# pubspec.yaml
environment:
  sdk: ^3.10.0  # Dart 3.10+ required

dev_dependencies:
  widgetbook: ^3.20.0
  widgetbook_annotation: ^3.9.0

packages/mobile/
├── lib/
│   └── components/
│       └── button.dart
└── widgetbook/
    ├── main.dart           # Widgetbook app entry
    └── button.story.dart   # Component stories

cd packages/mobile

# Debug mode (with hot reload) - REQUIRES Flutter 3.38+ / Widgetbook 3.20+
flutter run -d web-server -t widgetbook/main.dart --web-port=PORT --web-hostname=0.0.0.0

# Build release and serve static files
flutter build web -t widgetbook/main.dart --release
python3 -m http.server PORT --directory build/web

// test/components/button_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:aft_mobile/components/button.dart';

void main() {
  testWidgets('Button displays label', (tester) async {
    await tester.pumpWidget(
      MaterialApp(
        home: Button(label: 'Click me'),
      ),
    );

    expect(find.text('Click me'), findsOneWidget);
  });

  testWidgets('Button triggers onPressed', (tester) async {
    var pressed = false;

    await tester.pumpWidget(
      MaterialApp(
        home: Button(
          label: 'Click me',
          onPressed: () => pressed = true,
        ),
      ),
    );

    await tester.tap(find.byType(Button));
    expect(pressed, isTrue);
  });
}

// lib/keys/auth_keys.dart
class AuthKeys {
  static const loginButton = Key('auth_login_button');
  static const emailField = Key('auth_email_field');
  static const passwordField = Key('auth_password_field');
}

// In widget:
ElevatedButton(
  key: AuthKeys.loginButton,
  onPressed: _handleLogin,
  child: Text('Login'),
)

// In test:
await tester.tap(find.byKey(AuthKeys.loginButton));

testWidgets('Button matches golden', (tester) async {
  await tester.pumpWidget(
    MaterialApp(
      home: Button(label: 'Click me'),
    ),
  );

  await expectLater(
    find.byType(Button),
    matchesGoldenFile('goldens/button.png'),
  );
});

# pubspec.yaml
dependencies:
  amplify_flutter: ^2.0.0
  amplify_auth_cognito: ^2.0.0
  amplify_api: ^2.0.0

// packages/web/src/lib/amplify-config.ts
import { Amplify } from 'aws-amplify';
import outputs from '../../amplify_outputs.json';

let configured = false;

export function configureAmplify() {
  if (configured) return;
  try {
    Amplify.configure(outputs);
    configured = true;
  } catch (e) {
    console.warn('Amplify config not available');
  }
}

// packages/web/package.json
{
  "scripts": {
    "postinstall": "cp ../../amplify_outputs.json . 2>/dev/null || true"
  }
}

// lib/amplify_config.dart
import 'dart:convert';
import 'package:flutter/services.dart';

String? _cachedConfig;

/// Load Amplify config from bundled asset
/// Parallel to web's dynamic import approach
Future<String> loadAmplifyConfig() async {
  if (_cachedConfig != null) return _cachedConfig!;

  try {
    final jsonString = await rootBundle.loadString('assets/amplify_outputs.json');
    json.decode(jsonString); // Validate JSON
    _cachedConfig = jsonString;
    return jsonString;
  } catch (e) {
    return _fallbackConfig; // Dev mode fallback
  }
}

const _fallbackConfig = '''
{
  "version": "1",
  "auth": {"user_pool_id": "", "aws_region": "eu-west-2"},
  "data": {"url": "", "aws_region": "eu-west-2"}
}
''';

// lib/main.dart
import 'package:amplify_flutter/amplify_flutter.dart';
import 'package:amplify_auth_cognito/amplify_auth_cognito.dart';
import 'package:amplify_api/amplify_api.dart';
import 'amplify_config.dart';

bool _amplifyConfigured = false;

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await _configureAmplify();
  runApp(const MyApp());
}

Future<void> _configureAmplify() async {
  if (_amplifyConfigured) return;

  try {
    final config = await loadAmplifyConfig();
    await Amplify.addPlugins([AmplifyAuthCognito(), AmplifyAPI()]);
    await Amplify.configure(config);
    _amplifyConfigured = true;
    safePrint('Amplify configured successfully');
  } on AmplifyAlreadyConfiguredException {
    _amplifyConfigured = true;
  } catch (e) {
    safePrint('Error configuring Amplify: $e');
  }
}

# pubspec.yaml
flutter:
  assets:
    - assets/amplify_outputs.json

# scripts/sync-amplify-config.sh
#!/bin/bash
# Run after `npx ampx sandbox` or `ampx deploy`
SOURCE="../../amplify_outputs.json"
DEST="assets/amplify_outputs.json"

if [ -f "$SOURCE" ]; then
  cp "$SOURCE" "$DEST"
  echo "✅ Synced amplify_outputs.json"
else
  echo '{"version":"1","auth":{},"data":{}}' > "$DEST"
fi

// packages/web/src/app/page.tsx
const client = generateClient<Schema>();
const result = await client.models.Todo.list();
// Shows: "No todos yet - API is working!" or "{n} todo(s) found"

// lib/main.dart
Future<void> _fetchTodos() async {
  try {
    const listTodosQuery = '''
      query ListTodos {
        listTodos {
          items { id content isDone }
        }
      }
    ''';

    final request = GraphQLRequest<String>(document: listTodosQuery);
    final response = await Amplify.API.query(request: request).response;

    if (response.errors.isNotEmpty) {
      // Handle GraphQL errors
      return;
    }

    final json = jsonDecode(response.data!) as Map<String, dynamic>;
    final items = (json['listTodos']?['items'] as List?) ?? [];

    // Success: "No todos yet - API is working!" or "{n} todo(s) found"
    _status = items.isEmpty
        ? 'No todos yet - API is working!'
        : '${items.length} todo(s) found';
  } catch (e) {
    // Handle error
  }
}

# .github/workflows/mobile.yml
name: Mobile CI

on:
  push:
    branches: [develop, staging, main]
    paths: ['packages/mobile/**']
  pull_request:
    paths: ['packages/mobile/**']

jobs:
  test:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: packages/mobile
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.24.5'
          channel: 'stable'
      - run: flutter pub get
      - run: flutter test
      - run: flutter analyze

  build-android:
    needs: test
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: packages/mobile
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.24.5'
      - run: flutter pub get
      - run: flutter build apk --release
      - uses: actions/upload-artifact@v4
        with:
          name: android-apk
          path: packages/mobile/build/app/outputs/flutter-apk/app-release.apk

  # Only on staging/main - upload to Play Console internal track
  deploy-android:
    if: github.ref == 'refs/heads/staging' || github.ref == 'refs/heads/main'
    needs: build-android
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: android-apk
      - uses: r0adkll/upload-google-play@v1
        with:
          serviceAccountJsonPlainText: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT }}
          packageName: com.gaininsight.aft
          releaseFiles: app-release.apk
          track: internal

# packages/mobile/codemagic.yaml
workflows:
  ios-staging:
    name: iOS Staging Build
    instance_type: mac_mini_m2
    max_build_duration: 30
    triggering:
      events:
        - push
      branch_patterns:
        - pattern: staging
          include: true
    environment:
      ios_signing:
        distribution_type: app_store
        bundle_identifier: com.gaininsight.aft
      groups:
        - app_store_credentials  # APPLE_ID, APP_STORE_CONNECT_KEY, etc.
      flutter: 3.24.5
    scripts:
      - name: Get dependencies
        script: |
          cd packages/mobile
          flutter pub get
      - name: Run tests
        script: |
          cd packages/mobile
          flutter test
      - name: Build iOS
        script: |
          cd packages/mobile
          flutter build ipa --release --export-options-plist=/Users/builder/export_options.plist
    artifacts:
      - packages/mobile/build/ios/ipa/*.ipa
    publishing:
      app_store_connect:
        auth: integration
        submit_to_testflight: true
      slack:  # (legacy — migrate to Zulip webhook)
        channel: '#mobile-builds'
        notify_on_build_start: false

  ios-production:
    name: iOS Production Release
    instance_type: mac_mini_m2
    max_build_duration: 30
    triggering:
      events:
        - push
      branch_patterns:
        - pattern: main
          include: true
    environment:
      ios_signing:
        distribution_type: app_store
        bundle_identifier: com.gaininsight.aft
      groups:
        - app_store_credentials
      flutter: 3.24.5
    scripts:
      - name: Get dependencies
        script: |
          cd packages/mobile
          flutter pub get
      - name: Build iOS
        script: |
          cd packages/mobile
          flutter build ipa --release --export-options-plist=/Users/builder/export_options.plist
    artifacts:
      - packages/mobile/build/ios/ipa/*.ipa
    publishing:
      app_store_connect:
        auth: integration
        submit_to_testflight: true
        submit_to_app_store: true
      slack:  # (legacy — migrate to Zulip webhook)
        channel: '#releases'

tokens/
├── colors.json
├── typography.json
└── spacing.json
    ↓
style-dictionary build
    ↓
├── packages/web/src/styles/tokens.css
└── packages/mobile/lib/theme/tokens.dart

# Create new Flutter app
flutter create --org com.gaininsight packages/mobile

# Run on Android emulator
flutter run -d emulator-5554

# Run Flutter web (headless for gidev)
flutter run -d web-server --web-port=73000 --web-hostname=0.0.0.0

# Run Widgetbook (debug mode with hot reload)
flutter run -d web-server -t widgetbook/main.dart --web-port=76000 --web-hostname=0.0.0.0

# Run tests
flutter test

# Update golden files
flutter test --update-goldens

# Build Android APK
flutter build apk

# Build Android App Bundle (Play Store)
flutter build appbundle