royalpinto007/Kabootar

kabootar logo

Kabootar

Flag of India

Proudly Made in India

Chat that works with no internet, no servers, no SIM.

Messages hop phone-to-phone over Bluetooth and Wi-Fi and are delivered whenever the other person comes back in range. An offline, serverless mesh messenger built on a delay-tolerant network with epidemic routing, end-to-end encryption, private groups, and image and file sharing.

CI Build APK mesh engine: 32 invariants
Flutter Platform License: MIT PRs welcome Made in India

What it is · How it works · Architecture · Try it · Roadmap · Contributing

[!NOTE] Why this exists. When the network is down or jammed but people are nearby, Kabootar still gets your message through. Dead-zone buildings, basements, exam halls, festivals, protests, stadiums, trains, remote areas, roaming with no plan. Proximity is available even when the internet is not.

Screenshots

Chats, with delivery receipts that travelled back through the mesh. _{Chats. Receipts travel back the same way the message went.}

The mesh: peers in range, messages carried for others, and live routing events. _{Mesh. Peers in range, what you are carrying for other people, and routing as it happens.}

Scanning for nearby phones over Bluetooth and Wi-Fi. _{People. Whoever is running Kabootar within range.}

Channels and private groups, joined with a code. _{Channels. Private groups, joined with a code you share in person.}

_{Captured from the app running on a physical device, with the status and
navigation bars cropped out. Peer counts read zero because only one device was
in range for the capture.}

What it is

Kabootar is a private messenger with no backend at all. Instead of routing through a server, your phone forms a peer-to-peer mesh with other phones nearby. A message you send is flooded to everyone in range, carried onward by each device it reaches, and delivered the moment a chain of carriers connects you to the recipient, even if that is minutes later after you have both walked away.

It feels like a normal chat app, a contact list, saved history, sent/delivered receipts, end-to-end encrypted 1:1 chats and private groups, image and file sharing, but the transport underneath is a store-and-forward mesh rather than the cloud.

	Kabootar	Normal messenger
Needs internet / cell data	No	Yes
Needs a server or account	No	Yes
Works in a signal dead-zone	Yes	No
Your data leaves the device	No	Yes
Delivers to someone offline-then-back	Yes, via carriers	No

✨ Features

📡 Truly offline — Bluetooth + Wi-Fi peer links, zero infrastructure.
🕓 Store-and-forward — messages wait and ride other phones until delivered.
🔐 End-to-end encrypted — X25519 + Ed25519 + AES-GCM, with signed messages and a safety code to verify a contact. Relays only ever see ciphertext.
👥 Private groups — invite-only, encrypted with a shared group key.
🖼️ Image & file sharing — photos are compressed and thumbnailed; any file (up to 8 MB) is chunked and carried across the mesh just like text.
🔔 Notifications — local alerts when a message arrives (no push server).
🌗 Light / dark theme, archive / hide / block, delete-for-everyone, mark-as-unread — the everyday chat controls.
✅ Delivery receipts — end-to-end acks, WhatsApp-style ticks you can trust.
🔁 Self-healing routing — epidemic flooding with idempotent de-duplication.
📶 Live mesh view — watch peers, carried messages, and routing events.
🧪 Provably correct core — 32 routing invariants verified in plain Dart.
🇮🇳 Made in India — open source, no foreign backend.

📨 How your message travels

Alice sends a message to Bob, who is out of range. A relay carries it and delivers it later, then the receipt makes the return trip the same way.

