Nearfield_Friends/README.md

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

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