initial commit: Proximity iOS app proposal, full Swift code scaffold, reference backend, testing docs, generated Xcode project

README.md

@@ -0,0 +1,58 @@
+# 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`