# Synantisi Nearby Connections — Native Bridge Draft

> Status: design / implementation note  
> Date: 2026-09-08

## Recommendation

Use **Google Nearby Connections** as the first serious candidate for Synantisi's
native nearby transport.

It fits the Synantisi requirement unusually well:

- nearby devices can advertise/discover without Internet connectivity;
- Android and iOS are both supported;
- the SDK abstracts Bluetooth/BLE/Wi-Fi transport details;
- both sides accept a connection;
- data can be exchanged as small byte payloads after connection;
- the application does not need to expose GPS coordinates merely to discover a
  nearby Synantisi endpoint.

## Important correction

Do **not** specify a rigid transport sequence such as:

> BLE discovery → always upgrade to Wi-Fi Direct.

Google's current Nearby Connections documentation says it uses a combination of
Bluetooth, BLE and Wi-Fi technologies and abstracts the underlying choice.

The app should treat transport selection as the SDK's job.

## This cannot be done by an AI prompt

An AI/Markdown file can:
- define the Synantisi protocol;
- define Match Card encoding;
- generate native source code;
- help test matching logic.

It cannot obtain Bluetooth/local-network radio access by prompting alone.

Nearby Connections needs a native app integration.

## Android

Use the Google Play services Nearby Connections SDK.

The app must request the relevant runtime permissions. Depending on Android
version/target, these include Bluetooth scan/connect/advertise, location and/or
local-network permissions.

If required permissions are denied, advertising/discovery does not run.

## iPhone / iOS

Use Google's Nearby Connections Swift package.

The app requires Bluetooth and local-network usage descriptions/permissions in
`Info.plist`, plus the Bonjour service declaration generated from the service ID.

## API key?

Current Nearby **Connections** getting-started documentation does not instruct
developers to obtain the old Nearby Messages API key.

Do not confuse Nearby Connections with the deprecated **Nearby Messages** API,
which did require API-key setup.

Synantisi does need a stable service ID so only the intended application/service
is discovered.

## Suggested Synantisi flow

```text
START WALKABOUT 30
        ↓
native app starts Nearby advertising + discovery
        ↓
opaque rotating Synantisi endpoint/session id
        ↓
nearby Synantisi device found
        ↓
connection request
        ↓
mutual authentication/acceptance
        ↓
exchange minimum Match Cards
        ↓
local mutual-match evaluation
        ↓
"mutual match available"
        ↓
both accept
        ↓
Introduction Card
```

Do not broadcast a readable private profile in the discovery advertisement.

## Match payload

For early prototypes use a compact versioned byte payload rather than premature
bit-packing cleverness.

Example conceptual payload:

```yaml
v: 1
session: rotating-token
purpose_bits: ...
interest_bits: ...
style_bands: ...
```

Once the field dictionary is stable, pack it efficiently.

Google Nearby Connections supports byte payloads comfortably larger than
Synantisi needs for a Match Card, so privacy/versioning matter more than shaving
the first prototype down to a handful of characters.

## Security

Use the connection verification/authentication mechanisms recommended by Nearby
Connections.

A discovered endpoint is not automatically trusted.

Synantisi's `STOP`, `DECLINE`, `BLOCK`, `REPORT` and consent gates remain above
the transport layer.

## Architecture boundary

```text
Synantisi Protocol
      ↓
Match Vector / consent state
      ↓
Native Nearby Bridge
      ↓
Google Nearby Connections
      ↓
Bluetooth / BLE / Wi-Fi chosen by SDK
```

The Google layer is transport, not the social/matching policy.