# ta2002/it-support-agent architecture

> Architecture diagram of the GitHub repository ta2002/it-support-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ta2002/it-support-agent
- Repository: https://github.com/ta2002/it-support-agent

## Overview

##### Project type and purpose
- This is a single-page web application (React + Vite) that runs entirely in the browser.
- It uses browser Web APIs (screen capture, speech recognition, media streaming) and integrates with external AI and TTS services to provide an interactive IT-support assistant.

##### File structure
- Top-level files: Vite config, Tailwind config, tsconfig, package.json, .env example.
- `/src`: all source code:
- `main.tsx` + `index.html` – entry point for bootstrapping the React app.
- `App.tsx` – root application component orchestrating pages and global providers.
- `/hooks` – custom hooks (`useTheme`, `useSelectTheme`).
- `/lib/utils.ts` – shared utility functions.
- `/config/site.ts` – site-wide constants (nav items, metadata).
- `/assets` – images, fonts, etc.
- `/types` – TypeScript type definitions.
- No internal backend directory – all “backend” interactions are via Axios/SDK calls in the browser.

##### Extract architectural insights from the README
- The app flow:
1. User speaks (SpeechRecognition).
2. Screenshot (MediaDevices API).
3. Send question + screenshot to chosen LLM (OpenAI or Groq).
4. Chat history (React state in App).
5. Send AI response to ElevenLabs TTS, play audio.
- UI is built with React + Tailwind + shadcn UI.
- External dependencies: Axios, Groq SDK, OpenAI API, ElevenLabs API, various Web APIs.

##### Main components
a. Client Application (Browser)
- React SPA (App.tsx, component tree)
- UI Components (buttons, cards, select, nav, chat window)
- Custom Hooks & Utils (`useTheme`, `useSelectTheme`, utils.ts)
b. Browser Web APIs
- SpeechRecognition API
- MediaDevices API (screen capture)
- MediaSource API (audio streaming)
c. External AI Services
- OpenAI GPT-4o-mini endpoint
- Groq Llama-vision endpoint
d. External TTS Service
- ElevenLabs API for speech synthesis
e. Static Hosting / Deployment
- Vercel (vercel.json) or any static site host

##### Relationships and data flows
- User → (click/voice) → React UI
- React UI → SpeechRecognition API → transcribed text
- React UI → MediaDevices API → screenshot blob
- React orchestrates: send {transcript, screenshot} via Axios/Groq SDK to LLM
- LLM response → React state → Chat UI
- LLM response → ElevenLabs API → audio stream → MediaSource → audio playback
- Config (site.ts, env vars) feeds into API client modules

##### Architectural patterns & design principles
- Component-based architecture (React + shadcn UI)
- Hook abstraction for cross-cutting concerns (theme, TTS playback)
- Single source of truth for chat state held in App.tsx (or via Context if scaled)
- Environment-driven configuration (VITE_… env vars)
- Layered external service integration (LLM layer vs. TTS layer)

