# zackakil/immersive-language-learning-with-live-api architecture

> Architecture diagram of the GitHub repository zackakil/immersive-language-learning-with-live-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zackakil/immersive-language-learning-with-live-api
- Repository: https://github.com/zackakil/immersive-language-learning-with-live-api

## Overview

Immersive Language Learning is a browser-based roleplay practice app backed by a FastAPI service and Gemini Live. A learner moves from the welcome screen to choosing a mission, languages, and a learning mode, then practices in a live audio conversation and receives a completion score and feedback. The browser streams media through the service to Gemini and renders conversation updates. The README also describes optional bot protection, rate limiting, and BigQuery metrics. Some backend and UI excerpts are partial, so uncertain internal connections are omitted.

Main entry points: [`src/components/app-root.js`](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/app-root.js) (App navigation), [`src/components/view-chat.js`](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/view-chat.js) (Roleplay session), [`server/main.py`](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/server/main.py) (HTTP and WebSocket service), [`src/lib/gemini-live/geminilive.js`](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/lib/gemini-live/geminilive.js) (Live API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning_ui["Learning experience"]
  node_app_root["App navigation<br/>[app-root.js]"]
  node_splash["Welcome screen<br/>[view-splash.js]"]
  node_missions["Mission selection<br/>[view-missions.js]"]
  node_mission_data["Mission catalog<br/>[missions.json]"]
  node_chat["Roleplay session<br/>[view-chat.js]"]
  node_summary["Session results<br/>[view-summary.js]"]
  node_text_cycler["Prompt text<br/>[text-cycler.js]"]
  node_transcript["Live transcript<br/>[live-transcript.js]"]
  node_visualizer["Audio visualizer"]
end

subgraph group_live_client["Live interaction"]
  node_gemini_client["Live API client<br/>[geminilive.js]"]
  node_media_utils["Media streaming<br/>[mediaUtils.js]"]
end

subgraph group_service["Application service"]
  node_api["HTTP and WebSocket service<br/>[main.py]"]
  node_gemini_server["Gemini session<br/>[gemini_live.py]"]
  node_config["Configuration helpers<br/>[config_utils.py]"]
  node_fingerprint["Request fingerprint<br/>[fingerprint.py]"]
end

subgraph group_operations["Trust and metrics"]
  node_recaptcha["reCAPTCHA validator"]
  node_tracker["Event tracking<br/>[simple_tracker.py]"]
end

node_learner(("Learner"))
node_recaptcha_service{{"reCAPTCHA Enterprise"}}
node_bigquery[("BigQuery")]
node_gemini_service{{"Gemini Live API"}}

node_learner -->|"uses"| node_app_root
node_app_root -->|"shows"| node_splash
node_app_root -->|"shows"| node_missions
node_app_root -->|"shows"| node_chat
node_app_root -->|"shows"| node_summary
node_missions -->|"loads"| node_mission_data
node_chat -->|"configures"| node_gemini_client
node_chat -->|"uses"| node_media_utils
node_chat -->|"updates"| node_transcript
node_chat -->|"connects"| node_visualizer
node_chat -.->|"provides results"| node_summary
node_app_root -->|"uses"| node_text_cycler
node_gemini_client -->|"authenticates"| node_api
node_gemini_client -->|"streams WebSocket"| node_api
node_media_utils -->|"sends audio"| node_gemini_client
node_api -->|"starts session"| node_gemini_server
node_gemini_server -.->|"streams conversation"| node_gemini_service
node_api -.->|"validates token"| node_recaptcha
node_recaptcha -->|"assesses token"| node_recaptcha_service
node_api -->|"records events"| node_tracker
node_tracker -->|"writes metrics"| node_bigquery

click node_app_root "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/app-root.js"
click node_splash "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/view-splash.js"
click node_missions "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/view-missions.js"
click node_mission_data "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/data/missions.json"
click node_chat "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/view-chat.js"
click node_summary "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/view-summary.js"
click node_text_cycler "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/text-cycler.js"
click node_transcript "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/live-transcript.js"
click node_visualizer "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/audio-visualizer.js"
click node_gemini_client "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/lib/gemini-live/geminilive.js"
click node_media_utils "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/lib/gemini-live/mediaUtils.js"
click node_api "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/server/main.py"
click node_gemini_server "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/server/gemini_live.py"
click node_config "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/server/config_utils.py"
click node_fingerprint "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/server/fingerprint.py"
click node_recaptcha "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/server/recaptcha_validator.py"
click node_tracker "https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/server/simple_tracker.py"

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_app_root,node_splash,node_missions,node_mission_data,node_chat,node_summary,node_text_cycler,node_transcript,node_visualizer toneBlue
class node_gemini_client,node_media_utils,node_bigquery toneAmber
class node_api,node_gemini_server,node_config,node_fingerprint,node_gemini_service toneMint
class node_recaptcha,node_tracker toneRose
class node_learner,node_recaptcha_service toneIndigo
```

## Components

### Learning experience

- [App navigation](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/app-root.js): `src/components/app-root.js`
- [Welcome screen](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/view-splash.js): `src/components/view-splash.js`
- [Mission selection](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/view-missions.js): `src/components/view-missions.js`
- [Mission catalog](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/data/missions.json): `src/data/missions.json`
- [Roleplay session](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/view-chat.js): `src/components/view-chat.js`
- [Session results](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/view-summary.js): `src/components/view-summary.js`
- [Prompt text](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/text-cycler.js): `src/components/text-cycler.js`
- [Live transcript](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/live-transcript.js): `src/components/live-transcript.js`
- [Audio visualizer](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/components/audio-visualizer.js): `src/components/audio-visualizer.js`

### Live interaction

- [Live API client](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/lib/gemini-live/geminilive.js): `src/lib/gemini-live/geminilive.js`
- [Media streaming](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/src/lib/gemini-live/mediaUtils.js): `src/lib/gemini-live/mediaUtils.js`

### Application service

- [HTTP and WebSocket service](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/server/main.py): `server/main.py`
- [Gemini session](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/server/gemini_live.py): `server/gemini_live.py`
- [Configuration helpers](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/server/config_utils.py): `server/config_utils.py`
- [Request fingerprint](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/server/fingerprint.py): `server/fingerprint.py`

### Trust and metrics

- [reCAPTCHA validator](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/server/recaptcha_validator.py): `server/recaptcha_validator.py`
- [Event tracking](https://github.com/zackakil/immersive-language-learning-with-live-api/blob/main/server/simple_tracker.py): `server/simple_tracker.py`

### Other components

- **Learner**
- **reCAPTCHA Enterprise**
- **BigQuery**
- **Gemini Live API**

## Connections

- Learner → App navigation: uses (evidence: `README.md`)
- App navigation → Welcome screen: shows (evidence: `src/components/app-root.js`)
- App navigation → Mission selection: shows (evidence: `src/components/app-root.js`)
- App navigation → Roleplay session: shows (evidence: `src/components/app-root.js`)
- App navigation → Session results: shows (evidence: `src/components/app-root.js`)
- Mission selection → Mission catalog: loads (evidence: `src/components/view-missions.js`)
- Roleplay session → Live API client: configures (evidence: `src/components/view-chat.js`)
- Roleplay session → Media streaming: uses (evidence: `src/components/view-chat.js`)
- Roleplay session → Live transcript: updates (evidence: `src/components/view-chat.js`)
- Roleplay session → Audio visualizer: connects (evidence: `src/components/view-chat.js`)
- Roleplay session → Session results: provides results
- App navigation → Prompt text: uses (evidence: `src/components/app-root.js`)
- Live API client → HTTP and WebSocket service: authenticates (evidence: `src/lib/gemini-live/geminilive.js`)
- Live API client → HTTP and WebSocket service: streams WebSocket (evidence: `README.md`)
- Media streaming → Live API client: sends audio (evidence: `src/lib/gemini-live/mediaUtils.js`)
- HTTP and WebSocket service → Gemini session: starts session (evidence: `server/main.py`)
- Gemini session → Gemini Live API: streams conversation (evidence: `README.md`)
- HTTP and WebSocket service → reCAPTCHA validator: validates token (evidence: `server/main.py`)
- reCAPTCHA validator → reCAPTCHA Enterprise: assesses token (evidence: `server/recaptcha_validator.py`)
- HTTP and WebSocket service → Event tracking: records events (evidence: `README.md`)
- Event tracking → BigQuery: writes metrics (evidence: `server/simple_tracker.py`)