The Problem

1. Cellular networks often become congested in crowded places, causing messages and calls to fail.

2. People nearby are unable to communicate reliably because they depend on centralized infrastructure.

3. Internet access is not always available in festivals, events, or similar environments.

4. Existing communication tools do not work well for immediate local communication in dense crowds.

5. There is a need for a simple system that enables direct nearby device communication.

Our Solution

Bluetooth-based nearby communication: Chatterbox reduces dependence on mobile networks by using Bluetooth/nearby peer-to-peer communication so nearby devices can exchange messages directly. The app uses flutter_blue_plus to watch Bluetooth state and the nearby_connections package to advertise, discover, connect, and send payloads between devices.

Real-time device discovery and connection: The app keeps track of discovered and connected devices in state, updates the UI when devices appear or disconnect, and lets users connect directly to nearby devices.

Simple onboarding via QR codes: Users can quickly share and add contacts through QR-based invite and scan features. The QR data includes the username, a flag, and the UUID, and the “Add New Contact” button opens the QR scanner screen.

Local data persistence: User identity and chat history are stored locally using shared preferences, so the app can recreate a username, UUID, and chat list when it starts again.

Chat-first local networking approach: The app is organized as a Flutter project with core and features layers, and it includes platform folders for Android, iOS, web, Linux, macOS, and Windows. The current design focuses on nearby communication through the app UI and local device state rather than a custom mesh-routing backend.

Literature Survey

Most modern communication platforms are built around internet connectivity and centralized servers. While this works well in everyday situations, it becomes a clear limitation in crowded environments like festivals or large events, where networks often slow down or fail completely. This has led to growing interest in communication systems that can function independently of traditional infrastructure.

Bluetooth-based device communication allows nearby devices to discover and connect with each other efficiently. Alongside this, peer-to-peer communication frameworks make it possible for devices to exchange data directly without relying on a central server. Methods like QR-based onboarding make setup easier, and local storage helps preserve chats and user identity even when the connection is unstable.

However, many existing solutions are either too basic or not designed for real-world usability. They often require manual setup, lack a smooth user experience, or do not handle contact sharing and chat persistence well.

Chatterbox combines Bluetooth-based discovery, direct device communication, QR-based contact sharing, and local data management into a simple messaging app. The focus is on making nearby communication practical in situations where internet access is unreliable.

Methodology

Bluetooth and Permission Handling

At startup, the app initializes screen utilities, localization, Bluetooth permission handling, and notification permissions. It also checks Bluetooth state and turns Bluetooth on on Android when possible. Separate permission handling is used for Bluetooth, location, storage/media, and nearby Wi-Fi devices depending on the Android version. 

Bluetooth State and Device Discovery

The app uses a Riverpod-based Bluetooth state layer to watch Bluetooth status, manage discovered devices, connected devices, advertising, and discovery state, and expose message streams to the rest of the app. Nearby devices are discovered and connected through the nearby_connections service using Strategy.P2P_STAR.

Messaging Flow

When a message is sent, it is first added to the local chat history and then encoded as JSON before being sent to the connected device over Nearby Connections. Incoming messages are received as byte payloads, converted to text, parsed as JSON, and then added to the correct chat.

Chat and Contact Management

Chats store fields such as the other user’s username, UUID, favorite status, blocked status, and message list. The home screen shows chat rows, lets the user open the QR invite flow, and shows online status based on discovered or connected devices. The chat screen also disables the input area when Bluetooth is off or when a chat is blocked.

Local Storage and Session Initialization

On app startup, the app checks whether a username, UUID, and chat list already exist in local storage. If they do not, it generates a random username, creates a UUID, and initializes an empty chat list. The repository also includes a helper that reads and writes shared preferences and secure storage values.

Localization and UI

The app uses easy_localization. The UI is built in Flutter with a chat screen, message bubble widgets, input fields, and chat options such as rename and attachments. It includes a local notification service that can initialize notifications, request notification permission, and show or schedule notifications with different sound and urgency settings. The chat message model includes message ID, text, sender flag, timestamp, status, and type. The enum definitions already include sending, sent, delivered, and read statuses, and message types for file, voice, text, image, video, and location. The active Bluetooth transport path currently sends text-based JSON payloads.

Implementation

1. Frontend Architecture and User Experience (Flutter/Dart)

The user-facing application was developed using Flutter and Dart, with the project split into core and features folders. The repo also contains platform scaffolding for Android, iOS, web, Linux, macOS, and Windows, which matches a standard cross-platform Flutter setup.

2. Nearby Communication Layer

Bluetooth-based device discovery and communication are handled through Flutter Bluetooth state monitoring plus the Nearby Connections service. The service advertises the local user, discovers peers, accepts connections, and sends raw byte payloads between connected devices.

3. Message Processing Pipeline

Outgoing messages are stored locally first, then serialized into JSON, and then sent to the connected peer. Incoming data is decoded back into a message object and written into the correct chat thread. This keeps the UI responsive while preserving local chat history.

4. QR Code Contact Sharing

The app includes a QR generator for sharing contact data and a scanner flow for adding a new contact. The QR payload is simple and practical for nearby onboarding in crowded places.

5. Local Data Storage

User data is stored locally so the app can recover usernames, UUIDs, and chat lists across restarts. Shared preferences are used for the main stored data, and the helper also supports secure storage.

6. App State and Connectivity Feedback

The home screen shows connection state, discovered devices, and connected devices. The chat screen displays whether the contact is currently connected, and it disables input when Bluetooth is unavailable or the contact is blocked.

7. Localization and Notifications

Uses easy_localization, and it includes a local notification service for future or in-app alerting needs.

Future Scope

1. Support richer message handling for the message types already defined in the model, such as images, video, voice, files, and location.

2. Improve connection stability and recovery when devices move in and out of range.

3. Expand the contact and chat management flow with better search, organization, and message actions.

4. Extend notification behavior for incoming chats and connection events.

5. Add more polish to the multilingual UI and expand localization support if needed.

Acknowledgment

We are grateful for the opportunity to work on this project and gain practical experience in building a Flutter-based nearby communication application.