# Proximity - A Near-Field Social Connection App

**A social network you can only enter by being physically present. Every connection is a real-world encounter.**

---

## Handoff Notes

### Current State

The project is in **Phase 1 (MVP)** code completion. All core logic is written and structurally validated. The Xcode project is generated and verified. The reference backend server runs and has been syntax-checked.

### What's Done

- **40 Swift source files** across the full architecture (App → Models → Services → ViewModels → Views)
- **Full interaction loop**: presence toggle → simulated encounter → silhouette → wave → mutual reveal → E2E chat
- **Simulator-first testing**: `SimulatedAdapter` injects fake encounters; debug menu in toolbar; no iPhone needed for logic testing
- **Auth**: Apple Sign In + Google OAuth (stubs), Keychain persistence
- **Profile import**: Instagram/X OAuth at reveal time (privacy-gated)
- **Crypto**: rotating anonymous tokens (TokenManager) + X25519/ChaChaPoly E2E (CryptoManager)
- **Backend contract**: full API spec at `docs/backend-api-spec.md`
- **Reference server**: `server/src/index.ts` — Node/TypeScript, session→token mapping, mutual wave relay, E2E key exchange, message relay
- **UI test**: `ProximityUITests/ProximityFlowUITests.swift`
- **Testing guide**: `docs/TESTING_GUIDE.html` — step-by-step walkthrough for M-series Mac
- **Xcode project**: `Proximity.xcodeproj/` — generated, validated (108 objects, 0 missing refs, balanced braces)

### What Needs Real Implementation

| Item | File(s) | Status |
|---|---|---|
| Backend auth token verification | `server/src/index.ts` | Stubbed — accepts any token |
| Persistence (DB, Redis) | server | In-memory only |
| APNs push for background wake | Server + client | Not implemented |
| Real UWB handshake (two iPhones) | `UWBAdapter.swift` | Needs device testing |
| NFC tap-to-connect | `Core NFC` not used yet | Scaffolded |
| Production API credentials | Instagram, X, Google providers | Placeholder IDs |
| ChatView message decryption cache | `ChatViewModel.swift` | Functional but could use persistent cache |

### Architecture Highlights

- **PresenceEngine** talks to protocols (`HandshakeAdapter`, `BroadcastingAdapter`, `RegionAdapter`), not hardware — key to testability
- **RevealFlow** state machine: silhouette → considering → waiting → mutual → revealed → declined
- **RealtimeClient** shared WebSocket with Combine publishers consumed by both RevealFlow and ChatViewModel
- In DEBUG builds, `APIClient` points at `localhost:8080` and `SimulatedAdapter` is injected

### Quick Start

```bash
cd server && npm install && npm run dev     # start reference server
open Proximity.xcodeproj                     # open project in Xcode
# Select iPhone 15 simulator → ⌘R
# Sign in → go present → hammer icon → simulate encounter
```

### Repo

**Remote:** `https://tea.01v0.com/lattice/Nearfield_Friends.git`
**Local:** `/home/gem/workspace/Repos/Nearfield_Friends`