Remove redundant cursor styling

clio-infra/ARCHITECTURE.md

@@ -0,0 +1,126 @@
+# Clio - Architecture Overview
+
+## Purpose
+
+Multi-device audio recording system with end-to-end encryption. Records continuously on phone and portable devices, encrypts immediately, syncs to central server, transcribes with GPU, and provides a web interface for search and highlights.
+
+## Components
+
+| Repository | Purpose | Deployment Target |
+|------------|---------|-------------------|
+| clio-api | FastAPI server, recordings DB, highlights | Server (10.0.0.45) |
+| clio-android | Android recording app | Phone (manual APK) |
+| clio-ui | React viewer frontend | Server (10.0.0.45) |
+| clio-ai | Whisper transcription, wake word detection | Desktop (10.0.0.130) |
+| clio-infra | Deployment configs, docs, NixOS modules | All |
+
+## Security Model
+
+```
+Phone (has: server public key)     Server (has: private key)
+─────────────────────────────      ────────────────────────
+Record audio → temp.ogg
+Encrypt with public key →
+  recording_*.ogg.enc
+        │
+        └──── HTTP POST ────────→  Receive encrypted file
+                                   Decrypt with private key
+                                   Store as .ogg in recordings/
+```
+
+- **Sealed box encryption**: X25519 key exchange + XSalsa20-Poly1305
+- **Forward secrecy**: Each encryption uses ephemeral keys
+- **Phone never stores unencrypted**: Temp file deleted immediately after encryption
+- **If no public key configured**: Recordings are deleted (security-first design)
+
+## File Format (SREC)
+
+Encrypted files use a chunked format for streaming large files:
+
+```
+[4 bytes: "SREC" magic]
+[1 byte: version (1)]
+[4 bytes: chunk count, big-endian]
+For each chunk (64KB max):
+  [4 bytes: encrypted length, big-endian]
+  [N bytes: sealed box ciphertext]
+```
+
+## Data Flow
+
+```
+1. Recording
+   Phone/Pi → temp.ogg → encrypt → recording_*.ogg.enc
+
+2. Sync
+   Phone/Pi → HTTP POST → Server decrypts → recordings/YYYY/MM/DD/*.ogg
+
+3. Transcription (async, on desktop)
+   Desktop pulls recordings → Whisper → JSON segments → POST to server
+
+4. Viewing
+   Browser → clio-ui → clio-api → recordings + transcripts + highlights
+```
+
+## API Endpoints (clio-api)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check |
+| `/api/v1/public-key` | GET | Server public key (Base64) |
+| `/api/v1/recordings/upload` | POST | Upload encrypted file |
+| `/api/v1/recordings` | GET | List recordings with transcripts |
+| `/api/v1/recordings/{id}` | GET | Recording details |
+| `/api/v1/recordings/{id}/audio` | GET | Stream audio file |
+| `/api/v1/import/transcription` | POST | Import transcription JSON |
+| `/api/v1/highlights` | GET/POST | Manage highlights |
+| `/api/v1/sources` | GET | List recording sources |
+
+## Database Schema
+
+**recordings**: id, source_name, audio_path, duration, language, recorded_at, transcribed_at
+**segments**: id, recording_id, start_time, end_time, text, confidence
+**highlights**: id, recording_id, start_seconds, end_seconds, tag, note, created_at
+
+## Sync Modes (Android)
+
+| Mode | Behavior |
+|------|----------|
+| Never | No sync, files stay on phone |
+| LAN Only | Sync only when IP matches subnet (e.g., `10.0.0.`) |
+| WiFi Only | Sync on any WiFi network |
+| Any Network | Sync on WiFi or mobile data |
+
+## Hosts & Paths
+
+### Server (10.0.0.45)
+- Code: `/work/hosting/recordings`
+- Audio: `/media/external/Hosting/Recordings`
+- Database: `/work/hosting/recordings/data/recordings.db`
+- Frontend: `/var/www/recordings-viewer`
+- Domain: `recordings.hallocks.xyz`
+
+### Desktop (10.0.0.130)
+- Transcription scripts
+- Real-time wake word detection
+- GPU: RTX 3090
+
+## Dependencies
+
+### clio-api (Python)
+- fastapi, uvicorn
+- pynacl (libsodium)
+- aiofiles
+- sqlite3
+
+### clio-android (Kotlin)
+- lazysodium-android
+- androidx.work
+- okhttp3
+
+### clio-ai (Python)
+- faster-whisper
+- torch, torchaudio
+- sounddevice
+- webrtcvad
+- scikit-learn