# 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