sequenceDiagram
    autonumber
    participant A as Alice
    participant R as Relay (a stranger's phone)
    participant B as Bob (offline, then back)

    A->>R: msg "hey Bob" (flood)
    Note over R: Bob not in range —<br/>R carries the message
    A--xB: no path yet
    Note over A,R: time passes, Alice walks away
    R->>B: link comes up → flush carry
    B->>B: deliver + show message
    B->>R: ack (delivery receipt)
    R->>A: ack carried back
    Note over A: message flips to "delivered" ✓✓

Every phone applies the same six rules to each envelope it sees:

#	Rule	Why it matters
1	De-dup by message id	Idempotency; stops loops and flood storms
2	Learn from a `hello`	Builds the contact list from whoever is near
3	Deliver if it is for me	Save, show, and send an `ack`
4	Receipt on an `ack` for me	Flip my message to delivered
5	Relay + carry otherwise	Decrement TTL, cache, re-flood; carry onward
6	Cap everything	TTL + max-age + cache size bound battery and storage

Why this is interesting (the systems angle)

This is a delay-tolerant network (DTN) using epidemic routing with end-to-end acknowledgements, the same shape as a durable, at-least-once message queue, but running across a swarm of phones instead of a datacenter:

Idempotency by id — a message can arrive by many paths but is acted on once.
At-least-once delivery made exactly-once at the edges via de-dup on the id.
Persisted de-dup set — survives restarts, so a reboot cannot re-flood.
Bounded resources — TTL, max-age, and cache-size caps keep a carrier honest.

The whole routing brain is framework-free Dart (no Flutter, no radio, no DB), which is why its behaviour is pinned down by tests that run on a laptop. See docs/ARCHITECTURE.md.

🧱 Architecture

flowchart TD
    UI["UI · Flutter Material 3<br/>onboarding · chats · people · mesh"]
    SVC["ChatService<br/>the seam: state · hello handshake · ticks"]
    ENG["MeshEngine<br/>DTN routing · pure Dart"]
    DB[("SQLite<br/>messages · contacts · seen")]
    TX["Transport<br/>Nearby / Multipeer P2P"]

    UI --> SVC
    SVC --> ENG
    SVC --> DB
    SVC --> TX
    ENG -. ports .-> SVC
    TX <-->|"Bluetooth + Wi-Fi"| PEERS(("nearby phones"))

    classDef core fill:#4F46E5,stroke:#3730A3,color:#fff;
    class ENG core;

lib/core/mesh — the engine, envelope, config, ports. Zero framework imports.
lib/data — SQLite persistence + identity; the seen set is persisted.
lib/transport — MeshTransport interface + flutter_nearby_connections.
lib/services/chat_service.dart — the single source of truth the UI binds to.
lib/ui — a polished Material 3 messenger, including a live Mesh tab.

🚀 Try it

[!IMPORTANT] The mesh needs two physical phones on the same OS family (Android⇄Android or iOS⇄iOS). Emulators have no real Bluetooth/Wi-Fi radio.

Build & run from source

git clone https://github.com/royalpinto007/Kabootar.git
cd Kabootar

# The Android native shell is committed, so no `flutter create` is needed.
flutter pub get
dart run flutter_launcher_icons    # launcher icon
bash tool/patch_nearby_plugin.sh   # modernise the 2021-era mesh plugin
bash tool/patch_gradle.sh          # core-library desugaring (notifications)
flutter run                        # on a connected Android device

iOS needs a one-time flutter create . --platforms=ios --org dev.studchat to generate its Xcode shell. Full platform notes (permissions, minimum SDKs) are in docs/PLATFORM_SETUP.md.

Grab a prebuilt APK

Grab a signed-per-ABI APK from Releases (pick kabootar-vX.Y.Z-arm64-v8a.apk for most phones). Every push also builds one via the Build APK workflow (open the newest run → Artifacts → kabootar-apks).

Verify the routing engine without a phone

The store-and-forward core is provable on a laptop with just the Dart SDK:

dart run tool/engine_check.dart

── Store-and-forward across time (recipient offline, then returns)
  ✓ nobody delivered yet (C never in range)
  ✓ R is carrying the message for later
  ✓ C finally received it after coming back in range
  ✓ A eventually learns it was delivered
  ...
  32 passed, 0 failed — all mesh-engine invariants hold ✓

🧭 Honest constraints

Designed in up front, so nothing surprises you:

Cross-platform wall — one codebase runs on both, but a message cannot hop across the OS boundary (Android and iOS use different peer radios). v1 meshes within an OS family.
Range and density — delivery needs a chain of carriers to exist. Sparse crowds mean slow or no delivery. Inherent to any mesh.
No forward secrecy yet — encryption uses long-term static keys; a ratcheting scheme is future work. Open channels stay plaintext by design.
Battery — continuous advertise + scan is not free; duty-cycling is planned.

🗺 Roadmap

[x] Onboarding, live peer discovery, 1:1 text chat
[x] Store-and-forward with de-dup, TTL, and end-to-end acks
[x] Persistent history and contacts; resume undelivered on restart
[x] Live mesh diagnostics view
[x] 📢 Channels (broadcast group rooms, joined by code)
[x] 🔐 End-to-end encryption (X25519 + Ed25519 + AES-GCM) + message signing
[x] 👥 Private groups with membership (encrypted, invite-only)
[x] 🖼 Image sharing (compressed, chunked, carried like text)
[x] 📎 Arbitrary file sharing over the same chunk path
[x] 🔔 Local notifications, 🌗 theme, and full chat management
[ ] 🔒 Forward secrecy (a message ratchet on top of the static keys)
[ ] 🔋 Battery duty-cycling
[ ] 🌉 Online bridge: any node with internet relays onward

🇮🇳 Made in India

Built in India, open source, privacy-first. No servers, no foreign backend, no account: your messages and identity never leave your device. Kabootar is the kind of resilient, self-reliant tech that works in India's dead-zones, trains, and crowds, and it belongs to everyone who runs it.

The app carries a tricolour identity and the Ashoka Chakra, and an in-app "India & Kabootar" screen with the Preamble and the Fundamental Duties (Article 51A) for civic reference, plus friendly facts about how the mesh works.

[!NOTE] Kabootar is an independent, citizen-built project. It is not affiliated with or endorsed by any government or political party. National symbols are used respectfully; we deliberately never use the restricted State Emblem (the Lion Capital). See DISCLAIMER.md.

Legal: Privacy Policy · Terms of Use · Disclaimer. Direct chats and private groups are end-to-end encrypted; open channels are public by design and there is no forward secrecy yet, so use your judgement for highly sensitive information.

🤝 Contributing

Contributions are welcome. Good first steps:

Read CONTRIBUTING.md and docs/ARCHITECTURE.md
Keep the mesh engine framework-free and add tests for routing changes
Open an issue or a PR

By participating you agree to the Code of Conduct. Security issues: see SECURITY.md.

⭐ Star this project

If Kabootar is useful or interesting, a star genuinely helps others find it.

GitHub stars

Once the project gathers a few stars, a growth chart will render here via star-history.com.