# NoNo — TECH_STACK.md

> **Master-katalog technologii, platform, API, modeli AI, kanałów, baz danych i narzędzi** projektu NoNo — osobistego copilota „Life OS".
>
> Ten plik to pełny, kompletny rejestr wszystkiego, o czym rozmawialiśmy. Skrócony, kuratorowany stack pod MVP (z ładnym UI) żyje w [`docs/tech-stack.html`](docs/tech-stack.html). Gdy oba się rozjadą — **źródłem prawdy dla decyzji MVP jest `tech-stack.html`**, a ten plik jest szerszą mapą kierunku.

**Decyzje bazowe (MVP):** Android-only · chmura GPT/Gemini/Claude teraz, Bielik później · single-user (nie multi-tenant) · hosting Hetzner (UE/RODO).

---

## Legenda statusów

| Tag | Znaczenie |
|-----|-----------|
| 🟢 **MVP** | Wchodzi w pierwszej wersji („teraz") |
| 🟡 **V1** | Zaraz po MVP |
| 🟣 **Opcja** | Rozważane / opcjonalne |
| 🔵 **Wizja** | Długoterminowy kierunek produktu — kierunek, nie zobowiązanie |

> Statusy dla pozycji „Wizja" (rozbudowany roster agentów, features produktowe, część integracji) są orientacyjne — to mapa, nie backlog z datami.

---

## Stack w skrócie

| Warstwa | Technologie | Status |
|---------|-------------|--------|
| **Klient** | Flutter (Android) · Panel Web (Laravel) · WhatsApp · Signal | 🟢 / 🟡 |
| **Backend** | Laravel 12 (PHP) · REST API · Sanctum · Queues/Horizon · Scheduler · Events · WebSocket | 🟢 |
| **AI — modele** | GPT · Gemini · Claude · Whisper (STT) · Vision · Embeddings · Bielik (później) | 🟢 / 🟡 |
| **AI — architektura** | Orchestrator · RAG · Memory Engine · Knowledge Graph · Prediction/Confidence Engine · Agent System | 🟢 / 🔵 |
| **Dane** | PostgreSQL · pgvector · Redis · Object Storage | 🟢 |
| **Integracje** | Health Connect · WhatsApp Cloud API · FCM (push) | 🟢 / 🟡 |
| **Integracja agentów** | MCP (Model Context Protocol) | 🔵 |
| **Infra** | Hetzner · Ubuntu · Nginx · Docker · SSL · backupy | 🟢 |

---

## 1. Frontend

| Technologia | Rola | Status |
|-------------|------|--------|
| **Flutter (Dart)** | Główna aplikacja mobilna — **tylko Android** w MVP, iOS później | 🟢 |
| **Flutter Web** | Ewentualny web-klient z tego samego kodu | 🟣 |
| **HTML / CSS / JavaScript** | Makiety ekranów, panel WWW, dokumentacja | 🟢 |
| Material Design 3 | System UI natywny dla Androida | 🟢 |

---

## 2. Backend

| Technologia | Rola | Status |
|-------------|------|--------|
| **Laravel 12 (PHP 8.3+)** | Rdzeń backendu — logika biznesowa, rejestr narzędzi AI | 🟢 |
| REST API | Wejście dla mobile, web, WhatsApp | 🟢 |
| Auth (Sanctum) | Autoryzacja i tokeny (mobile + web) | 🟢 |
| Queue + Horizon | Zadania async: transkrypcja, embeddingi, raporty, analizy AI (na Redisie) | 🟢 |
| Scheduler (Cron) | Check-in, Voice Journal 21:00, raport tygodniowy, przypomnienia | 🟢 |
| Events | Zdarzenia domenowe / event-driven flow | 🟢 |
| WebSocket (Laravel Reverb) | Realtime — live czat, aktualizacje dashboardu | 🟣 |
| Webhooks | Wejście z WhatsApp Cloud API i innych usług | 🟢 |

---

## 3. Bazy danych i pamięć

| Technologia | Rola | Status |
|-------------|------|--------|
| **PostgreSQL** | Główna baza — dane strukturalne wszystkich modułów | 🟢 |
| **pgvector** | Baza wektorowa: pamięć AI, RAG, wyszukiwanie podobnych wspomnień | 🟢 |
| **Redis** | Cache, kolejki, sesje, rate-limiting | 🟢 |
| Object Storage | Pliki: PDF badań, audio głosówek, zdjęcia (Hetzner Storage Box / S3 / MinIO) | 🟢 |

**Model danych:** SQL (relacyjne) · Vector DB (embeddingi) · Knowledge Graph · Memory Timeline · Life Timeline.

---

## 4. Warstwa AI — modele

| Model | Rola | Status |
|-------|------|--------|
| **GPT (OpenAI)** | Reasoning, planning, audyt, tool-calling | 🟢 |
| **Gemini (Google)** | Alternatywa dla GPT — długi kontekst, Vision, research | 🟢 |
| **Claude (Anthropic)** | Rozumowanie / audyt wyników, zadania wymagające precyzji | 🟢 |
| **Whisper** | Speech-to-Text (głos → tekst); chmura teraz, whisper.cpp lokalnie później | 🟢 |
| **Vision Model** | Analiza zdjęć, twarzy, dokumentów, sylwetki | 🟢 |
| **Bielik** | Docelowy główny Copilot PL, self-hosted — prywatność i koszt | 🟡 |

### Embedding models (rozważane)

| Model | Notatka |
|-------|---------|
| **BGE-M3** | Multilingual, wielozadaniowy |
| **Qwen Embedding** | Kandydat |
| **E5 Multilingual** | Kandydat |

> 🔒 **Zasada nadrzędna:** wszystkie klucze API żyją wyłącznie po stronie serwera (Laravel). Aplikacja i kanały nigdy ich nie widzą — rozmawiają tylko z naszym API.

---

## 5. Warstwa AI — architektura

| Komponent | Rola | Status |
|-----------|------|--------|
| **Orchestrator** | Routing modeli (GPT/Gemini/Claude → Bielik), rejestr narzędzi, router prywatności, kontrola kosztów | 🟢 |
| **RAG** | Retrieval Augmented Generation — kontekst z pamięci wektorowej | 🟢 |
| **Memory Engine** | Zapis, curation i przywoływanie wspomnień | 🟢 |
| **Knowledge Graph** | Graf wiedzy — relacje między encjami życia | 🔵 |
| **Prediction Engine** | Predykcje i wczesne sygnały | 🔵 |
| **Confidence Engine** | Ocena pewności odpowiedzi / Confidence Score | 🔵 |
| **Agent System** | Rejestr i uruchamianie wyspecjalizowanych agentów | 🔵 |

---

## 6. System agentów AI

Docelowy roster agentów. W MVP realny jest niewielki podzbiór rdzeniowy (np. Planner, Coach, Health, Memory Curator, Notification, Parser/Voice/Vision) — reszta to kierunek 🔵.

| Agent | Agent | Agent |
|-------|-------|-------|
| Planner | Coach | Finance |
| Health | Shopping | Knowledge |
| Research | Travel | Recovery |
| Supplement | Diet | Lab |
| Life Admin | Notification | Memory Curator |
| Scientist | Auditor | Safety |
| Parser | Vision | Voice |
| News | Task | — |

---

## 7. Integracje mobilne i zdrowie

| Integracja | Rola | Status |
|------------|------|--------|
| **Health Connect** | ⭐ Główne źródło danych zdrowotnych Androida: kroki, sen, tętno, waga, aktywność, kalorie, dystans | 🟢 |
| **Samsung Health** | Źródło danych poprzez Health Connect | 🟢 |
| **Google Fit** | Opcjonalne źródło danych | 🟣 |

### Wearables

| Urządzenie | Rola | Status |
|------------|------|--------|
| Suunto | Import aktywności | 🔵 |
| Smartwatch (ogólnie) | Dane aktywności / tętna | 🔵 |
| Opaska monitorująca sen | Dane snu | 🔵 |

---

## 8. Komunikacja / kanały

| Kanał | Rola | Status |
|-------|------|--------|
| **WhatsApp** ⭐⭐⭐⭐⭐ | Najważniejszy kanał: chat, głosówki, reminder, AI Chat, AI Journal (WhatsApp Business Cloud API) | 🟡 |
| **Signal** | Alternatywny kanał dla prywatności (signal-cli / bridge) | 🟣 |
| **Push Notifications** | Powiadomienia push na Androida (FCM) | 🟢 |
| **SMS** | Kanał awaryjny do eskalacji | 🟣 |
| **Email** | Raporty i powiadomienia | 🟣 |

> ⚠️ WhatsApp Cloud API: brak grup z botem, okno 24 h + płatne szablony na wiadomości proaktywne. Household przez 1:1 + wspólny kontekst.

---

## 9. Social Media

| Platforma | Status |
|-----------|--------|
| Instagram | 🔵 |
| Facebook | 🔵 |
| LinkedIn | 🔵 |
| X | 🔵 |
| Threads | 🔵 (opcja) |

---

## 10. Knowledge Hub

| Źródło | Rola | Status |
|--------|------|--------|
| YouTube | Śledzone kanały | 🔵 |
| Reddit | Subreddity | 🔵 |
| RSS | Feedy | 🔵 |
| Blogi | Źródła treści | 🔵 |

---

## 11. Project Management

| Narzędzie | Rola | Status |
|-----------|------|--------|
| Notion | Tworzenie zadań | 🔵 |
| GitHub | Issues | 🔵 |
| Jira | Zadania | 🔵 |
| Trello | Zadania | 🔵 |

---

## 12. Shopping

| Kanał | Status |
|-------|--------|
| Allegro | 🔵 |
| Amazon | 🔵 |
| Cateringi dietetyczne | 🔵 |
| Sklepy internetowe (ogólnie) | 🔵 |

---

## 13. Dokumenty i OCR

| Element | Rola | Status |
|---------|------|--------|
| **OCR** | Dokumenty, badania, faktury, rachunki | 🟡 |
| PDF | Wejście dokumentów | 🟢 |
| Zdjęcia | Wejście dokumentów / analiza | 🟢 |
| CSV / Excel | Import danych strukturalnych | 🟣 |

---

## 14. AI Voice

| Element | Rola | Status |
|---------|------|--------|
| Whisper (STT) | Transkrypcja głosu | 🟢 |
| Voice Journal | Głosowy dziennik (np. 21:00) | 🟢 |
| Voice Commands | Komendy głosowe | 🟡 |
| Voice Notes | Notatki głosowe | 🟢 |

---

## 15. Analiza zdjęć

| Element | Rola | Status |
|---------|------|--------|
| Face Analysis | Analiza twarzy | 🔵 |
| Body Analysis | Analiza sylwetki | 🔵 |
| Progress Photos | Zdjęcia postępów | 🟡 |
| Biological Age | Szacowany wiek biologiczny | 🔵 |

---

## 16. Powiadomienia

| Element | Rola | Status |
|---------|------|--------|
| Push · WhatsApp · Signal · SMS · Email | Kanały dostarczania | 🟢 / 🟡 / 🟣 |
| **Reminder Engine** | Silnik przypomnień | 🟢 |
| **Escalation Engine** | Eskalacja przy braku reakcji | 🟡 |

---

## 17. Panel Desktop / WWW

| Sekcja | Rola | Status |
|--------|------|--------|
| Panel WWW (Laravel + Livewire / Filament) | Pełne analizy, konfiguracja | 🟡 |
| Dashboard · Analytics · Reports | Przegląd i raporty | 🟡 |
| Finance · Knowledge · Health | Widoki modułowe | 🟡 |
| ApexCharts / Chart.js | Wykresy trendów (waga, badania, cashflow) | 🟡 |

---

## 18. Finanse

| Element | Rola | Status |
|---------|------|--------|
| Cash Flow | Przepływy | 🟡 |
| Budget · Planner | Budżet i planowanie | 🟡 |
| Recurring Payments | Płatności cykliczne | 🟡 |
| **Forecast Engine** | Prognozy finansowe | 🔵 |

---

## 19. API / integracje techniczne

| Element | Status |
|---------|--------|
| REST API | 🟢 |
| Webhooks | 🟢 |
| Queues | 🟢 |
| Cron | 🟢 |
| Events | 🟢 |

---

## 20. Auth

| Element | Rola | Status |
|---------|------|--------|
| **Laravel Sanctum** | Główna autoryzacja / tokeny | 🟢 |
| OAuth | Logowanie zewnętrzne / integracje | 🟡 |
| JWT | Do rozważenia | 🟣 |

---

## 21. Synchronizacja

| Element | Status |
|---------|--------|
| Real Time Sync | 🟣 |
| WebSocket | 🟣 |
| Live Updates | 🟣 |

---

## 22. Features produktowe (AI)

Warstwa „produktu" — funkcje widoczne dla użytkownika, budowane na warstwie AI. Większość to kierunek 🔵; część rdzeniowa (Weekly Reports, Insights, Confidence Score, Explainable AI) może pojawić się wcześniej.

| Feature | Feature | Feature |
|---------|---------|---------|
| Digital Twin | Life Operating System | Life GPS |
| Pattern Detection | Predictions | Insights |
| Signals | Why Engine | Recovery Mode |
| AI Emergency Check-in | Weekly Reports | Executive Summary |
| Confidence Score | Explainable AI | — |

---

## 23. MCP — Model Context Protocol 🔵

**Warstwa integracyjna dla agentów.** Standaryzuje sposób, w jaki NoNo łączy się ze światem zewnętrznym — zamiast budować każdą integrację od zera.

Docelowo przez MCP: GitHub · Notion · system plików · bazy danych · kalendarz · poczta · lokalne narzędzia programistyczne.

**Dlaczego warto od razu w roadmapie:** architektura staje się modułowa i łatwa do rozbudowy; nowe integracje wpina się jako serwery MCP bez przepisywania rdzenia.

---

## 24. Dev Tools

| Narzędzie | Rola |
|-----------|------|
| **Codex** | Programista AI — generowanie kodu, refaktoryzacja, testy |
| **ChatGPT** | Product Owner / architekt / UX / analityk / review kodu |
| **Claude** | Programowanie, analiza, implementacja |
| **Cursor** | IDE AI |
| Git + GitHub | Repozytorium, wersjonowanie, podstawa deployu |
| Composer / pub | Zależności PHP i Dart/Flutter |
| Pest / PHPUnit | Testy backendu |
| Pint + PHPStan | Formatowanie i statyczna analiza |
| Telescope / Sentry | Debug i śledzenie błędów produkcyjnych |

---

## 25. Infrastruktura / hosting

| Technologia | Rola | Status |
|-------------|------|--------|
| **Hetzner Cloud** | Serwer produkcyjny (UE = RODO) | 🟢 |
| Ubuntu 24.04 LTS | System operacyjny serwera | 🟢 |
| Nginx + PHP-FPM | Serwer WWW + wykonywanie PHP | 🟢 |
| Docker / docker-compose | Konteneryzacja (opcja) | 🟣 |
| SSL — Let's Encrypt | HTTPS (auto-odnawianie) | 🟢 |
| Cloudflare | DNS, CDN, DDoS, cache | 🟣 |
| Deploy: Git + Deployer | Wdrożenia z repo | 🟢 |
| Backupy automatyczne | Baza + pliki, poza serwerem prod | 🟢 |

---

## 26. Bezpieczeństwo / compliance

| Element | Rola | Status |
|---------|------|--------|
| Sekrety server-side | Klucze API tylko w `.env` na serwerze | 🟢 |
| Szyfrowanie | TLS w tranzycie + dane wrażliwe w spoczynku | 🟢 |
| RODO | Dane kat. szczególnej (zdrowie): zgody, prawo do usunięcia, hosting UE | 🟢 |
| AI Act | Granica insight ≠ diagnoza wpisana w produkt | 🟢 |
| Audit log + rate limiting | Śledzenie dostępu, ochrona API | 🟡 |

---

## 27. Dokumentacja

Markdown (`.md`) · HTML Mockups · ERD · PRD · Roadmap · API Docs · Database Docs · Prompt Library · Backlog · Architecture.

---

> **Do potwierdzenia / uzupełnienia:** (1) technologia panelu web (Livewire vs Inertia+Vue vs Filament), (2) rozmiar serwera Hetzner na start, (3) Docker od razu czy klasyczny deploy, (4) który model embeddingów jako domyślny, (5) rdzeniowy zestaw agentów na MVP.