Data Flow

System Overview

Vista to aplikacja desktopowa zbudowana na Tauri (Rust backend) z React frontend. Poniższy diagram pokazuje pełny przepływ danych przez wszystkie warstwy systemu.

flowchart TB
    subgraph Frontend["Frontend (TypeScript)"]
        UI[UI Components]
        Hooks[Hooks & Services]
        TauriWrapper[tauriWrapper.ts<br/>safeInvoke + withSessionPayload]
    end

    subgraph TauriBridge["Tauri Bridge"]
        InvokeHandler[invoke_handler<br/>generate_handler!]
        SessionValidation[Session Validation<br/>InvokeEnvelope]
    end

    subgraph API["api/ - Tauri Commands"]
        subgraph AuthAPI["auth/"]
            Login[login.rs]
            Password[password.rs]
            Biometric[biometric.rs]
            Pin[pin.rs]
        end

        subgraph UsersAPI["users/"]
            UsersCRUD[crud.rs]
            Invitations[invitations.rs]
            Preferences[preferences.rs]
        end

        subgraph PatientsAPI["patients/"]
            PatientsCRUD[crud.rs]
            PatientsSearch[search.rs]
        end

        subgraph VisitsAPI["visits/"]
            VisitsCRUD[crud.rs]
            VisitsQueries[queries.rs]
            SOAP[soap.rs]
        end

        subgraph AIAPI["ai/"]
            AIChat[chat.rs]
            AITranscription[transcription.rs]
            AISoap[soap.rs]
            AISuggestions[suggestions.rs]
        end

        subgraph AudioAPI["audio/"]
            Recordings[recordings.rs]
            Transcription[transcription.rs]
        end

        subgraph AnalyticsAPI["analytics/"]
            Dashboard[dashboard.rs]
            Trends[trends.rs]
        end
    end

    subgraph Domain["domain/ - Business Logic"]
        subgraph AuthDomain["auth/"]
            SessionLogic[session.rs]
            Permissions[permissions.rs]
        end

        subgraph AIDomain["ai/"]
            Prompts[prompts.rs]
            Streaming[streaming.rs]
            Models[models.rs]
        end

        subgraph MedicalDomain["medical/"]
            Validation[validation.rs]
        end
    end

    subgraph Infra["infra/ - Infrastructure"]
        subgraph Database["database/"]
            Schema[schema.rs]
            DBModels[models.rs]
            Queries[queries/]
        end

        subgraph AIProviders["ai_providers/"]
            Resolver[resolver.rs]
            OpenAI[openai.rs]
            Libraxis[libraxis.rs]
        end

        subgraph Engines["engines/"]
            STT[stt/]
            TTS[tts/]
            RecordingsEngine[recordings/]
        end

        subgraph Platform["platform/"]
            MacOS[macos/]
            Windows[windows/]
        end
    end

    subgraph Shared["shared/"]
        Types[types/<br/>ids, session, errors]
        Utils[utils/<br/>cipher, logger]
        Middleware[middleware/<br/>auth]
    end

    subgraph External["External Services"]
        OpenAICloud[OpenAI API]
        LibraxisCloud[Libraxis API]
        SQLite[(SQLite DB)]
    end

    %% Frontend → Tauri
    UI --> Hooks
    Hooks --> TauriWrapper
    TauriWrapper --> InvokeHandler

    %% Tauri Bridge → API
    InvokeHandler --> SessionValidation
    SessionValidation --> AuthAPI
    SessionValidation --> UsersAPI
    SessionValidation --> PatientsAPI
    SessionValidation --> VisitsAPI
    SessionValidation --> AIAPI
    SessionValidation --> AudioAPI
    SessionValidation --> AnalyticsAPI

    %% API → Domain
    AuthAPI --> AuthDomain
    AIAPI --> AIDomain
    VisitsAPI --> MedicalDomain

    %% API → Shared
    AuthAPI --> Middleware
    UsersAPI --> Middleware
    PatientsAPI --> Middleware

    %% Domain → Infra
    AuthDomain --> Database
    AIDomain --> AIProviders
    AIDomain --> Engines

    %% API → Infra (direct for simple CRUD)
    PatientsAPI --> Database
    VisitsAPI --> Database
    UsersAPI --> Database
    AnalyticsAPI --> Database
    AudioAPI --> Engines

    %% Infra → External
    AIProviders --> OpenAICloud
    AIProviders --> LibraxisCloud
    Database --> SQLite
    STT --> OpenAICloud
    TTS --> OpenAICloud

    %% Shared usage
    Types -.-> API
    Types -.-> Domain
    Utils -.-> Infra

---

Warstwy architektury

