clio/clio-android/description.md

# Phone Recorder - Architecture Overview

## Purpose

Android app that records audio continuously, encrypts recordings immediately (never stored unencrypted), and syncs them to a server over LAN or internet.

## 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]
```

## Android App Structure

### Main Files

| File | Purpose |
|------|---------|
| `MainActivity.kt` | UI, settings, sync controls |
| `RecordingService.kt` | Foreground service for recording, encryption on stop |
| `StorageHelper.kt` | File paths, temp vs recordings directories |

### Crypto Package (`crypto/`)

| File | Purpose |
|------|---------|
| `CryptoHelper.kt` | SREC format encryption using lazysodium |
| `KeyManager.kt` | Store/retrieve server public key (SharedPreferences) |

### Sync Package (`sync/`)

| File | Purpose |
|------|---------|
| `SyncSettings.kt` | Sync mode enum, server URLs, LAN subnet prefix |
| `NetworkHelper.kt` | Detect WiFi, LAN (by IP prefix), network availability |
| `SyncTracker.kt` | Track which files synced successfully (SharedPreferences) |
| `SyncWorker.kt` | WorkManager background job for uploads |
| `SyncManager.kt` | Schedule periodic (15min) and immediate syncs |

### API Package (`api/`)

| File | Purpose |
|------|---------|
| `RecordingsApi.kt` | OkHttp client, upload with SHA-256 verification |

## Sync Modes

| Mode | Behavior |
|------|----------|
| Never | No sync, files stay on phone |
| LAN Only | Sync only when IP matches configured subnet (e.g., `10.0.0.`) |
| WiFi Only | Sync on any WiFi network |
| Any Network | Sync on WiFi or mobile data |

## Server Structure (Python/FastAPI)

| File | Purpose |
|------|---------|
| `main.py` | FastAPI endpoints |
| `crypto.py` | PyNaCl decryption, keypair management |
| `config.py` | Paths, ports |

### Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Returns `{"status": "ok"}` |
| `/api/v1/public-key` | GET | Returns Base64 public key |
| `/api/v1/recordings/upload` | POST | Upload encrypted file, returns hash for verification |
| `/api/v1/recordings` | GET | List decrypted recordings |

## Data Flow

1. **Recording starts**: `RecordingService` writes to `temp/recording_TIMESTAMP.ogg`
2. **Recording stops**:
   - `CryptoHelper.encryptFile()` reads temp, writes `recordings/recording_TIMESTAMP.ogg.enc`
   - Temp file deleted
   - `SyncManager.scheduleImmediateSync()` triggered
3. **Sync runs**:
   - `SyncWorker` checks network conditions match `SyncMode`
   - Computes SHA-256 of encrypted file
   - Uploads to server
   - Server decrypts, returns hash
   - If hashes match, marks file as synced
4. **Server storage**: `recordings/YYYY/MM/DD/recording_TIMESTAMP.ogg`

## Key Dependencies

### Android
- `lazysodium-android` - libsodium bindings
- `androidx.work` - Background job scheduling
- `okhttp3` - HTTP client

### Server
- `fastapi` + `uvicorn` - Web framework
- `pynacl` - libsodium bindings
- `aiofiles` - Async file I/O

## Configuration

### Android (in-app settings)
- Sync mode (Never/LAN/WiFi/Any)
- LAN subnet prefix (default: `10.0.0.`)
- Server URLs (LAN and remote)
- Server public key (Base64)

### Server (config.py or env vars)
- `HOST` - Bind address (default: 0.0.0.0)
- `PORT` - Listen port (default: 8000)
- `BASE_DIR` - Base directory for keys and recordings