# Architecture Decision Records — Social Proximity

This file tracks key architectural decisions made during the project.
Each decision includes context, what was decided, and the consequences.

---

## ADR-001: Flutter for the mobile app

**Date:** 2026-05-07  
**Status:** Accepted

**Context:**  
The app requires BLE scanning and advertising to detect nearby users. We needed a cross-platform framework (Android + iOS) that provides reliable, low-latency access to the BLE hardware stack.

**Decision:**  
Use Flutter (Dart) with `flutter_blue_plus`.

Flutter compiles to native ARM code and communicates with the platform via direct platform channels — no JavaScript bridge. This gives more stable and predictable BLE behaviour than React Native's bridge-based architecture. `flutter_blue_plus` is the most actively maintained Flutter BLE library with full support for scanning, advertising, and GATT on both Android and iOS.

**Consequences:**  
- Team needs to learn Dart (low barrier — similar to TypeScript)
- BLE integration testing requires physical devices, not emulators
- Build toolchain: Flutter SDK + Android Studio + Xcode

---

## ADR-002: FastAPI for the backend

**Date:** 2026-05-07  
**Status:** Accepted

**Context:**  
Backend needs to handle short-lived sessions, real-time WebSocket nudges, and serve anonymised stats. Should be fast to build and easy to maintain.

**Decision:**  
Use FastAPI (Python) with async support, WebSockets, and Pydantic for request/response validation.

**Consequences:**  
- Native async support fits the WebSocket and Redis use cases
- Pydantic models double as documentation and runtime validation
- Python aligns with DevOpsMCP tooling (complexity, type hints, PEP compliance)

---

## ADR-003: Redis for session storage (not PostgreSQL)

**Date:** 2026-05-07  
**Status:** Accepted

**Context:**  
User sessions are ephemeral by design — they expire after 2 hours and must never be reconstructed. We need fast reads/writes for the match engine.

**Decision:**  
Store all active sessions in Redis with a 2-hour TTL. Use PostgreSQL only for aggregate counters (stats).

**Consequences:**  
- Sessions are automatically deleted by Redis TTL — no manual cleanup needed
- No user-level data ever reaches the database
- Redis must be treated as infrastructure (not optional) — included in docker-compose

---

## ADR-004: No in-app messaging

**Date:** 2026-05-07  
**Status:** Accepted

**Context:**  
We want to nudge users into real, face-to-face conversation — not replace it with another chat interface.

**Decision:**  
The app will never include a messaging feature. The nudge is the product. After a match, the app's job is done.

**Consequences:**  
- Simpler backend (no message storage, no threads)
- Clearer privacy posture
- Risk: lower engagement metrics — accepted by design