FlowFlutter 🤖💬

A modern, beautiful Flutter mobile chat client for Flowise - your AI chatflow platform. Built with Material Design 3 and featuring a stunning dark theme.

✨ Features

Core Functionality

🔄 Real-time Streaming - Live token-by-token responses via Server-Sent Events (SSE)
💾 Persistent History - Secure local storage of conversations with chatId continuity
⚙️ Flexible Configuration - Easy setup with API host and chatflow ID
🎨 Beautiful Dark Theme - Modern UI inspired by premium AI chat apps
📱 Cross-Platform - iOS, Android, Web, Windows, macOS, Linux support

Advanced Features

📄 Source Documents - Expandable panels showing RAG document sources
🛠️ Tool Usage Display - Visual chips showing which tools the AI used
⏱️ Smart Timestamps - Relative time formatting (e.g., "2m ago", "Today at 14:30")
🚨 Intelligent Error Handling - User-friendly error messages with specific guidance
🔄 Automatic Retry - Exponential backoff for rate limiting (429 errors)
💬 Empty State - Welcoming screen with suggestion chips
🎯 Non-streaming Fallback - Seamless switch between streaming and non-streaming modes

🎨 Design

FlowFlutter features a premium dark theme with:

Navy Blue Background (#1A2332) - Easy on the eyes
Vibrant Blue Accents (#4169FF) - Modern and professional
Cyan Highlights (#00D4FF) - For AI assistant elements
Gradient Message Bubbles - Beautiful visual hierarchy
Roboto Font Family - Clean, readable typography

📸 Screenshots

Coming soon - Add your screenshots here!

🛠️ Tech Stack

Framework: Flutter 3.9.2+
Language: Dart 3.0+
State Management: StatefulWidget with ChangeNotifier patterns (KISS approach)
Storage:
- flutter_secure_storage - Encrypted chatId and message storage
- shared_preferences - App configuration
HTTP Client: http package with custom SSE parsing
UI: Material Design 3 with custom theming
Formatting: intl for timestamps

🚀 Getting Started

Prerequisites

Flutter SDK 3.9.2 or higher
Dart SDK 3.0 or higher
A running Flowise instance
Chatflow ID from your Flowise setup

Installation

Clone the repository

git clone https://github.com/yourusername/flowflutter.git
cd flowflutter

Install dependencies
```
flutter pub get
```

Run the app

# For web
flutter run -d chrome

# For mobile (with device/emulator connected)
flutter run

# For desktop
flutter run -d windows  # or macos, linux

⚙️ Configuration

First Launch

Launch the app - you'll see the chat screen with an empty state
Tap the Settings icon (⚙️) in the top-right corner
Configure:
- API Host: Your Flowise server URL (e.g., https://your-flowise.com)
- Chatflow ID: Your chatflow identifier
- Use Streaming: Toggle for real-time vs batch responses
Tap "Save Settings"
Start chatting!

API Key Security

⚠️ Important: Never hardcode API keys in your app!

For production:

Use a backend proxy that adds the Authorization: Bearer <key> header
Update apiHost to point to your proxy endpoint
Let the proxy handle authentication with Flowise

For development:

Flowise chatflows can be made public (no API key required)
Or use environment-specific configuration

📱 Usage

Chat Features

Send Messages: Type and press Enter or tap the send button
Streaming Responses: Watch AI responses appear in real-time
View Sources: Tap to expand source documents in RAG responses
Tool Information: See which tools the AI used (displayed as chips)
New Chat: Tap the "+" icon to start fresh
Settings: Tap the gear icon to update configuration

Error Handling

The app provides helpful error messages:

"No internet connection" - Check your network
"Invalid API key" - Verify credentials in settings
"Chatflow not found" - Check your Chatflow ID
"Too many requests" - Automatic retry with countdown
"Server error" - Flowise may be down, try later

🏗️ Architecture

lib/
├── main.dart                 # App entry point with theme configuration
├── models/
│   ├── app_config.dart       # Configuration model
│   ├── chat_message.dart     # Message and SourceDocument models
│   └── sse_event.dart        # Server-Sent Events parsing
├── screens/
│   ├── chat_screen.dart      # Main chat interface
│   └── settings_screen.dart  # Configuration screen
├── services/
│   ├── config_store.dart     # SharedPreferences wrapper
│   ├── history_store.dart    # Secure storage for messages
│   └── prediction_service.dart # Flowise API client (streaming/non-streaming)
└── widgets/
    └── message_bubble.dart   # Chat message UI component

Key Design Principles

KISS (Keep It Simple, Stupid): Minimal abstractions, clear code
YOLO (You Only Live Once): Fast MVP, iterate based on feedback
Separation of Concerns: Clear distinction between UI, business logic, and data
Stateful Simplicity: Using built-in Flutter state management (no complex state libraries)

🔄 Development

Running Tests

flutter test

Building for Production

# Android
flutter build apk --release

# iOS
flutter build ios --release

# Web
flutter build web --release

# Desktop
flutter build windows --release  # or macos, linux

Docker Deployment

FlowFlutter can be deployed as a web application using Docker:

Using Pre-built Image

# Pull from GitHub Container Registry
docker pull ghcr.io/xhorizont/flowflutter:latest

# Run the container
docker run -d \
  --name flowflutter \
  -p 8080:80 \
  ghcr.io/xhorizont/flowflutter:latest

# Access at http://localhost:8080

Building Locally

# Build the image
docker build -t flowflutter:local .

# Run the container
docker run -d \
  --name flowflutter \
  -p 8080:80 \
  flowflutter:local

Available Tags

latest - Latest stable release
1.0.x - Specific version
1.0 - Latest 1.0.x version
1 - Latest 1.x.x version

The Docker image:

Multi-stage build for optimal size (~50MB)
Nginx serving Flutter web build
Health check included
Multi-architecture support (linux/amd64, linux/arm64)

Hot Reload

While developing:

Press r in terminal for hot reload
Press R for hot restart
Press q to quit

🐛 Troubleshooting

CORS Issues (Web)

If running on web and getting CORS errors:

Configure Flowise with:

CORS_ORIGINS=http://localhost:8080
IFRAME_ORIGINS=http://localhost:8080

Or use a proxy server to bypass CORS

Streaming Not Working

Ensure Flowise version is 2.1.0+ for reliable SSE support
Check useStreaming toggle in settings
Verify network allows SSE connections

Messages Not Persisting

flutter_secure_storage may have issues on some platforms
Check app permissions for storage access
Try clearing app data and reconfiguring

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📋 Roadmap

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Flowise - The amazing AI chatflow platform
Flutter - Beautiful native apps framework
Material Design 3 - Design system

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Flowise Docs: docs.flowiseai.com

🌟 Star History

If you find this project useful, please consider giving it a star! ⭐

Built with ❤️ using Flutter and Flowise