Dokumentacja Techniczna: Danish AI Tutor
Projekt opiera się na modularnym stacku OpenAI + infrastrukturze serverless, aby utrzymać niską latencję i bardzo niski koszt jednostkowy nauki języka duńskiego.
Latencja
Zwykle 2-4 sekundy end-to-end.
Budżet
Około 4-4.5h rozmowy za 20 PLN.
Bezpieczeństwo
RLS + izolacja historii na użytkownika.
Modułowość
STT + LLM + TTS z wymienialnymi komponentami.
1. Silniki Sztucznej Inteligencji (AI Stack)
Podejście "best-of-breed": każdy komponent robi jedną rzecz bardzo dobrze. Kliknij moduł, aby zobaczyć rolę, uzasadnienie i koszty.
Szczegółowy podział latencji (Pipeline 3 AI)
Aby uzyskać naturalny efekt rozmowy, optymalizujemy każdy krok procesu. Poniżej rozkład czasu odpowiedzi przy wykorzystaniu Groq.
Cel: utrzymać pełny czas end-to-end na poziomie komfortowym dla konwersacji głosowej.
| Etap procesu | Silnik AI | Średni czas (latencja) | Rola w systemie |
|---|---|---|---|
| STT Słuchanie | Groq (Whisper v3) | ~0.3 - 0.6 sekundy | Błyskawiczna zamiana mowy na tekst. |
| LLM Mózg | GPT-5 Mini | ~0.4 - 0.8 sekundy | Analiza błędu i wygenerowanie odpowiedzi JSON. |
| TTS Mówienie | OpenAI TTS-1 | ~0.8 - 1.5 sekundy | Synteza głosu (streaming zaczyna się szybciej). |
| NET Sieć | Infrastruktura | ~0.2 - 0.4 sekundy | Przesył danych między usługami i użytkownikiem. |
| SUMA (End-to-End) | Pipeline 3 AI | ~1.7 - 3.3 sekundy | Całkowity czas oczekiwania użytkownika. |
2. Język i Środowisko Aplikacji
Framework: Next.js (React)
Full-stack w jednym repo. API Routes ukrywają klucze AI po stronie serwera.
Stan i sesja
React Hooks (`useState`, `useEffect`) + autoryzacja sesji użytkownika.
Integracja backendu
Bezpośredni orkiestrator w kodzie backendu, bez osobnego MCP serwera.
3. Analiza Kosztów i Ekonomia
Zasięg nauki za 20 PLN (ok. $5.00)
W tym STT Whisper Large v3 (Groq) + GPT-5 Mini + TTS-1.
Cennik GPT-5 Mini (1M tokenów)
| Typ | Cena |
|---|---|
| Input | $0.25 |
| Cached Input | $0.03 |
| Output | $2.00 |
Context Caching obniża koszt powtarzalnych instrukcji o ok. 80-90%.
Podział kosztu 1h rozmowy
Wycena audio API (Whisper + TTS-1)
| Usługa | Cena | Uwagi |
|---|---|---|
| Whisper Large v3 Turbo na Groq (STT) | $0.04 / godz. transkrypcji* | Wariant Turbo, do 228x realtime oraz lepsza precyzja dla duńskiej wymowy. |
| OpenAI TTS-1 (TTS) | $15.00 / 1M znaków | Model zoptymalizowany pod niską latencję dialogu. |
Średni czas odpowiedzi (latencja)
Pełny cykl (upload audio, transkrypcja, generacja odpowiedzi, synteza mowy) trwa zwykle 2-4 sekundy. Streaming sprawia, że tekst poprawki pojawia się niemal natychmiast, więc odczuwalne opóźnienie jest mniejsze.
4. Infrastruktura i Hosting
Dobór pod Free Tier: uruchomienie i testy bez stałych kosztów.
| Usługa | Kluczowe limity | Szacowana wydajność |
|---|---|---|
Vercel Hobby
|
100 GB transferu/mies., 6000 minut buildów | ok. 2 000-5 000 MAU |
Neon PostgreSQL Free
|
512 MB storage, współdzielone CPU (0.25 vCPU) | ok. 10 000-15 000 rozmów tekstowych |
Cloudflare R2 Free
|
10 GB, 1 mln write, 10 mln read/mies. | ok. 50 000-100 000 interakcji głosowych |
5. Bezpieczeństwo i Logika Biznesowa
Autoryzacja i prywatność
- Neon Auth (Clerk) do 10 000 MAU w planie darmowym.
- Gotowe komponenty logowania i natywna integracja z bazą Neon.
- RLS (Row Level Security): użytkownik widzi tylko własną historię.
- W bazie Neon przechowujemy tekst i klucze, a audio wyłącznie w Cloudflare R2.
Flow i kontrola kosztów
- AI zwraca ustrukturyzowany JSON: transkrypcja, poprawka, wskazówka fonetyczna, odpowiedź.
- Liczniki minut i tokenów per użytkownik zapisane w Neon.
{
"transcript": "...",
"correction": "...",
"phonetic_tip": "...",
"assistant_reply": "...",
"meme_id": "optional"
}
6. Integracja Systemu Płatności (SaaS)
Dlaczego Stripe
Światowy standard SaaS z gotowymi komponentami: Stripe Checkout i portal klienta do obsługi subskrypcji.
Brak opłat stałych i abonamentowych. Prowizja zwykle ok. 1.1%-2.9% + 1.20 PLN za udaną transakcję.
Wymagania techniczne
- Konto firmowe Stripe + konfiguracja kluczy Secret/Publishable.
- Webhooki do automatycznej aktualizacji limitów w Neon po płatności.
- Certyfikat SSL na domenie produkcyjnej.
7. Integracja Bazy Memów (Gamifikacja)
1. Magazyn
Pliki graficzne memów są składowane w Cloudflare R2.
2. Metadata
System prompt zawiera listę ID i opisy kontekstów użycia (np. `proud_viking`).
3. Wybór AI
Model decyduje, czy dodać `meme_id` do odpowiedzi JSON.
4. Display
Frontend renderuje obrazek automatycznie w oknie czatu.
8. Integracja komunikacji: Brevo (E-mail & SMS)
Funkcjonalności w projekcie
- Automatyczne e-maile transakcyjne: potwierdzenia konta, odzyskiwanie hasła, raporty postępów.
- Powiadomienia SMS: przypomnienia o sesjach i alerty o niskim stanie pakietu minut.
Free Tier Brevo
- E-mail: 300 wiadomości dziennie.
- Kontakty: nielimitowana baza kontaktów.
- Szablony: edytor Drag & Drop i responsywna biblioteka templatek.
- API/SMTP: pełny dostęp do integracji z backendem na Vercel.
SMS: koszty i zasady
- Model prepaid (pay-as-you-go), bez abonamentu.
- Pakiety kredytów nie wygasają.
- Aktualny przykład dla Polski: pakiet 100 SMS kosztuje €1.69, co daje około €0.0169 za SMS.
- W przeliczeniu orientacyjnym to ok. 0,07-0,08 PLN/SMS netto (zależnie od kursu EUR).
- Zasięg globalny: wysyłka do ponad 150 krajów.
Obsługa skrzynki i domeny
Do obsługi skrzynki pocztowej i codziennej komunikacji można używać klienta Mozilla Thunderbird.
Operatorem poczty może być OVH, gdzie można również kupić domenę i utrzymywać skrzynki e-mail.
9. Elementy do ustalenia (Pre-production)
Prompt AI i ton nauczyciela
Surowość korekt, język wskazówek i osobowość asystenta.
Hosting docelowy
Pozostanie na Vercel Hobby czy migracja na infrastrukturę klienta.
Domena
Czy domena .pl/.dk już istnieje, czy trzeba ją zarejestrować.
Źródła memów
Własna baza grafik lub przygotowanie zestawu startowego.
Stripe - wymagania techniczne
Konto firmowe, klucze API, webhooki, SSL oraz aktualizacja limitów po płatności.
Koszty Stripe
Brak stałych opłat; zwykle ok. 1.1%-2.9% + 1.20 PLN za transakcję.
Analityka aplikacji
Gdzie stawiamy analitykę aplikacji i czy w ogóle jest potrzebna na etapie MVP?
Podsumowanie wyboru: ten stack umożliwia realizację projektu w budżecie 8 000 PLN przy zachowaniu skalowalności, bezpieczeństwa i niskich kosztów utrzymania.
10. Prototyp UI aplikacji
Poniżej osadzony jest interaktywny prototyp interfejsu użytkownika na bazie pliku projektu.
Jeśli podgląd się nie ładuje, otwórz plik `Prototyp UI aplikacji.html` bezpośrednio.