Flutter Frontend - AppFlowy

The AppFlowy Flutter frontend provides a rich, cross-platform user interface with native performance on desktop and mobile platforms.

Project Structure

The Flutter app is located in frontend/appflowy_flutter/ with the following structure:

appflowy_flutter/
├── lib/                    # Main application code
│   ├── core/              # Core utilities and configuration
│   ├── features/          # Feature modules
│   ├── plugins/           # Plugin system
│   ├── shared/            # Shared widgets and utilities
│   ├── startup/           # Application initialization
│   ├── user/              # User management
│   ├── workspace/         # Workspace management
│   ├── mobile/            # Mobile-specific code
│   └── main.dart          # Application entry point
├── packages/              # Local packages
│   └── appflowy_backend/  # FFI bindings to Rust
├── assets/                # Images, fonts, icons
├── integration_test/      # Integration tests
├── test/                  # Unit tests
└── pubspec.yaml           # Dependencies

Key Directories

`/lib/core/`

Core application infrastructure:

config: App configuration and environment variables
helpers: Utility functions and helpers
notification: Notification handling from Rust backend

`/lib/features/`

Feature-based modules organized by domain:

workspace

Workspace management, sidebar, and navigation

settings

User settings, preferences, and account management

view_management

View creation, deletion, and organization

shared_section

Shared workspaces and collaboration features

`/lib/plugins/`

The plugin system enables extensible document types:

Plugin	Description
`document`	Rich text editor with blocks and formatting
`database`	Grid, board, calendar, and kanban views
`ai_chat`	AI-powered chat interface
`blank`	Blank page template
`database_document`	Database with embedded document

Each plugin implements the Plugin interface and registers itself with the plugin system.

`/lib/shared/`

Reusable components and utilities:

widgets: Common UI components (buttons, dialogs, inputs)
bloc: Shared BLoC state management classes
models: Shared data models
styles: Theme and styling constants

`/lib/mobile/`

Mobile-specific implementations:

application: Mobile app state management
presentation: Mobile-optimized screens and widgets

State Management

AppFlowy uses the BLoC (Business Logic Component) pattern for state management:

// Example BLoC structure
class DocumentBloc extends Bloc<DocumentEvent, DocumentState> {
  DocumentBloc({
    required this.documentId,
  }) : super(DocumentState.initial()) {
    on<DocumentEvent>(_onDocumentEvent);
  }
  
  Future<void> _onDocumentEvent(
    DocumentEvent event,
    Emitter<DocumentState> emit,
  ) async {
    // Handle events and emit states
  }
}

BLoC Pattern Benefits

Separation of Concerns

Business logic is separated from UI, making code more maintainable

Testability

BLoCs can be easily unit tested without UI dependencies

Reusability

Business logic can be shared across different widgets

Predictability

State changes follow a unidirectional data flow

FFI Integration

The Flutter app communicates with the Rust backend through FFI:

Package Structure

packages/appflowy_backend/
├── lib/
│   └── dispatch/          # Event dispatch to Rust
├── macos/                 # macOS native code
├── ios/                   # iOS native code
├── android/               # Android native code
├── linux/                 # Linux native code
└── windows/               # Windows native code

Event Dispatch

Create event request

final request = UserEventGetUserProfile();

Dispatch to Rust

final result = await UserEventGetUserProfile().send();

Handle response

result.fold(
  (userProfile) => print('Success: ${userProfile.name}'),
  (error) => print('Error: $error'),
);

Code Generation

Protobuf definitions are used to generate Dart classes:

# Generate Dart code from .proto files
flutter pub run build_runner build

Application Lifecycle

Initialization Flow

main.dart entry

Application starts in main.dart with runAppFlowy()

Startup initialization

The startup/ module initializes core services:

Rust backend initialization
Dependency injection setup
Theme and localization

Authentication check

Check if user is logged in and load workspace

Render UI

Display the main workspace or login screen

Main Entry Point

// lib/main.dart
import 'package:scaled_app/scaled_app.dart';
import 'startup/startup.dart';

Future<void> main() async {
  ScaledWidgetsFlutterBinding.ensureInitialized(
    scaleFactor: (_) => 1.0,
  );
  
  await runAppFlowy();
}

Dependency Injection

AppFlowy uses the GetIt service locator for dependency injection:

// Register services
getIt.registerLazySingleton<AuthService>(() => AuthService());

// Access services
final authService = getIt<AuthService>();

Platform-Specific Code

Desktop vs Mobile

AppFlowy provides different UI implementations for desktop and mobile:

Desktop
Mobile

if (PlatformExtension.isDesktop) {
  return DesktopHomeScreen();
}

if (PlatformExtension.isMobile) {
  return MobileHomeScreen();
}

Responsive Design

The app uses responsive layouts that adapt to screen size:

LayoutBuilder(
  builder: (context, constraints) {
    if (constraints.maxWidth > 800) {
      return DesktopLayout();
    } else {
      return MobileLayout();
    }
  },
)

Testing

Test Structure

test/
├── bloc/           # BLoC unit tests
├── widget/         # Widget tests
└── util/           # Utility tests

integration_test/
└── *.dart          # Integration tests

Running Tests

cd appflowy_flutter
flutter test

Dependencies

Key Flutter packages used in AppFlowy:

Package	Purpose
`flutter_bloc`	State management with BLoC pattern
`get_it`	Service locator for dependency injection
`ffi`	Foreign function interface to Rust
`freezed`	Code generation for immutable classes
`protobuf`	Protocol buffer serialization
`flutter_localizations`	Internationalization support
`provider`	Simple dependency injection
`go_router`	Declarative routing

See pubspec.yaml for the complete list of dependencies and versions.

Development Workflow

Install dependencies

cd frontend/appflowy_flutter
flutter pub get

Generate code

flutter pub run build_runner build --delete-conflicting-outputs

Run the app

flutter run

Architecture

Building from Source

Contributing

​Project Structure

​Key Directories

​/lib/core/

​/lib/features/

workspace

settings

view_management

shared_section

​/lib/plugins/

​/lib/shared/

​/lib/mobile/

​State Management

​BLoC Pattern Benefits

Separation of Concerns

Testability

Reusability

Predictability

​FFI Integration

​Package Structure

​Event Dispatch

​Code Generation

​Application Lifecycle

​Initialization Flow

​Main Entry Point

​Dependency Injection

​Platform-Specific Code

​Desktop vs Mobile

​Responsive Design

​Testing

​Test Structure

​Running Tests

​Dependencies

​Development Workflow

​Next Steps

Rust Backend

Building Desktop

Build docs developers (and LLMs) love

Project Structure

Key Directories

`/lib/core/`

`/lib/features/`

`/lib/plugins/`

`/lib/shared/`

`/lib/mobile/`

State Management

BLoC Pattern Benefits

FFI Integration

Package Structure

Event Dispatch

Code Generation

Application Lifecycle

Initialization Flow

Main Entry Point

Dependency Injection

Platform-Specific Code

Desktop vs Mobile

Responsive Design

Testing

Test Structure

Running Tests

Dependencies

Development Workflow

Next Steps