Remove redundant cursor styling
Some checks failed
Deploy API / deploy (push) Failing after 1s
Deploy UI / deploy (push) Successful in 1s

This commit is contained in:
Your Name 2026-05-19 19:48:13 -04:00
parent 080b4bdaf1
commit b24dd72ae0
93 changed files with 9058 additions and 1 deletions

126
clio-infra/ARCHITECTURE.md Normal file
View file

@ -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

153
clio-infra/TODO.md Normal file
View file

@ -0,0 +1,153 @@
# Clio - Consolidated TODO
## Architecture Overview
```
┌─────────────────────────────────────────────────────────────────────────┐
│ TARGET ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────────────────────────────────────────┐ │
│ │ Phone │───────▶│ Server (10.0.0.45) │ │
│ │ (Android)│ push │ - Storage hub (recordings) │ │
│ └──────────┘ │ - clio-api (FastAPI) │ │
│ │ - clio-ui (React frontend) │ │
│ ┌──────────┐ │ - Database (highlights, transcripts) │ │
│ │ Pi │───────▶│ - Forgejo (code.hallocks.xyz) │ │
│ │(portable)│ push └──────────────────────────────────────────────┘ │
│ └──────────┘ │ │
│ │ pulls recordings │
│ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Desktop (10.0.0.130) │ │
│ │ - GPU: RTX 3090 │ │
│ │ - clio-ai/transcription (Whisper) │ │
│ │ - clio-ai/real_time (wake word detection) │ │
│ │ - Off at night (non-critical) │ │
│ └──────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
## Immediate Tasks
### Infrastructure Setup
- [x] Import Pi recorder code (systemd setup) → clio-pi/
- [ ] Migrate ~100s GB of recordings from Pi to server storage
- [ ] Pi: Add sync script to push recordings to server
- [ ] Pi: Auto-detect audio device (currently hardcoded to hw:1)
- [ ] Set up Forgejo repos for all clio-* projects
- [ ] Configure Forgejo Actions for server deployments (10.0.0.45)
- [ ] Create backup strategy for viewer, highlights, and database
### Deployment Pipeline
- [ ] clio-api: Forgejo Actions → deploy to 10.0.0.45
- [ ] clio-ui: Forgejo Actions → deploy to 10.0.0.45:/var/www/recordings-viewer
- [ ] clio-ai: Manual deploy to desktop (10.0.0.130) - not via Actions
---
## Feature Backlog
### High Priority
- [ ] QR code for key import (avoid email/typing)
- [ ] Server URL configuration in app UI
- [ ] Manual sync trigger button
- [ ] View sync history/status in app
- [ ] Display last successful sync time on phone
- [ ] Server status page/dashboard:
- When phone/pi last synced
- Total recordings count
- Recent uploads
- Disk space usage
### Wake Word / Voice Recognition (clio-ai)
- [ ] Manage wake words in UI (currently hardcoded)
- [ ] Centralize voice recognition training data
- [ ] Real-time detection improvements (currently sucks even on desktop)
- [ ] Future: Real-time detection on phone/pi (low priority)
### Audio Analysis & Intelligence
- [ ] Speech detection bar in recording detail view
- [ ] Sleeping/silence detection for overnight recordings
- [ ] Auto voice recognition / speaker identification
- [ ] Auto highlight generation (audio-based, not text search)
### Viewer UX
- [ ] Background audio playback (mini player across views)
- [ ] Highlight duration (currently point-only, add end time)
- [ ] Auto-scroll timeline to recordings
### Medium Priority
- [ ] Configurable recording quality (bitrate, sample rate)
- [ ] Configurable segment duration (currently 2 hours)
- [ ] Delete synced files automatically (with retention)
- [ ] Server authentication for upload endpoint
- [ ] Server HTTPS with Let's Encrypt (partially done via Caddy)
### Low Priority / Nice to Have
- [ ] Multiple server destinations
- [ ] Compression before encryption
- [ ] Resume interrupted uploads
- [ ] Docker container for server
---
## Questions to Resolve
### Key Rotation
- What happens when server keypair changes?
- Options:
1. Keep old private key archived
2. Sync all files before rotating
3. Store key version in encrypted file header
### Manual Decryption
- Document steps to decrypt files copied via USB
- CLI tool needed
### Desktop Worker Architecture
- How does desktop pull recordings from server?
- How does it push transcriptions back?
- Queue system needed?
---
## Known Limitations
1. **No streaming encryption**: Entire temp file must complete before encryption
2. **No partial sync**: If upload fails, whole file retries
3. **Single server**: Can only sync to one destination at a time
4. **No authentication**: Relies on encryption for confidentiality
5. **Desktop off at night**: Real-time detection unavailable
---
## Repository Structure
```
/work/projects/clio/
├── clio-api/ # FastAPI server (recordings, highlights, transcripts)
├── clio-android/ # Android recording app
├── clio-ui/ # React frontend (viewer)
├── clio-ai/ # ML/AI components
│ ├── real_time/ # Wake word detection, voice classifier
│ └── transcription/ # Whisper transcription scripts
├── clio-pi/ # Raspberry Pi recorder
│ ├── bin/ # Recording scripts
│ ├── systemd/ # Service units
│ └── setup.sh # Pi setup script
└── clio-infra/ # Deployment, configs, docs
├── nixos/ # NixOS modules
├── scripts/ # Deploy scripts
└── TODO.md # This file
```
## Hosts
| Host | IP | Role |
|------|-----|------|
| Server | 10.0.0.45 | Storage, API, UI, Forgejo |
| Desktop | 10.0.0.130 | GPU transcription, real-time detection |
| Phone | (mobile) | Recording source |
| Pi | (TBD) | Portable recording source |

View file

@ -0,0 +1,46 @@
# Caddyfile snippet for phone-recorder
# Add this to your global /etc/caddy/Caddyfile
#
# Caddy will automatically obtain and renew HTTPS certificates
recordings.hallocks.xyz {
# Proxy everything to FastAPI
reverse_proxy localhost:8000
# Security headers
header {
X-Content-Type-Options nosniff
X-Frame-Options SAMEORIGIN
Referrer-Policy strict-origin-when-cross-origin
-Server
}
# Logging for fail2ban
log {
output file /var/log/caddy/recordings.log {
roll_size 10mb
roll_keep 5
}
format json
}
}
# ============================================================
# Other services (for reference when setting them back up):
# ============================================================
# todo.hallocks.xyz {
# reverse_proxy localhost:3456 # Vikunja
# log {
# output file /var/log/caddy/todo.log
# format json
# }
# }
# passwords.hallocks.xyz {
# reverse_proxy localhost:8080 # Vaultwarden
# log {
# output file /var/log/caddy/passwords.log
# format json
# }
# }

View file

@ -0,0 +1,182 @@
# NixOS module for phone-recorder server
# Add to your configuration.nix imports or use as a standalone module
#
# Usage in configuration.nix:
# imports = [ ./phone-recorder.nix ];
# services.phone-recorder.enable = true;
{ config, lib, pkgs, ... }:
let
cfg = config.services.phone-recorder;
in
{
options.services.phone-recorder = {
enable = lib.mkEnableOption "Phone Recorder server";
port = lib.mkOption {
type = lib.types.port;
default = 8000;
description = "Port for the API server";
};
dataDir = lib.mkOption {
type = lib.types.path;
default = "/var/lib/phone-recorder";
description = "Directory for recordings and database";
};
user = lib.mkOption {
type = lib.types.str;
default = "phone-recorder";
description = "User to run the service as";
};
domain = lib.mkOption {
type = lib.types.str;
default = "recordings.hallocks.xyz";
description = "Domain for HTTPS access";
};
enableCaddy = lib.mkOption {
type = lib.types.bool;
default = true;
description = "Enable Caddy reverse proxy with automatic HTTPS";
};
enableFail2ban = lib.mkOption {
type = lib.types.bool;
default = true;
description = "Enable fail2ban protection";
};
sourceDir = lib.mkOption {
type = lib.types.path;
default = /home/thallock/phone-recorder;
description = "Path to the server source code";
};
};
config = lib.mkIf cfg.enable {
# Create user and group
users.users.${cfg.user} = {
isSystemUser = true;
group = cfg.user;
home = cfg.dataDir;
createHome = true;
};
users.groups.${cfg.user} = {};
# Systemd service
systemd.services.phone-recorder = {
description = "Phone Recorder API Server";
after = [ "network.target" ];
wantedBy = [ "multi-user.target" ];
environment = {
HOST = "127.0.0.1"; # Only listen locally, Caddy handles external
PORT = toString cfg.port;
BASE_DIR = toString cfg.sourceDir;
RECORDINGS_DIR = "${cfg.dataDir}/recordings";
DATABASE_PATH = "${cfg.dataDir}/recordings.db";
};
serviceConfig = {
Type = "simple";
User = cfg.user;
Group = cfg.user;
WorkingDirectory = cfg.sourceDir;
ExecStart = "${pkgs.uv}/bin/uv run python main.py";
Restart = "always";
RestartSec = 5;
# Hardening
NoNewPrivileges = true;
ProtectSystem = "strict";
ProtectHome = "read-only";
PrivateTmp = true;
ReadWritePaths = [ cfg.dataDir ];
};
preStart = ''
mkdir -p ${cfg.dataDir}/recordings
mkdir -p ${cfg.dataDir}/keys
'';
};
# Caddy reverse proxy
services.caddy = lib.mkIf cfg.enableCaddy {
enable = true;
virtualHosts = {
"${cfg.domain}" = {
extraConfig = ''
# API endpoints
handle /api/* {
reverse_proxy localhost:${toString cfg.port}
}
handle /health {
reverse_proxy localhost:${toString cfg.port}
}
# Static frontend (if you have one)
handle {
root * /var/www/recordings-viewer
file_server
try_files {path} /index.html
}
# Security headers
header {
X-Content-Type-Options nosniff
X-Frame-Options DENY
Referrer-Policy strict-origin-when-cross-origin
}
# Rate limiting for uploads
@upload path /api/v1/recordings/upload
handle @upload {
rate_limit {remote.ip} 10r/m
reverse_proxy localhost:${toString cfg.port}
}
# Logging
log {
output file /var/log/caddy/recordings.log
format json
}
'';
};
};
};
# Open firewall
networking.firewall.allowedTCPPorts = [ 80 443 ]
++ lib.optional (!cfg.enableCaddy) cfg.port;
# Fail2ban
services.fail2ban = lib.mkIf cfg.enableFail2ban {
enable = true;
maxretry = 5;
bantime = "1h";
jails = {
caddy-auth = lib.mkIf cfg.enableCaddy ''
enabled = true
filter = caddy-auth
logpath = /var/log/caddy/recordings.log
maxretry = 5
bantime = 3600
'';
};
};
# Fail2ban filter for Caddy
environment.etc."fail2ban/filter.d/caddy-auth.conf" = lib.mkIf (cfg.enableFail2ban && cfg.enableCaddy) {
text = ''
[Definition]
failregex = ^.*"remote_ip":"<HOST>".*"status":40[13].*$
ignoreregex =
'';
};
};
}

View file

@ -0,0 +1,33 @@
# Systemd service file for phone-recorder
# Copy to /etc/systemd/system/phone-recorder.service
# Then: systemctl daemon-reload && systemctl enable --now phone-recorder
[Unit]
Description=Phone Recorder API Server
After=network.target local-fs.target
Wants=network-online.target
[Service]
Type=simple
User=thallock
Group=thallock
WorkingDirectory=/work/hosting/recordings
# Paths
Environment="HOST=0.0.0.0"
Environment="PORT=8000"
Environment="BASE_DIR=/work/hosting/recordings"
Environment="RECORDINGS_DIR=/media/external/Hosting/Recordings"
Environment="DATABASE_PATH=/work/hosting/recordings/data/recordings.db"
Environment="KEYS_DIR=/work/hosting/recordings/data/keys"
ExecStart=/home/thallock/.local/bin/uv run python main.py
Restart=always
RestartSec=5
# Hardening
NoNewPrivileges=true
PrivateTmp=true
[Install]
WantedBy=multi-user.target

View file

@ -0,0 +1,74 @@
#!/usr/bin/env bash
set -euo pipefail
# Deployment script for phone-recorder server
# Target: thallock@10.0.0.45 (SSH port 2252)
#
# Paths on server:
# Code: /work/hosting/recordings
# Data (db): /work/hosting/recordings/data
# Audio: /media/external/Hosting/Recordings
SERVER_HOST="10.0.0.45"
SERVER_USER="thallock"
SERVER_PORT="2252"
CODE_DIR="/work/hosting/recordings"
DATA_DIR="/work/hosting/recordings/data"
AUDIO_DIR="/media/external/Hosting/Recordings"
SSH_OPTS="-p ${SERVER_PORT}"
SSH_CMD="ssh ${SSH_OPTS} ${SERVER_USER}@${SERVER_HOST}"
RSYNC_SSH="ssh -p ${SERVER_PORT}"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
echo "=== Deploying phone-recorder server to ${SERVER_USER}@${SERVER_HOST} ==="
# Sync server code (excluding local data)
echo "Syncing server code..."
rsync -avz --delete \
--exclude '.venv' \
--exclude '__pycache__' \
--exclude '*.pyc' \
--exclude 'recordings/' \
--exclude 'recordings.db' \
--exclude 'keys/' \
--exclude 'data/' \
--exclude '.git' \
--exclude 'nixos/' \
-e "${RSYNC_SSH}" \
"${SCRIPT_DIR}/" \
"${SERVER_USER}@${SERVER_HOST}:${CODE_DIR}/"
echo "Setting up on remote server..."
${SSH_CMD} bash << REMOTE_SCRIPT
set -euo pipefail
# Create directories
mkdir -p ${DATA_DIR}/keys
mkdir -p ${AUDIO_DIR}
cd ${CODE_DIR}
# Sync dependencies
echo "Syncing Python dependencies..."
uv sync
echo ""
echo "=== Server code deployed ==="
echo "Code: ${CODE_DIR}"
echo "Data: ${DATA_DIR}"
echo "Audio: ${AUDIO_DIR}"
echo ""
echo "To install/update systemd service:"
echo " sudo cp ${CODE_DIR}/nixos/phone-recorder.service /etc/systemd/system/"
echo " sudo systemctl daemon-reload"
echo " sudo systemctl enable --now phone-recorder"
echo ""
echo "To check status:"
echo " sudo systemctl status phone-recorder"
echo " curl http://localhost:8000/health"
REMOTE_SCRIPT
echo ""
echo "=== Deployment complete ==="

View file

@ -0,0 +1,15 @@
#!/run/current-system/sw/bin/fish
rsync -avz --delete \
--exclude '.venv' --exclude '__pycache__' --exclude '*.pyc' \
--exclude 'recordings/' --exclude 'recordings.db' --exclude 'keys/' \
--exclude 'data/' --exclude '.git' \
-e 'ssh -p 2252' \
/work/projects/phone_recorder/claude/server/ \
thallock@10.0.0.45:/work/hosting/recordings/
# Deploy React frontend
rsync -avz --delete \
-e 'ssh -p 2252' \
/work/projects/view_recordings/designer_export/ \
thallock@10.0.0.45:/work/hosting/recordings-viewer/

78
clio-infra/scripts/deploy.sh Executable file
View file

@ -0,0 +1,78 @@
#!/usr/bin/env bash
set -euo pipefail
# Clio deployment script
# Deploys clio-api and clio-ui to server (10.0.0.45)
#
# Usage: ./deploy.sh [api|ui|all]
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
CLIO_ROOT="$(dirname "$(dirname "$SCRIPT_DIR")")"
SERVER_HOST="10.0.0.45"
SERVER_USER="thallock"
SERVER_PORT="2252"
# Server paths
API_CODE_DIR="/work/hosting/recordings"
UI_DIR="/work/hosting/recordings-viewer"
SSH_OPTS="-p ${SERVER_PORT}"
SSH_CMD="ssh ${SSH_OPTS} ${SERVER_USER}@${SERVER_HOST}"
RSYNC_SSH="ssh -p ${SERVER_PORT}"
deploy_api() {
echo "=== Deploying clio-api ==="
rsync -avz --delete \
--exclude '.venv' \
--exclude '__pycache__' \
--exclude '*.pyc' \
--exclude 'recordings/' \
--exclude 'recordings.db' \
--exclude 'keys/' \
--exclude 'data/' \
--exclude '.git' \
--exclude 'nixos/' \
-e "${RSYNC_SSH}" \
"${CLIO_ROOT}/clio-api/" \
"${SERVER_USER}@${SERVER_HOST}:${API_CODE_DIR}/"
echo "Running uv sync on server..."
${SSH_CMD} "cd ${API_CODE_DIR} && uv sync"
echo "clio-api deployed."
}
deploy_ui() {
echo "=== Deploying clio-ui ==="
rsync -avz --delete \
-e "${RSYNC_SSH}" \
"${CLIO_ROOT}/clio-ui/" \
"${SERVER_USER}@${SERVER_HOST}:${UI_DIR}/"
echo "clio-ui deployed."
}
case "${1:-all}" in
api)
deploy_api
;;
ui)
deploy_ui
;;
all)
deploy_api
deploy_ui
;;
*)
echo "Usage: $0 [api|ui|all]"
exit 1
;;
esac
echo ""
echo "=== Deployment complete ==="
echo ""
echo "To restart the API service:"
echo " ssh -p ${SERVER_PORT} ${SERVER_USER}@${SERVER_HOST} 'sudo systemctl restart phone-recorder'"
echo ""
echo "To check status:"
echo " curl https://recordings.hallocks.xyz/health"