Frontend Layer

Warstwa	Odpowiedzialność
UI Components	Renderowanie interfejsu, obsługa inputów
Hooks & Services	Logika biznesowa, cache, state management
tauriWrapper	IPC wrapper, session payload, error handling

Tauri Bridge

Element	Rola
invoke_handler	Routing komend do odpowiednich handlerów
Session Validation	Weryfikacja InvokeEnvelope, autoryzacja

API Layer (api/)

Thin wrappers - komendy Tauri wywołujące logikę domenową:

• auth/ - login, password, biometrics, PIN
• users/ - CRUD, invitations, preferences
• patients/ - CRUD, search, pagination
• visits/ - CRUD, SOAP, finalization
• ai/ - chat, transcription, suggestions
• audio/ - recordings, transcription jobs
• analytics/ - dashboard, trends

Domain Layer (domain/)

Pure Rust - logika biznesowa bez side effects:

• auth/ - session validation, permissions
• ai/ - prompt building, streaming, model selection
• medical/ - walidacja leków, dawek

Infrastructure Layer (infra/)

Integracje z zewnętrznymi systemami:

• database/ - SQLite schema, queries, migrations
• ai_providers/ - OpenAI, Libraxis, resolver
• engines/ - STT, TTS, recordings
• platform/ - macOS (TouchID), Windows specifics

Shared Layer (shared/)

Utilities używane przez wszystkie warstwy:

• types/ - SessionId, UserId, InvokeEnvelope
• utils/ - cipher, secure logger, HMAC
• middleware/ - auth middleware

---

Request Flow Example

Patient Creation

sequenceDiagram
    participant UI as React UI
    participant Hook as usePatients
    participant Wrapper as tauriWrapper
    participant Bridge as Tauri Bridge
    participant API as api/patients
    participant DB as database/

    UI->>Hook: createPatient(data)
    Hook->>Wrapper: safeInvoke('create_patient', data)
    Wrapper->>Wrapper: withSessionPayload(data)
    Wrapper->>Bridge: invoke('create_patient', envelope)
    Bridge->>Bridge: Validate session
    Bridge->>API: create_patient(db, data)
    API->>DB: INSERT INTO patients
    DB-->>API: Patient record
    API-->>Bridge: Result<Patient>
    Bridge-->>Wrapper: Patient
    Wrapper-->>Hook: Patient
    Hook-->>UI: Update state

AI Chat with Streaming

sequenceDiagram
    participant UI as ChatPanel
    participant Hook as useChatHistory
    participant Client as UnifiedAIClient
    participant API as api/ai/chat
    participant Domain as domain/ai
    participant Provider as ai_providers

    UI->>Hook: sendMessage(text)
    Hook->>Client: chatStream(message)
    Client->>API: unified_ai_chat_stream
    API->>Domain: build_prompt(context)
    Domain-->>API: Prompt
    API->>Provider: stream_chat(prompt)

    loop Token streaming
        Provider-->>API: token
        API-->>Client: emit('ai-stream-token')
        Client-->>Hook: onToken(token)
        Hook-->>UI: Update display
    end

    Provider-->>API: complete
    API-->>Client: emit('ai-stream-complete')
    Client-->>Hook: onComplete(response)
    Hook-->>UI: Final message

---

Data Persistence

SQLite Database

Wszystkie dane zapisywane w lokalnej bazie SQLite:

~/Library/Application Support/Vista/vista.db  (macOS)
%APPDATA%/Vista/vista.db                       (Windows)
~/.local/share/Vista/vista.db                  (Linux)

Audio Files

Nagrania audio zapisywane w osobnym katalogu:

~/Library/Application Support/Vista/recordings/  (macOS)

Secure Storage

Wrażliwe dane (API keys, tokens) w systemowym keychain:

• macOS - Keychain Services
• Windows - Credential Manager
• Linux - Secret Service API

---

Error Propagation

flowchart LR
    subgraph Backend
        DB[Database Error]
        AI[AI Service Error]
        Auth[Auth Error]
    end

    subgraph Bridge
        Result[Result<T, String>]
    end

    subgraph Frontend
        Wrapper[safeInvoke catch]
        Hook[Hook error state]
        UI[Error UI]
    end

    DB --> Result
    AI --> Result
    Auth --> Result
    Result --> Wrapper
    Wrapper --> Hook
    Hook --> UI

Każdy błąd backend jest konwertowany do String i propagowany przez Tauri IPC do frontend, gdzie jest obsługiwany przez error boundaries i toast notifications.

---

Related

• Backend Overview - Szczegóły backend
• Frontend Overview - Szczegóły frontend
• Database Schema - Struktura bazy danych