# jakerains/hci-v3 architecture

> Architecture diagram of the GitHub repository jakerains/hci-v3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jakerains/hci-v3
- Repository: https://github.com/jakerains/hci-v3

## Overview

##### Main Components

A. Frontend Layer:
- Next.js Application (Port 3000)
- Main Interface Components
- NavalHelmInterface
- CompassDisplay
- ShipStatus
- CommandLog
- Theme System
- Voice Command UI

B. Backend Services:
- WebSocket Server (Port 2700)
- Vosk Voice Recognition
- API Routes
- Voice Recognition
- Text-to-Speech
- Command Processing
- Theme Management

C. External Services:
- Google Gemini AI
- ElevenLabs Text-to-Speech
- Vosk Speech Recognition Models

##### Component Relationships

**User Input Layer**
**↓**
**Frontend Components ←→ Context Providers (Theme)**
**↓**
**API Layer**
**↓**
**External Services Layer**

##### Specific Implementation Details

a) User Interface Layer (Blue):
- Voice Input Component
- Visual Components
- Command History
- Settings Management

b) Application Core (Green):
- Custom Hooks
- useVoiceCommands
- useAudioFeedback
- useVoiceRecognition
- Context Providers
- Command Processing

c) Backend Services (Orange):
- Voice Recognition API
- Text-to-Speech API
- Command Processing API
- WebSocket Server

d) External Services (Purple):
- Google Gemini
- ElevenLabs
- Vosk Model Storage

##### Technical Stack Indicators

Technology badges for:
- Next.js 13.5
- TypeScript
- Tailwind CSS
- WebSocket
- Vosk
- External APIs

##### Important Architectural Notes

- Offline capabilities
- API key management flow
- Real-time update paths
- Theme switching system
- Model download/management system

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "User Input Layer"
        VoiceInput["Voice Input"]
        VisualInput["Visual Input"]
    end

    subgraph "Frontend Layer"
        NHI["Naval Helm Interface"]:::component
        CD["Compass Display"]:::component
        SS["Ship Status"]:::component
        CL["Command Log"]:::component
        TS["Theme Switcher"]:::component
        
        subgraph "Custom Hooks"
            VC["Voice Commands"]:::hook
            AF["Audio Feedback"]:::hook
            VR["Voice Recognition"]:::hook
            VoskR["Vosk Recognition"]:::hook
        end
        
        subgraph "Context"
            TC["Theme Context"]:::context
            AP["App Providers"]:::context
        end
    end

    subgraph "Backend Services"
        WS["WebSocket Server"]:::server
        
        subgraph "API Routes"
            VRA["Voice Recognition API"]:::api
            TTSA["Text-to-Speech API"]:::api
            CPA["Command Processing API"]:::api
            TMA["Theme Management API"]:::api
        end
        
        subgraph "Voice Recognition System"
            VS["Vosk Server"]:::vosk
            VSe["Vosk Setup"]:::vosk
            VMM["Vosk Model Management"]:::vosk
            SRC["Speech Recognition Client"]:::vosk
        end
    end

    subgraph "External Services"
        GEM["Google Gemini AI"]:::external
        EL["ElevenLabs TTS"]:::external
        VM["Vosk Models"]:::external
    end

    subgraph "Configuration"
        AK["API Keys Management"]:::config
        CS["Command Store"]:::config
        TS2["Theme System"]:::config
        CF["Configuration"]:::config
    end

    %% Relationships
    VoiceInput --> VR
    VisualInput --> NHI
    NHI --> CD & SS & CL
    VR --> WS
    WS --> VRA
    VRA --> GEM
    GEM --> CPA
    CPA --> EL
    EL --> AF
    TC --> TS
    VMM --> VM
    VS --> SRC

    %% Click Events
    click NHI "https://github.com/jakerains/HCI-V3/blob/main//components/NavalHelmInterface.tsx"
    click CD "https://github.com/jakerains/HCI-V3/blob/main//components/CompassDisplay.tsx"
    click SS "https://github.com/jakerains/HCI-V3/blob/main//components/ShipStatus.tsx"
    click CL "https://github.com/jakerains/HCI-V3/blob/main//components/CommandLog.tsx"
    click TS "https://github.com/jakerains/HCI-V3/blob/main//components/ThemeSwitcher.tsx"
    click WS "https://github.com/jakerains/HCI-V3/blob/main//server.js"
    click VRA "https://github.com/jakerains/HCI-V3/blob/main//app/api/voice-recognition/route.ts"
    click TTSA "https://github.com/jakerains/HCI-V3/blob/main//app/api/text-to-speech/route.ts"
    click CPA "https://github.com/jakerains/HCI-V3/blob/main//app/api/process-command/route.ts"
    click TMA "https://github.com/jakerains/HCI-V3/blob/main//app/api/add-theme/route.ts"
    click VC "https://github.com/jakerains/HCI-V3/blob/main//hooks/useVoiceCommands.ts"
    click AF "https://github.com/jakerains/HCI-V3/blob/main//hooks/useAudioFeedback.ts"
    click VR "https://github.com/jakerains/HCI-V3/blob/main//hooks/useVoiceRecognition.ts"
    click VoskR "https://github.com/jakerains/HCI-V3/blob/main//hooks/useVoskRecognition.ts"
    click TC "https://github.com/jakerains/HCI-V3/blob/main//contexts/ThemeContext.tsx"
    click AP "https://github.com/jakerains/HCI-V3/blob/main//app/providers.tsx"
    click VS "https://github.com/jakerains/HCI-V3/blob/main//scripts/vosk-server.py"
    click VSe "https://github.com/jakerains/HCI-V3/blob/main//scripts/setup-vosk.js"
    click VMM "https://github.com/jakerains/HCI-V3/blob/main//pages/api/vosk-model/index.ts"
    click SRC "https://github.com/jakerains/HCI-V3/blob/main//public/js/speech-recognition.js"
    click AK "https://github.com/jakerains/HCI-V3/blob/main//lib/api-keys.ts"
    click CS "https://github.com/jakerains/HCI-V3/blob/main//lib/commandStore.ts"
    click TS2 "https://github.com/jakerains/HCI-V3/blob/main//lib/themes.ts"
    click CF "https://github.com/jakerains/HCI-V3/blob/main//lib/config.ts"

    %% Styles
    classDef component fill:#a8dadc,stroke:#457b9d
    classDef hook fill:#457b9d,stroke:#1d3557,color:#fff
    classDef context fill:#e63946,stroke:#1d3557,color:#fff
    classDef server fill:#fca311,stroke:#14213d
    classDef api fill:#e5e5e5,stroke:#14213d
    classDef vosk fill:#06d6a0,stroke:#073b4c
    classDef external fill:#118ab2,stroke:#073b4c,color:#fff
    classDef config fill:#ffd166,stroke:#073b4c

    %% Legend
    subgraph Legend
        L1["Component"]:::component
        L2["Hook"]:::hook
        L3["Context"]:::context
        L4["Server"]:::server
        L5["API"]:::api
        L6["Vosk"]:::vosk
        L7["External"]:::external
        L8["Config"]:::config
    end
```