##### Essential elements to capture
- Clear labels on every node (e.g., “Groq Llama-vision API”)
- UI component subtree to illustrate where screen & speech controls live
- Deployment target (Vercel) showing static hosting of index.html + bundle

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User("User"):::external

    %% Client-side Application
    subgraph "Client Application (Browser)" 
        direction TB
        subgraph "Entry Point"
            direction TB
            Main["main.tsx"]:::client
            HTML["index.html"]:::client
        end
        subgraph "Root Component"
            direction TB
            App["App.tsx"]:::client
        end
        subgraph "UI Components"
            direction TB
            UI["UI Components"]:::client
            Nav["main-nav.tsx"]:::client
            ThemeToggle["mode-toggle.tsx"]:::client
            SiteHeader["site-header.tsx"]:::client
            Indicator["tailwind-indicator.tsx"]:::client
            Icons["icons.tsx"]:::client
        end
        subgraph "Logic & Config"
            direction TB
            Hooks["Custom Hooks"]:::client
            UseTheme["useTheme.ts"]:::client
            UseSelect["useSelectTheme.ts"]:::client
            Utils["utils.ts"]:::client
            Config["site.ts"]:::client
            Types["nav.ts"]:::client
            EnvExample[".env.example"]:::client
        end
        subgraph "Assets"
            direction TB
            Assets["src/assets"]:::client
            Public["public"]:::client
        end
    end

    %% Browser Web APIs
    subgraph "Browser Web APIs"
        direction TB
        Speech["SpeechRecognition API"]:::browserapi
        Screen["MediaDevices API (screen capture)"]:::browserapi
        MediaSrc["MediaSource API (audio)"]:::browserapi
    end

    %% External AI Services
    subgraph "External AI Services"
        direction TB
        OpenAI["OpenAI GPT-4o-mini API"]:::externalapi
        Groq["Groq Llama-vision API"]:::externalapi
    end

    %% External TTS Service
    Eleven["ElevenLabs TTS API"]:::externalapi

    %% Deployment
    subgraph "Deployment / Hosting"
        direction TB
        Vercel["Vercel (Static Hosting)"]:::deployment
    end

    %% Flows
    User -->|"1. voice input"| Speech
    User -->|"1. click"| App
    Speech -->|"transcript"| App
    App -->|"2. capture"| Screen
    Screen -->|"screenshot blob"| App
    App -->|"3. LLM request"| OpenAI
    App -->|"3. LLM request"| Groq
    OpenAI -->|"3. LLM response"| App
    Groq -->|"3. LLM response"| App
    App -->|"4. TTS request"| Eleven
    Eleven -->|"4. audio stream"| MediaSrc
    MediaSrc -->|"play audio"| App
    Config -->|"env vars"| App
    Main --> App
    HTML --> Main
    App --> UI
    UI --> Nav
    UI --> ThemeToggle
    UI --> SiteHeader
    UI --> Indicator
    UI --> Icons
    Hooks --> UseTheme
    Hooks --> UseSelect
    Hooks -.-> App
    Utils -.-> App
    Types -.-> App
    EnvExample -.-> Config
    Assets -.-> UI
    Public -.-> Assets
    App --> Vercel

    %% Click Events
    click Main "https://github.com/ta2002/it-support-agent/blob/main/src/main.tsx"
    click HTML "https://github.com/ta2002/it-support-agent/blob/main/index.html"
    click App "https://github.com/ta2002/it-support-agent/blob/main/src/App.tsx"
    click UI "https://github.com/ta2002/it-support-agent/tree/main/src/components/ui"
    click Nav "https://github.com/ta2002/it-support-agent/blob/main/src/components/main-nav.tsx"
    click ThemeToggle "https://github.com/ta2002/it-support-agent/blob/main/src/components/mode-toggle.tsx"
    click SiteHeader "https://github.com/ta2002/it-support-agent/blob/main/src/components/site-header.tsx"
    click Indicator "https://github.com/ta2002/it-support-agent/blob/main/src/components/tailwind-indicator.tsx"
    click Icons "https://github.com/ta2002/it-support-agent/blob/main/src/components/icons.tsx"
    click UseTheme "https://github.com/ta2002/it-support-agent/blob/main/src/hooks/useTheme.ts"
    click UseSelect "https://github.com/ta2002/it-support-agent/blob/main/src/hooks/useSelectTheme.ts"
    click Utils "https://github.com/ta2002/it-support-agent/blob/main/src/lib/utils.ts"
    click Config "https://github.com/ta2002/it-support-agent/blob/main/src/config/site.ts"
    click Assets "https://github.com/ta2002/it-support-agent/tree/main/src/assets"
    click Types "https://github.com/ta2002/it-support-agent/blob/main/src/types/nav.ts"
    click EnvExample "https://github.com/ta2002/it-support-agent/blob/main/.env.example"
    click Vercel "https://github.com/ta2002/it-support-agent/blob/main/vercel.json"

    %% Styles
    classDef client fill:#cce5ff,stroke:#3399ff,color:#003366
    classDef browserapi fill:#d4edda,stroke:#28a745,color:#155724
    classDef externalapi fill:#fff3cd,stroke:#ffcd39,color:#856404
    classDef deployment fill:#e2e3e5,stroke:#6c757d,color:#343a40
    classDef external fill:#f8f9fa,stroke:#6c757d,color:#343a40

    %% Legend
    subgraph Legend
        direction TB
        C1["Blue: Client Modules"]:::client
        C2["Green: Browser APIs"]:::browserapi
        C3["Orange: External APIs"]:::externalapi
        C4["Gray: Deployment"]:::deployment
    end
```
