# bitchat Development Roadmap: BLE Mesh Architecture Overhaul in 3 Phases

> Explore the bitchat development roadmap: A 3-phase overhaul of BLE mesh architecture, moving from a monolithic design to a clean, layered mesh stack for enhanced performance and modularity.

- Repository: [permissionlesstech/bitchat](https://github.com/permissionlesstech/bitchat)
- Tags: getting-started
- Published: 2026-08-20

---

**The bitchat roadmap centers on transforming its BLE transport from a monolithic "god-object" into a clean, layered mesh stack through link-layer extraction, a Sans-I/O engine core with simulator, and modular feature extraction.**

The permissionlesstech/bitchat project is undertaking a foundational architectural restructuring of its Bluetooth Low Energy (BLE) networking layer. According to the official **[BLE-ARCHITECTURE-V3](https://github.com/permissionlesstech/bitchat/blob/main/docs/BLE-ARCHITECTURE-V3.md)** design document, the bitchat development roadmap proceeds through three deliberate phases designed to eliminate race conditions, enable deterministic testing, and prepare the codebase for diverse peer-to-peer features.

## Phase 1: Link-Layer Extraction

The first milestone of the bitchat roadmap moves CoreBluetooth delegates, scheduling, duty-cycle handling, and buffers behind new `LinkEvent` and `LinkCommand` ports.

This extraction eliminates the problematic "check-bind-then-act" race condition by making bindings **engine-owned rather than delegate-owned**. The implementation follows a specific sequence:

1. **Radio-half extraction** — Scanning, advertising, and duty-cycle logic migrate to `BLERadioController` (referenced as [#1539] in planning documents)
2. **Binding and link-auth migration** — Move to `BLELinkAuthState` and `BLELinkBindings` within the engine
3. **Delegate reduction** — CoreBluetooth delegates shrink to simple event emitters

Both steps (a) and (b) are already landed in the codebase as of the V3 document ([lines 131-166](https://github.com/permissionlesstech/bitchat/blob/main/docs/BLE-ARCHITECTURE-V3.md#L131-L166)).

### Key Architecture Constraint

The link-layer extraction enforces **strict concurrency contracts** defined in [lines 54-78](https://github.com/permissionlesstech/bitchat/blob/main/docs/BLE-ARCHITECTURE-V3.md#L54-78) of the architecture document:

- **Engine-confined** — All engine state manipulation occurs on a dedicated serial queue
- **bleQueue-confined** — BLE operations remain isolated to their dispatch queue
- **Lock-backed stores** — Shared state uses explicit locking primitives

These constraints prevent deadlocks by construction rather than by debugging.

## Phase 2: Sans-I/O Engine Core and Simulator

The second phase of the bitchat development roadmap converts the engine into a **pure function** with the signature `handle(event) → [Effect]`.

This Sans-I/O architecture removes all side effects from the core logic, making the engine entirely deterministic. The team drives this core with a `SimulatedLinkLayer` that can:

- Execute property-based tests without real radios
- Run multi-node simulations without wall-clock waits
- Reproduce timing-dependent bugs consistently

The simulator is already functional in `bitchatTests/Simulation/`. Current deterministic tests complete in approximately **40 milliseconds** and have already uncovered a real bug in the announce throttle logic ([lines 194-202](https://github.com/permissionlesstech/bitchat/blob/main/docs/BLE-ARCHITECTURE-V3.md#L194-202)).

### Engine Core Implementation Pattern

```swift
// Engine core handling an event – now a pure function
func handle(_ event: BLELinkEvent) -> [Effect] {
    switch event {
    case .bytesReceived(let id, let payload):
        // Decode, look up binding, produce effects (e.g., forward packet)
        return [.forward(packet: payload, to: id)]
    // … other cases
    }
}

```

## Phase 3: Feature-Module Extraction

The final planned phase extracts each high-level capability into its own module, leaving only a thin transport core in the engine.

Modules planned for extraction include:

- **Courier** — Message relay and store-and-forward
- **Board** — Public topic-based messaging
- **Pre-keys** — Offline encryption key exchange
- **Voice** — Real-time audio streaming
- **File transfer** — Chunked data transmission
- **Groups** — Multi-party conversations
- **Diagnostics** — Network health and debugging
- **Verification** — Identity attestation flows
- **Public archive** — Historical message retention

Each module will own its state and register for its specific message types. The architecture document notes that a **formal effect system** is deferred until all modules are in place.

### Link-Layer Event Emission

Once extraction completes, modules interact with the link layer through clean event interfaces:

```swift
// Emitting a link-layer event (e.g., new bytes received)
let event = BLELinkEvent.bytesReceived(linkID: 42, payload: data)
BLELinkLayer.shared.emitLinkEvent(event)   // Handed to the engine

```

### Simulator Usage for Testing

The deterministic simulator enables rapid iteration on complex scenarios:

```swift
// Using the simulator for deterministic multi-node tests
let sim = SimulatedMesh()
sim.addNode(id: "alice")
sim.addNode(id: "bob")
sim.runScenario(.announceAndBind)   // No real Bluetooth required

```

## Key Source Files in the bitchat Roadmap

| File | Role in Roadmap |
|------|-----------------|
| [`docs/BLE-ARCHITECTURE-V3.md`](https://github.com/permissionlesstech/bitchat/blob/main/docs/BLE-ARCHITECTURE-V3.md) | Canonical roadmap document with line-level references |
| `BLEService+LinkLayerCentralRole.swift` | CoreBluetooth delegate extensions (post-extraction central role) |
| `BLEService+LinkLayerPeripheralRole.swift` | Peripheral-role link-layer implementation |
| [`BLELinkLayer.swift`](https://github.com/permissionlesstech/bitchat/blob/main/BLELinkLayer.swift) | New `BLELinkLayer` class exposing `emitLinkEvent` |
| [`SimulatedMesh.swift`](https://github.com/permissionlesstech/bitchat/blob/main/SimulatedMesh.swift) | Test-only simulator driving the engine core |
| `bitchat/Nostr/` | Core Nostr protocol implementation used by transport |
| [`Package.swift`](https://github.com/permissionlesstech/bitchat/blob/main/Package.swift) | Swift package definition and module structure |

## Summary

- **bitchat's roadmap** follows three phases: link-layer extraction, Sans-I/O engine with simulator, and feature modularization
- **Link-layer extraction** is substantially complete, with `BLERadioController` and `BLELinkAuthState` already landed
- **Sans-I/O engine core** enables 40ms deterministic tests that have already found real bugs
- **Modular feature extraction** will separate courier, board, voice, file transfer, and other capabilities into independent modules
- Strict concurrency contracts (engine-confined, bleQueue-confined, lock-backed stores) prevent deadlocks by design

## Frequently Asked Questions

### What is the current status of the bitchat BLE architecture overhaul?

The link-layer extraction (Phase 1) is largely complete. The `BLERadioController`, `BLELinkAuthState`, and `BLELinkBindings` components are already implemented. The Sans-I/O simulator (Phase 2) is functional and actively catching bugs. Feature-module extraction (Phase 3) remains future work.

### Where can I read the official bitchat development roadmap?

The canonical document is [`docs/BLE-ARCHITECTURE-V3.md`](https://github.com/permissionlesstech/bitchat/blob/main/docs/BLE-ARCHITECTURE-V3.md) in the permissionlesstech/bitchat repository. It contains detailed line references, phase breakdowns, and concurrency contract specifications ([direct link](https://github.com/permissionlesstech/bitchat/blob/main/docs/BLE-ARCHITECTURE-V3.md)).

### How does the bitchat simulator improve testing?

The `SimulatedMesh` class drives the engine core without real Bluetooth hardware or wall-clock delays. Tests run in approximately 40 milliseconds, enable property-based testing across many scenarios, and provide deterministic reproduction of timing-dependent bugs.

### What modules are planned for extraction from the bitchat engine?

The roadmap targets nine feature modules: courier, board, pre-keys, voice, file transfer, groups, diagnostics, verification, and public archive. Each will own its state and message-type registration, communicating through the thin transport core via the `LinkEvent`/`LinkCommand` ports.