Потоци на данни

Тази страница описва четирите основни потока на данни в Dictaro: диктовка, автентикация, billing и usage/quota.

1. Поток на диктовка

Основният потребителски поток -- от натискане на hotkey до появяване на текст на екрана.

Детайли

1. Hotkey -- глобален keyboard hook чрез windows-sys Win32 API. Поддържа конфигурируеми комбинации.
2. Аудио запис -- WASAPI (Windows) или CoreAudio (macOS), 16 kHz sample rate, mono канал, float32 формат.
3. WAV кодиране -- библиотеката hound създава WAV буфер в паметта (без файл на диска).
4. WebSocket -- tokio-tungstenite с native-tls. Първо се изпраща JSON metadata, после binary WAV.
5. API key -- вграден в клиента, изпраща се в metadata JSON за автентикация към ASR сървъра.
6. ASR модел -- NVIDIA NeMo (nemo_toolkit[asr]), работи на CUDA GPU.
7. Post-processing -- опционален за Pro потребители. vLLM сървира Gemma 3 12B IT с bfloat16, gpu-memory-utilization=0.25.
8. Hallucination filter -- клиентски филтър за премахване на повтарящи се фрази и ASR артефакти.
9. Text injection -- arboard библиотека записва текста в clipboard, след което симулира paste.

2. Поток на автентикация (OAuth)

Browser-redirect OAuth flow за свързване на десктоп клиента с licensing сървъра.

Ключови моменти

• State параметър: SHA-256 hash на timestamp + PID, предпазва от CSRF атаки.
• Session cookies: gorilla/securecookie с HttpOnly, Secure флагове.
• Timeout: 60 секунди за login flow (race: callback vs timeout vs cancel).
• Device ID: SHA-256 на machine-specific идентификатори, ограничава брой акаунти на устройство.
• JWT claims: {sub: email, user_id, plan, device_id, provider, iat, exp}.
• RS256 ключове: PEM формат, публичният ключ е вграден в клиента.
• Token refresh: POST /auth/refresh на всеки 1 час; при неуспех -- backoff от 5 минути.
• Leeway: Сървърът допуска 5 секунди clock skew; клиентът -- 60 секунди.

3. Поток на billing (Stripe)

Процесът на надграждане от Free към Pro план чрез Stripe Checkout.

Webhook събития

Stripe Event	Действие
checkout.session.completed	Записва stripe_customer_id, subscription_id, задава plan='pro'
customer.subscription.updated	Синхронизира статус на абонамента
customer.subscription.deleted	Връща потребителя на plan='free'
invoice.payment_failed	Логва за наблюдение

Checkout timeout

Checkout flow-ът има 120-секунден timeout (двойно спрямо login-а), за да даде време за попълване на платежни данни в Stripe.

Stripe Customer Portal

Pro потребителите могат да управляват абонамента си чрез Stripe Customer Portal:

4. Поток на usage и quota

Записване на употреба и управление на rolling quota за безплатни потребители.

Rolling quota алгоритъм

Конфигурация на квоти

Параметър	Стойност	Описание
QUOTA_MINUTES	10	Квота за безплатни потребители (600 секунди)
COOLDOWN_HOURS	5	Cooldown период след надвишаване на квотата
TRIAL_DAYS	7	Безплатен пробен период без ограничения
TYPING_RATIO	4.0	Множител за "спестено време при писане"

Статуси на квотата

Статус	Описание	Ограничение
unlimited	Pro потребител	Без ограничения
trial	В рамките на 7-дневния пробен период	Без ограничения
active	Free потребител с налична квота	Диктовката е разрешена
cooldown	Квотата е надвишена	Диктовката е блокирана до cooldown_until

Публична статистика

Endpoint GET /stats/public връща агрегирани данни за маркетинг сайта:

{
  "total_users": 150,
  "total_dictation_hours": 42.5,
  "total_typing_saved_hours": 170.0,
  "total_dictation_count": 12500
}

Данните идват от таблицата stats_aggregate, която се актуализира при всеки RecordUsage call чрез UPSERT.