JARVIS Docs

Jarvis - Voice.Assistant.Web

Jarvis to webowy interfejs asystenta AI oparty o Flask, Jinja2, SQLAlchemy i integracje z usługami zewnętrznymi. Aplikacja udostępnia panel rozmowy, konta użytkowników, historię konwersacji, konfigurację modelu, opcjonalny tor głosowy Speaches oraz mechanizm zgłaszania błędów do Azure Boards z powiadomieniami Discord.

Repozytorium jest po refaktoryzacji z wcześniejszej struktury monolitycznej do modularnej architektury opartej o Flask blueprints, serwisy domenowe, testowalny Docker Compose i osobne procesy tła. Aktualnie system obejmuje także Redis, worker pamięci oraz lokalny LLM używany do ekstrakcji podsumowań i faktów o użytkowniku.

Cel Projektu

Jarvis ma pełnić rolę webowego asystenta AI:

  • użytkownik może założyć konto i zalogować się do aplikacji,
  • po zalogowaniu może korzystać z widoku chatu,
  • rozmowy są zapisywane w bazie danych jako historia konwersacji,
  • aplikacja może dopinać do promptu krótką pamięć rozmowy i trwałe fakty o użytkowniku,
  • użytkownik może zmieniać model, temperaturę, liczbę odpowiedzi i konfigurację głosu,
  • aplikacja może korzystać z OpenAI API do generowania odpowiedzi,
  • Speaches może generować audio TTS, a browserowy voice mode pozostaje fallbackiem,
  • formularz zgłaszania błędów tworzy work item w Azure Boards,
  • zgłoszenia błędów mogą być wysyłane jako powiadomienia Discord webhookiem,
  • pipeline CI/CD buduje obraz Docker, uruchamia testy jakości i smoke testy stacka Compose.

Aktualny Stan Architektury

Aplikacja działa jako Flask application factory:

app.py
  -> backend.create_app()
       -> Flask(...)
       -> db.init_app(app)
       -> ma.init_app(app)
       -> login_manager.init_app(app)
       -> Redis-backed sessions and rate limits
       -> register blueprints
       -> setup tracing

Główne aktywne moduły HTTP są podzielone według domen:

  • backend/blueprints/public.py - strony publiczne i healthcheck,
  • backend/blueprints/docs.py - renderowanie dokumentacji Markdown,
  • backend/blueprints/auth.py - rejestracja, logowanie, wylogowanie,
  • backend/blueprints/users.py - operacje na użytkownikach,
  • backend/blueprints/chat.py - chat, konwersacje, konfiguracja chatu, modele i języki,
  • backend/blueprints/speech.py - konfiguracja głosu i synteza TTS przez Speaches,
  • backend/blueprints/bug_report.py - zgłoszenia błędów do Azure Boards i Discord,
  • backend/services/auth_discord.py - callback OAuth2 Discord.

Serwisy domenowe izolują logikę zewnętrznych integracji i procesów tła:

  • backend/services/openai_service.py - budowanie promptu, wywołanie OpenAI, zapis historii i enqueue jobów pamięci,
  • backend/services/memory_service.py - kolejka Redis, kontekst pamięci, aktualizacja summary i memory items,
  • backend/services/memory_extractors.py - lokalny LLM extractor i fallback heurystyczny,
  • backend/services/speech_service.py - synteza TTS, cache audio i walidacja konfiguracji Speaches,
  • backend/services/cache_service.py - wspólny klient Redis i pomocnicze operacje cache.

Warstwa uruchomieniowa w Compose obejmuje:

  • web - aplikację Flask/Gunicorn,
  • db - Postgres z obrazem pgvector/pgvector:pg13,
  • redis - sesje, rate limit, TTS cache i kolejkę pamięci,
  • memory-worker - proces tła aktualizujący pamięć,
  • local-llm i local-llm-models - Ollama oraz bootstrap modelu qwen2.5:3b-instruct,
  • speaches i speaches-models - lokalny serwis mowy i bootstrap modeli TTS,
  • mockserver - lokalny mock reCAPTCHA dla testów/integracji.

