The project faced a critical inflection point. An established native iOS application, written in Swift with UIKit, needed to coexist with a series of new, rapidly developed features built using Flutter. The core technical pain point wasn’t UI, but data consistency and developer velocity. The existing iOS architecture relied on a constellation of REST endpoints, leading to state management divergence, duplicated business logic on the client, and significant friction when building composite UI. A unified data layer was not a luxury; it was a necessity for survival.
Our initial concept was to build a single backend-for-frontend (BFF) that could serve both the legacy iOS client and the new Flutter modules. This immediately brought GraphQL to the forefront. Its schema-driven approach and ability to let clients request exactly what they need would eliminate the over-fetching problems of our REST APIs and provide a single source of truth for our data model. The backend choice was Node.js, primarily for its mature GraphQL ecosystem and our team’s existing expertise. For cloud infrastructure, we were already invested in Alibaba Cloud, so leveraging ECS for compute, RDS for persistence, and API Gateway for security and traffic management was the logical path.
The real contention arose on the client-side strategy. For the new Flutter modules, we wanted a declarative, component-driven data-fetching model inspired by Relay. The elegance of co-locating data dependencies with UI components via fragments is a massive productivity boost. The problem, of course, is that Relay is a JavaScript framework, deeply integrated with the React component lifecycle. Flutter has no such equivalent. The architectural decision was therefore not to adopt an existing library, but to engineer a bespoke, lightweight, Relay-inspired data-fetching engine for Flutter. This engine would need to communicate with our Node.js GraphQL server, manage a normalized client-side cache, and provide a declarative API for Flutter widgets.
The architecture can be visualized as follows:
graph TD
subgraph Clients
FlutterApp[Flutter App with Custom Relay Engine]
LegacyIOS[Legacy iOS App]
end
subgraph Alibaba Cloud
APIGateway[API Gateway
AuthN/AuthZ, Rate Limiting]
subgraph VPC
ECS[ECS Instance: Node.js/Apollo Server]
RDS[RDS for PostgreSQL]
end
end
FlutterApp -- "Custom JSON Payload (GraphQL Fragments)" --> APIGateway
LegacyIOS -- "Standard GraphQL Query" --> APIGateway
APIGateway -- "Forward Request" --> ECS
ECS -- "GraphQL Resolvers" --> RDS
We would build the Node.js backend first, establishing the GraphQL schema and resolvers. Then, we would tackle the most challenging piece: the custom Flutter engine that mimics Relay’s core principles.
Backend Implementation: Node.js and Apollo Server on ECS
The foundation is a robust GraphQL server. We chose Apollo Server for its feature set and ease of use. The project structure is standard for a Node.js application intended for containerization.
Here is the core package.json defining our dependencies:
{
"name": "unified-bff-server",
"version": "1.0.0",
"description": "GraphQL BFF for iOS and Flutter clients",
"main": "src/index.js",
"type": "module",
"scripts": {
"start": "node src/index.js",
"test": "echo \"Error: no test specified\" && exit 1"
},
"dependencies": {
"@apollo/server": "^4.9.5",
"graphql": "^16.8.1",
"graphql-tag": "^2.12.6",
"winston": "^3.11.0"
}
}The server needs a schema. This schema defines the contract for both clients. A pitfall here is designing a schema too closely tied to one client’s view models. It must be generic enough to serve both native iOS and Flutter.
src/schema.graphql
type Query {
project(id: ID!): Project
user(id: ID!): User
}
"""
Represents a single project within the system.
"""
type Project {
id: ID!
name: String!
description: String
status: ProjectStatus!
owner: User!
tasks(first: Int = 10): [Task!]
}
"""
Represents a user account.
"""
type User {
id: ID!
name: String!
email: String!
avatarUrl: String
}
"""
Represents a task within a project.
"""
type Task {
id: ID!
title: String!
completed: Boolean!
assignee: User
}
enum ProjectStatus {
IN_PROGRESS
COMPLETED
ARCHIVED
}Next, the server implementation with resolvers. In a real-world project, the dataSources would connect to databases or other microservices. Here, we use mock data to focus on the server structure. We also incorporate basic logging with Winston, which is critical for debugging in a containerized environment on ECS.
src/logger.js
import winston from 'winston';
const logger = winston.createLogger({
level: 'info',
format: winston.format.combine(
winston.format.timestamp(),
winston.format.json()
),
transports: [
// In production, you'd log to a file or a logging service.
// For ECS, logging to console is standard practice as logs are
// collected by services like Alibaba Cloud Log Service.
new winston.transports.Console({
format: winston.format.simple(),
}),
],
});
export default logger;src/index.js
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { readFileSync } from 'fs';
import logger from './logger.js';
// Mock data sources - replace with actual database connectors.
const mockData = {
users: {
'1': { id: '1', name: 'Alice', email: '[email protected]', avatarUrl: 'url1' },
'2': { id: '2', name: 'Bob', email: '[email protected]', avatarUrl: 'url2' },
},
tasks: {
'101': { id: '101', title: 'Design new dashboard', completed: true, assigneeId: '1' },
'102': { id: '102', title: 'Implement API gateway', completed: false, assigneeId: '2' },
'103': { id: '103', title: 'Setup CI/CD pipeline', completed: false, assigneeId: '1' },
},
projects: {
'p1': { id: 'p1', name: 'Project Phoenix', description: 'Next-gen platform', status: 'IN_PROGRESS', ownerId: '1', taskIds: ['101', '102'] },
},
};
const typeDefs = readFileSync('./src/schema.graphql', { encoding: 'utf-8' });
const resolvers = {
Query: {
project: (_, { id }) => {
logger.info(`Fetching project with id: ${id}`);
if (!mockData.projects[id]) {
throw new Error(`Project with id ${id} not found.`);
}
return mockData.projects[id];
},
user: (_, { id }) => {
logger.info(`Fetching user with id: ${id}`);
return mockData.users[id];
},
},
Project: {
owner: (project) => {
logger.info(`Resolving owner for project ${project.id}, ownerId: ${project.ownerId}`);
return mockData.users[project.ownerId];
},
tasks: (project, { first }) => {
logger.info(`Resolving tasks for project ${project.id}`);
return project.taskIds.slice(0, first).map(taskId => mockData.tasks[taskId]);
},
},
Task: {
assignee: (task) => {
if (!task.assigneeId) return null;
logger.info(`Resolving assignee for task ${task.id}, assigneeId: ${task.assigneeId}`);
return mockData.users[task.assigneeId];
},
},
};
const server = new ApolloServer({
typeDefs,
resolvers,
});
// A common mistake is to forget proper error handling and health checks.
// The `listen` options are critical for production deployments.
const startServer = async () => {
try {
const { url } = await startStandaloneServer(server, {
listen: { port: 4000, host: '0.0.0.0' },
});
logger.info(`🚀 Server ready at ${url}`);
} catch(error) {
logger.error('Failed to start server', { error: error.message });
process.exit(1);
}
};
startServer();To deploy this on Alibaba Cloud ECS, we containerize it.
Dockerfile
# Use an official Node.js runtime as a parent image
FROM node:18-alpine
# Set the working directory in the container
WORKDIR /usr/src/app
# Copy package.json and package-lock.json
COPY package*.json ./
# Install any needed packages
RUN npm install
# Bundle app source
COPY . .
# Make port 4000 available to the world outside this container
EXPOSE 4000
# Define the command to run your app
CMD [ "npm", "start" ]This Docker image can be pushed to Alibaba Cloud Container Registry (ACR) and deployed to an ECS instance. The final step is configuring API Gateway to route traffic from a public endpoint to the private IP of the ECS instance on port 4000, adding JWT validation or other security policies as needed.
The Flutter “Micro-Relay” Engine
This is the most novel part of the solution. We need to create a system in Flutter that allows widgets to declaratively state their data requirements without knowing how the data is fetched.
Our engine has three main components:
- The Normalized Cache: A simple
Mapacting as a client-side database, keyed by a global unique ID (__typename:id). - Fragment Widgets: A custom
StatelessWidgetsubclass that widgets can extend to define their data fragments. - The Query Container: A widget that traverses its descendants, collects all fragments, aggregates them into a single GraphQL query, fetches the data, normalizes it into the cache, and rebuilds.
Let’s start with the cache and the core data handling logic.
lib/relay_engine/store.dart
import 'package:flutter/foundation.dart';
// A simple in-memory normalized cache.
// In a real application, this might be backed by a persistent store like Hive or Isar.
class RelayStore with ChangeNotifier {
final Map<String, Map<String, dynamic>> _data = {};
Map<String, dynamic>? get(String dataId) {
return _data[dataId];
}
void put(String dataId, Map<String, dynamic> record) {
if (_data.containsKey(dataId)) {
_data[dataId]!.addAll(record);
} else {
_data[dataId] = record;
}
}
// The normalization process is the key to avoiding data duplication.
// It traverses the GraphQL response and splits it into flat records.
void normalize(Map<String, dynamic> response) {
_normalizeRecursive(response);
// After normalization, notify listeners so widgets can rebuild.
notifyListeners();
}
void _normalizeRecursive(dynamic json) {
if (json is Map<String, dynamic>) {
// A common mistake is not handling the __typename field properly.
// It's essential for creating the unique ID.
if (json.containsKey('__typename') && json.containsKey('id')) {
final dataId = '${json['__typename']}:${json['id']}';
final record = <String, dynamic>{};
json.forEach((key, value) {
if (value is Map<String, dynamic>) {
// If the value is another object, replace it with a reference
// and normalize the nested object.
if (value.containsKey('__typename') && value.containsKey('id')) {
final nestedId = '${value['__typename']}:${value['id']}';
record[key] = {'__ref': nestedId};
_normalizeRecursive(value);
}
} else if (value is List) {
// Handle lists of objects.
record[key] = value.map((item) {
if (item is Map<String, dynamic> && item.containsKey('__typename') && item.containsKey('id')) {
final nestedId = '${item['__typename']}:${item['id']}';
_normalizeRecursive(item);
return {'__ref': nestedId};
}
return item;
}).toList();
} else {
record[key] = value;
}
});
put(dataId, record);
} else {
// If it's not a normalizable object, just recurse into its values.
json.values.forEach(_normalizeRecursive);
}
} else if (json is List) {
json.forEach(_normalizeRecursive);
}
}
}Now, the declarative part. We’ll create an abstract widget that forces implementers to define a fragment.
lib/relay_engine/fragment_widget.dart
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'store.dart';
// This structure represents the data requirements for a widget.
class GQLFragment {
final String onType;
final List<String> fields;
GQLFragment({required this.onType, required this.fields});
}
// This abstract class is the core of the declarative API.
// Widgets extend this instead of StatelessWidget or StatefulWidget.
abstract class FragmentWidget<T> extends StatelessWidget {
final String dataId;
const FragmentWidget({super.key, required this.dataId});
// Subclasses MUST implement this to define their data needs.
GQLFragment get fragment;
// Subclasses implement this build method, which receives the fully
// resolved data from the cache.
Widget build(BuildContext context, T data);
// The main build method reads from the store and denormalizes the data.
Widget build(BuildContext context) {
// This is where the magic happens. We listen to the store for changes.
return Consumer<RelayStore>(
builder: (context, store, child) {
final Map<String, dynamic>? data = _denormalize(store, dataId);
if (data == null) {
// In a real app, you'd show a loading shimmer.
return const Center(child: Text("Loading fragment..."));
}
// This is a simplified deserialization. A production app
// would use code generation (e.g., freezed, json_serializable).
final typedData = _mapToType(data);
return build(context, typedData);
},
);
}
// This is a placeholder for a proper deserialization factory.
T _mapToType(Map<String, dynamic> data);
// Denormalization reads the root record and follows references (__ref)
// to reconstruct the nested data structure the widget expects.
Map<String, dynamic>? _denormalize(RelayStore store, String id) {
final record = store.get(id);
if (record == null) return null;
final result = <String, dynamic>{};
record.forEach((key, value) {
if (value is Map<String, dynamic> && value.containsKey('__ref')) {
result[key] = _denormalize(store, value['__ref']);
} else if (value is List) {
result[key] = value.map((item) {
if (item is Map<String, dynamic> && item.containsKey('__ref')) {
return _denormalize(store, item['__ref']);
}
return item;
}).toList();
} else {
result[key] = value;
}
});
return result;
}
}Finally, the QueryContainer that orchestrates everything. Its job is to find all FragmentWidget descendants, collect their fragments, build a query, and execute it.
lib/relay_engine/query_container.dart
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'package:provider/provider.dart';
import 'fragment_widget.dart';
import 'store.dart';
// For simplicity, we manage state directly in the StatefulWidget.
// In a larger app, this logic might move to a Riverpod provider or a BLoC.
class QueryContainer extends StatefulWidget {
final Widget child;
final String queryName;
final Map<String, dynamic> variables;
const QueryContainer({
super.key,
required this.child,
required this.queryName,
required this.variables,
});
State<QueryContainer> createState() => _QueryContainerState();
}
class _QueryContainerState extends State<QueryContainer> {
bool _isLoading = true;
String? _error;
void initState() {
super.initState();
// This is a deferred execution to ensure the child widgets are laid out
// and we can traverse the tree to find their fragments.
WidgetsBinding.instance.addPostFrameCallback((_) {
_fetchData();
});
}
String _buildQuery() {
// This is a naive implementation of fragment collection.
// It walks the element tree to find the `FragmentWidget` instances.
// A more performant solution might use a shared context.
final fragments = <GQLFragment>[];
void visit(Element element) {
if (element.widget is FragmentWidget) {
fragments.add((element.widget as FragmentWidget).fragment);
}
element.visitChildren(visit);
}
context.visitChildElements(visit);
// Aggregate fragments into a single GraphQL query string.
// IMPORTANT: This requires adding `__typename` to every selection set
// so the normalization logic can work correctly.
final fragmentStrings = fragments.toSet().map((f) => '''
... on ${f.onType} {
__typename
id
${f.fields.join('\n')}
}
''').join('\n');
final variableDefinitions = r'($id: ID!)';
final queryArguments = r'(id: $id)';
return '''
query ${widget.queryName}$variableDefinitions {
project$queryArguments {
__typename
id
${fragmentStrings}
}
}
''';
}
Future<void> _fetchData() async {
setState(() {
_isLoading = true;
_error = null;
});
try {
final query = _buildQuery();
// In a production app, the URI should come from a configuration service.
final uri = Uri.parse('YOUR_ALIBABA_CLOUD_API_GATEWAY_ENDPOINT');
final response = await http.post(
uri,
headers: {'Content-Type': 'application/json'},
body: json.encode({
'query': query,
'variables': widget.variables,
}),
);
if (response.statusCode == 200) {
final body = json.decode(response.body);
if (body['errors'] != null) {
throw Exception(body['errors'][0]['message']);
}
// This is the critical step: normalize the response into the store.
// The `Provider` will then notify all listening `FragmentWidget`s.
context.read<RelayStore>().normalize(body['data']);
} else {
throw Exception('Failed to load data: ${response.statusCode}');
}
} catch (e) {
setState(() {
_error = e.toString();
});
} finally {
setState(() {
_isLoading = false;
});
}
}
Widget build(BuildContext context) {
if (_isLoading) {
return const Center(child: CircularProgressIndicator());
}
if (_error != null) {
return Center(child: Text('Error: $_error'));
}
return widget.child;
}
}Putting It All Together: A Flutter Screen
Now we can build a screen composed of multiple widgets, each defining its own data dependency.
First, let’s define our data models and the FragmentWidget implementations.
lib/widgets/project_header.dart
import 'package:flutter/material.dart';
import 'package:unified_data_layer/relay_engine/fragment_widget.dart';
// Data class for this widget
class ProjectHeaderData {
final String name;
final String status;
ProjectHeaderData({required this.name, required this.status});
}
class ProjectHeader extends FragmentWidget<ProjectHeaderData> {
const ProjectHeader({super.key, required super.dataId});
GQLFragment get fragment => GQLFragment(
onType: 'Project',
fields: ['name', 'status'],
);
ProjectHeaderData _mapToType(Map<String, dynamic> data) {
return ProjectHeaderData(name: data['name'], status: data['status']);
}
Widget build(BuildContext context, ProjectHeaderData data) {
return Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(data.name, style: Theme.of(context).textTheme.headlineMedium),
Text('Status: ${data.status}', style: Theme.of(context).textTheme.bodySmall),
],
);
}
}lib/widgets/project_owner_card.dart
import 'package:flutter/material.dart';
import 'package:unified_data_layer/relay_engine/fragment_widget.dart';
class ProjectOwnerData {
final String name;
final String? avatarUrl;
ProjectOwnerData({required this.name, this.avatarUrl});
}
class ProjectOwnerCard extends FragmentWidget<ProjectOwnerData> {
const ProjectOwnerCard({super.key, required super.dataId});
GQLFragment get fragment => GQLFragment(
onType: 'Project',
fields: ['owner { __typename id name avatarUrl }'],
);
ProjectOwnerData _mapToType(Map<String, dynamic> data) {
final owner = data['owner'];
return ProjectOwnerData(name: owner['name'], avatarUrl: owner['avatarUrl']);
}
Widget build(BuildContext context, ProjectOwnerData data) {
return Card(
child: ListTile(
leading: CircleAvatar(
// In a real app, use a CachedNetworkImage
child: Text(data.name.substring(0, 1)),
),
title: const Text('Project Owner'),
subtitle: Text(data.name),
),
);
}
}Finally, the main screen combines them under a QueryContainer.
lib/main.dart
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:unified_data_layer/relay_engine/query_container.dart';
import 'package:unified_data_layer/relay_engine/store.dart';
import 'package:unified_data_layer/widgets/project_header.dart';
import 'package:unified_data_layer/widgets/project_owner_card.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
Widget build(BuildContext context) {
// Provide the store at the top of the widget tree.
return ChangeNotifierProvider(
create: (_) => RelayStore(),
child: MaterialApp(
title: 'Unified Data Demo',
theme: ThemeData(primarySwatch: Colors.blue),
home: const ProjectScreen(projectId: 'p1'),
),
);
}
}
class ProjectScreen extends StatelessWidget {
final String projectId;
const ProjectScreen({super.key, required this.projectId});
Widget build(BuildContext context) {
// The dataId is constructed from the typename and the ID.
// This needs to be known beforehand or passed down.
final projectDataId = 'Project:$projectId';
return Scaffold(
appBar: AppBar(title: const Text('Project Details')),
body: QueryContainer(
queryName: 'ProjectDetailQuery',
variables: {'id': projectId},
child: Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
// Both widgets are descendants of QueryContainer.
// Their fragments will be automatically collected.
ProjectHeader(dataId: projectDataId),
const SizedBox(height: 20),
ProjectOwnerCard(dataId: projectDataId),
],
),
),
),
);
}
}The key result here is that ProjectScreen does not know or care about the specific data fields needed by ProjectHeader or ProjectOwnerCard. If the ProjectOwnerCard designer decides they also need the owner’s email, they only need to modify the fragment in project_owner_card.dart. The query aggregation logic in QueryContainer will automatically pick up the change and fetch the new field, without any modification to the parent screen. This achieves the desired co-location and modularity.
This implementation is a proof-of-concept, and it carries significant technical debt. The fragment collection via tree traversal is inefficient and should be optimized, perhaps by using a build-time code generator (build_runner) to create a manifest of fragments. The current system lacks support for mutations, subscriptions, and Relay’s powerful pagination (@connection) directive. Furthermore, the manual denormalization and type mapping (_mapToType) is boilerplate-heavy and error-prone; code generation is the only viable long-term solution here. This bespoke engine imposes a learning curve on new developers, a trade-off made consciously to bridge a specific technological gap. Its applicability is limited to scenarios where this exact cross-stack problem exists and where the investment in building and maintaining a custom data layer is justified by the gains in developer velocity for feature teams.
