# pranavshree-ai/nova-ai architecture

> Architecture diagram of the GitHub repository pranavshree-ai/nova-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pranavshree-ai/nova-ai
- Repository: https://github.com/pranavshree-ai/nova-ai

## Overview

NOVA is a browser-based holographic voice-assistant interface. The user opens the orb UI, starts voice interaction or webcam gestures, and receives spoken responses while gestures and pointer controls manipulate the 3D scene. The main documented branches are voice/transcription and AI actions, hand tracking, and themed 3D rendering. The excerpts establish the page-to-component, component-to-runtime modules, and API-to-agent calls; browser speech synthesis and some UI wiring are not fully shown, so those links are omitted.

Main entry points: [`components/JarvisOrb.tsx`](https://github.com/pranavshree-ai/nova-ai/blob/main/components/JarvisOrb.tsx) (Orb HUD), [`lib/useVoiceAgent.ts`](https://github.com/pranavshree-ai/nova-ai/blob/main/lib/useVoiceAgent.ts) (Voice state and audio), [`app/api/nova/route.ts`](https://github.com/pranavshree-ai/nova-ai/blob/main/app/api/nova/route.ts) (Assistant API), [`lib/handTracker.ts`](https://github.com/pranavshree-ai/nova-ai/blob/main/lib/handTracker.ts) (Hand tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Orb interface"]
  node_page["Home page<br/>[page.tsx]"]
  node_orb["Orb HUD<br/>[JarvisOrb.tsx]"]
  node_scene["3D orb scene<br/>[orbScene.ts]"]
end

subgraph group_vision["Gesture controls"]
  node_tracker["Hand tracking<br/>[handTracker.ts]"]
end

subgraph group_voice["Voice assistant"]
  node_voicehook["Voice state and audio<br/>[useVoiceAgent.ts]"]
end

subgraph group_server["Assistant services"]
  node_transcribe["Speech transcription<br/>[route.ts]"]
  node_nova["Assistant API<br/>[route.ts]"]
  node_browser["Browser actions<br/>[browserAgent.ts]"]
  node_search["Web search<br/>[searchAgent.ts]"]
end

node_user(("User"))
node_groq{{"Groq AI services"}}
node_mediapipe{{"MediaPipe models"}}
node_web{{"Web results"}}
node_browserapp{{"System browser"}}
node_googletts{{"Google TTS"}}

node_user -->|"opens"| node_page
node_page -->|"renders"| node_orb
node_orb -->|"creates and controls"| node_scene
node_orb -->|"starts and configures"| node_tracker
node_tracker -->|"loads vision model"| node_mediapipe
node_tracker -->|"gesture callbacks"| node_scene
node_orb -->|"starts and stops"| node_voicehook
node_voicehook -.->|"uploads audio"| node_transcribe
node_transcribe -->|"transcribes audio"| node_groq
node_voicehook -->|"sends transcript and history"| node_nova
node_nova -->|"requests assistant response"| node_groq
node_nova -->|"executes browser tool"| node_browser
node_nova -->|"requests search"| node_search
node_search -->|"fetches search results"| node_web
node_browser -->|"opens action URL"| node_browserapp
node_voicehook -.->|"may request TTS"| node_googletts

click node_page "https://github.com/pranavshree-ai/nova-ai/blob/main/app/page.tsx"
click node_orb "https://github.com/pranavshree-ai/nova-ai/blob/main/components/JarvisOrb.tsx"
click node_scene "https://github.com/pranavshree-ai/nova-ai/blob/main/lib/orbScene.ts"
click node_tracker "https://github.com/pranavshree-ai/nova-ai/blob/main/lib/handTracker.ts"
click node_voicehook "https://github.com/pranavshree-ai/nova-ai/blob/main/lib/useVoiceAgent.ts"
click node_transcribe "https://github.com/pranavshree-ai/nova-ai/blob/main/app/api/transcribe/route.ts"
click node_nova "https://github.com/pranavshree-ai/nova-ai/blob/main/app/api/nova/route.ts"
click node_browser "https://github.com/pranavshree-ai/nova-ai/blob/main/lib/browserAgent.ts"
click node_search "https://github.com/pranavshree-ai/nova-ai/blob/main/lib/searchAgent.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_page,node_orb,node_scene,node_user,node_browserapp toneBlue
class node_tracker toneAmber
class node_voicehook,node_mediapipe toneMint
class node_transcribe,node_nova,node_browser,node_search toneRose
class node_groq,node_web,node_googletts toneIndigo
```

## Components

### Orb interface

- [Home page](https://github.com/pranavshree-ai/nova-ai/blob/main/app/page.tsx): `app/page.tsx`
- [Orb HUD](https://github.com/pranavshree-ai/nova-ai/blob/main/components/JarvisOrb.tsx): `components/JarvisOrb.tsx`
- [3D orb scene](https://github.com/pranavshree-ai/nova-ai/blob/main/lib/orbScene.ts): `lib/orbScene.ts`

### Gesture controls

- [Hand tracking](https://github.com/pranavshree-ai/nova-ai/blob/main/lib/handTracker.ts): `lib/handTracker.ts`

### Voice assistant

- [Voice state and audio](https://github.com/pranavshree-ai/nova-ai/blob/main/lib/useVoiceAgent.ts): `lib/useVoiceAgent.ts`

### Assistant services

- [Speech transcription](https://github.com/pranavshree-ai/nova-ai/blob/main/app/api/transcribe/route.ts): `app/api/transcribe/route.ts`
- [Assistant API](https://github.com/pranavshree-ai/nova-ai/blob/main/app/api/nova/route.ts): `app/api/nova/route.ts`
- [Browser actions](https://github.com/pranavshree-ai/nova-ai/blob/main/lib/browserAgent.ts): `lib/browserAgent.ts`
- [Web search](https://github.com/pranavshree-ai/nova-ai/blob/main/lib/searchAgent.ts): `lib/searchAgent.ts`

### Other components

- **User**
- **Groq AI services**
- **MediaPipe models**
- **Web results**
- **System browser**
- **Google TTS**

## Connections

- User → Home page: opens (evidence: `app/page.tsx`)
- Home page → Orb HUD: renders (evidence: `app/page.tsx`)
- Orb HUD → 3D orb scene: creates and controls (evidence: `components/JarvisOrb.tsx`)
- Orb HUD → Hand tracking: starts and configures (evidence: `components/JarvisOrb.tsx`)
- Hand tracking → MediaPipe models: loads vision model (evidence: `lib/handTracker.ts`)
- Hand tracking → 3D orb scene: gesture callbacks (evidence: `components/JarvisOrb.tsx`)
- Orb HUD → Voice state and audio: starts and stops (evidence: `components/JarvisOrb.tsx`)
- Voice state and audio → Speech transcription: uploads audio
- Speech transcription → Groq AI services: transcribes audio (evidence: `app/api/transcribe/route.ts`)
- Voice state and audio → Assistant API: sends transcript and history (evidence: `lib/useVoiceAgent.ts`)
- Assistant API → Groq AI services: requests assistant response (evidence: `app/api/nova/route.ts`)
- Assistant API → Browser actions: executes browser tool (evidence: `app/api/nova/route.ts`)
- Assistant API → Web search: requests search (evidence: `app/api/nova/route.ts`)
- Web search → Web results: fetches search results (evidence: `lib/searchAgent.ts`)
- Browser actions → System browser: opens action URL (evidence: `lib/browserAgent.ts`)
- Voice state and audio → Google TTS: may request TTS
