Story Flutter Graphql Operation

Examples:

• graphql/character/character.graphql
• graphql/location/location.graphql

If the domain directory doesn't exist yet, create it.

Step 3 — Write the Operation

Follow the app's established patterns exactly.

Fragment pattern (define once, reuse everywhere):

fragment AllShip on Ship {
  id
  title
  text
  createdAt
  user
  images {
    fileName
    URL
    x
    y
    id
  }
}

Query:

query ships {
  ships(input: {}) {
    ...AllShip
  }
}

query ship($id: Int!) {
  ship(input: { id: $id }) {
    ...AllShip
  }
  posts(input: { id: $id, class: "ships" }) {
    ...PostStandard
  }
}

Mutation:

mutation createShip(
  $title: String!
  $text: String
  $files: [FileInput]
) {
  createShip(
    input: { title: $title, text: $text, files: $files }
  ) {
    ...AllShip
  }
}

Subscription (AI streaming):

subscription ragStreamShip(
  $title: String!
  $text: String
) {
  ragStreamShip(input: { title: $title, text: $text }) {
    text
    done
  }
}

Step 4 — Run Codegen

cd services/mobile && dart run build_runner build --delete-conflicting-outputs

Step 5 — Use the Generated Code

Codegen produces these in [entity].graphql.dart:

Query widget (in a page):

import '../../graphql/ship/ship.graphql.dart';

Query$ships$Widget(
  options: Options$Query$ships(
    pollInterval: const Duration(seconds: 10),
  ),
  builder: (result, {fetchMore, refetch}) {
    if (result.isLoading) return const Center(child: CircularProgressIndicator());
    if (result.hasException) return Center(child: Text('Error: ${result.exception}'));
    final ships = result.parsedData?.ships ?? [];
    // build UI from ships
  },
)

Mutation hook (in a form):

final mutation = useMutation$createShip();

final result = await mutation
    .runMutation(Variables$Mutation$createShip(title: 'My Ship'))
    .networkResult;

if (result?.hasException ?? true) {
  // show error snackbar
} else {
  context.go('/ships');
}

Rules

• Never look at backend server code. The schema tells you everything.
• No service layer, no repository. Widgets use hooks directly.
• Always run codegen after writing or editing a .graphql file.
• Codegen output is read-only. Never manually edit .graphql.dart files.