Diagramy przepływów znajdują się w Architekturze Systemu.

Historia Refaktoryzacji i Stara Logika

Pierwotnie aplikacja miała centralny moduł backend/routes.py, który łączył renderowanie stron, auth, CRUD użytkowników, chat, Azure Boards, Discord i error handlery. Po rozpoczęciu refaktoryzacji nowe blueprinty zaczęły dublować endpointy starego monolitu.

Efekty uboczne starego podejścia:

  • nie było jasne, który moduł jest źródłem prawdy dla danego endpointu,
  • testy mogły trafiać w starą logikę zamiast w nową,
  • import modułów mógł inicjalizować klientów zewnętrznych za wcześnie,
  • część logiki była trudna do testowania bez globalnych monkeypatchy,
  • plik routes.py łączył HTTP, walidację, logikę biznesową, integracje i serializację.

Obecnie:

  • backend/routes.py nie istnieje już jako aktywny element aplikacji,
  • create_app() rejestruje tylko blueprinty domenowe,
  • openai_service.py nie definiuje tras Flask, tylko funkcje serwisowe,
  • klient OpenAI jest inicjalizowany leniwie,
  • db.create_all() jest ograniczone do testów, AUTO_CREATE_DB=true albo jednorazowego db-init,
  • testowanie obrazu Docker odbywa się jako black-box HTTP na finalnym stacku Compose.

Jeżeli w historii Git lub w starszym branchu pojawi się backend/routes.py, należy traktować go jako dawny monolit, nie jako docelowy wzorzec implementacji.

Struktura Repozytorium

.
|-- app.py
|-- backend/
|   |-- __init__.py
|   |-- config.py
|   |-- extensions.py
|   |-- http.py
|   |-- models.py
|   |-- observability.py
|   |-- blueprints/
|   |   |-- auth.py
|   |   |-- bug_report.py
|   |   |-- chat.py
|   |   |-- docs.py
|   |   |-- public.py
|   |   |-- speech.py
|   |   `-- users.py
|   |-- services/
|   |   |-- auth_discord.py
|   |   |-- cache_service.py
|   |   |-- memory_extractors.py
|   |   |-- memory_service.py
|   |   |-- openai_service.py
|   |   `-- speech_service.py
|   |-- workers/
|   |   `-- memory_worker.py
|   |-- data/
|   |   `-- speaches-voices.json
|   |-- templates/
|   `-- static/
|-- scripts/
|-- tests/
|   |-- test_endpoints.py
|   |-- test_memory_extractors.py
|   |-- test_memory_service.py
|   |-- test_models.py
|   `-- integration/
|       `-- test_container_endpoints.py
|-- Dockerfile
|-- docker-compose.yml
|-- azure-pipelines.yml
|-- requirements.txt
|-- requirements-dev.txt
|-- pyproject.toml
|-- docs/
`-- mockserver/

Najważniejsze Pliki

  • backend/__init__.py - Flask application factory, inicjalizacja rozszerzeń i rejestracja blueprintów.
  • backend/config.py - konfiguracja oparta o zmienne środowiskowe.
  • backend/models.py - modele SQLAlchemy i schematy Marshmallow.
  • backend/blueprints/ - aktywne moduły HTTP.
  • backend/services/ - logika integracji, cache, pamięci i speech.
  • backend/workers/memory_worker.py - proces tła dla kolejki pamięci.
  • backend/data/speaches-voices.json - katalog modeli i głosów TTS dla UI oraz bootstrapu modeli.
  • tests/ - testy jednostkowe, endpointów i smoke testy kontenera.
  • Dockerfile - multi-stage build obrazu runtime/tester/production.
  • docker-compose.yml - lokalny stack web, Postgres, Redis, memory-worker, local LLM, Speaches i MockServer.
  • azure-pipelines.yml - pipeline CI/CD.