# siddhantsinghrao/build-with-agora architecture

> Architecture diagram of the GitHub repository siddhantsinghrao/build-with-agora, 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/siddhantsinghrao/build-with-agora
- Repository: https://github.com/siddhantsinghrao/build-with-agora

## Overview

StudyCircle’s primary workflow is a student joining a spoken tutoring session while a teacher observes live per-student comprehension reports. The repository also contains a separate Next.js voice tutor/counsellor implementation and an older static client with outbound calling. The main backend excerpt shows token issuance, Agora agent control, LLM proxying, report extraction, and telephony configuration; the documented README clarifies the primary UI/API workflow. Several UI and alternate-app relationships are not excerpted, so those links are omitted rather than inferred.

Main entry points: [`server/server.js`](https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js) (Session API), [`voice-app-next/lib/agora.ts`](https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/lib/agora.ts) (Agora Client Logic), [`web/components/TeacherDashboard.tsx`](https://github.com/siddhantsinghrao/build-with-agora/blob/main/web/components/TeacherDashboard.tsx) (Teacher Dashboard), [`voice-app-next/app/api/agent/start/route.ts`](https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/app/api/agent/start/route.ts) (Start Agent Route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_primary["StudyCircle Main"]
  node_web_student["Student Console<br/>[StudentConsole.tsx]"]
  node_web_teacher["Teacher Dashboard"]
  node_lead_cards["Learning Cards<br/>[LeadCard.tsx]"]
  node_web_api["Web API Client<br/>[api.ts]"]
end

subgraph group_backend["Session Backend"]
  node_server_api["Session API<br/>[server.js]"]
  node_rtc_tokens["RTC Tokens<br/>[server.js]"]
  node_agent_control["Agent Control<br/>[server.js]"]
  node_transcripts["Transcript Capture<br/>[server.js]"]
  node_learning_reports["Learning Reports<br/>[server.js]"]
  node_call_control["Outbound Calls<br/>[server.js]"]
  node_telephony_config["Telephony Config<br/>[server.js]"]
end

subgraph group_voice_next["Next Voice App"]
  node_voice_session["Voice Session<br/>[VoiceSession.tsx]"]
  node_next_start["Start Agent Route<br/>[route.ts]"]
  node_next_stop["Stop Agent Route<br/>[route.ts]"]
  node_next_status["Agent Status Route<br/>[route.ts]"]
  node_next_token["Token Route<br/>[route.ts]"]
  node_next_sessions["Sessions Route<br/>[route.ts]"]
  node_next_dashboard["Session Dashboard<br/>[page.tsx]"]
  node_agora_lib["Agora Client Logic<br/>[agora.ts]"]
  node_session_store[("Session Store<br/>[sessions.ts]")]
end

subgraph group_legacy["Legacy Calling"]
  node_legacy_ui["Counsellor UI<br/>[talk.html]"]
end

node_student(("Student"))
node_teacher(("Teacher"))
node_agora["Agora Services"]
node_llm["LLM Service"]
node_vobiz["Vobiz"]
node_phone_student(("Student Phone"))

node_student -->|"uses"| node_web_student
node_web_student -->|"calls session APIs"| node_server_api
node_teacher -->|"views reports"| node_web_teacher
node_web_teacher -->|"loads live data"| node_server_api
node_web_teacher -->|"shows student cards"| node_lead_cards
node_server_api -->|"issues tokens"| node_rtc_tokens
node_server_api -->|"starts and stops"| node_agent_control
node_agent_control -->|"controls agents"| node_agora
node_server_api -->|"captures turns"| node_transcripts
node_transcripts -->|"forwards prompts"| node_llm
node_server_api -->|"extracts reports"| node_learning_reports
node_learning_reports -->|"requests extraction"| node_llm
node_server_api -->|"starts calls"| node_call_control
node_call_control -->|"uses SIP gateway"| node_agora
node_call_control -->|"checks credentials"| node_vobiz
node_legacy_ui -->|"configures calling"| node_server_api
node_legacy_ui -->|"calls"| node_phone_student
node_voice_session -->|"starts agent"| node_next_start
node_voice_session -->|"stops agent"| node_next_stop
node_next_start -->|"starts agent"| node_agora_lib
node_next_start -->|"adds session"| node_session_store
node_next_stop -->|"stops agent"| node_agora_lib
node_next_stop -->|"removes session"| node_session_store
node_next_status -->|"queries agent"| node_agora_lib
node_next_token -->|"mints token"| node_agora_lib
node_next_sessions -->|"lists sessions"| node_session_store
node_next_dashboard -.->|"reads sessions"| node_next_sessions
node_telephony_config -->|"tests credentials"| node_vobiz

click node_web_student "https://github.com/siddhantsinghrao/build-with-agora/blob/main/web/components/StudentConsole.tsx"
click node_web_teacher "https://github.com/siddhantsinghrao/build-with-agora/blob/main/web/components/TeacherDashboard.tsx"
click node_lead_cards "https://github.com/siddhantsinghrao/build-with-agora/blob/main/web/components/LeadCard.tsx"
click node_web_api "https://github.com/siddhantsinghrao/build-with-agora/blob/main/web/lib/api.ts"
click node_server_api "https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js"
click node_rtc_tokens "https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js"
click node_agent_control "https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js"
click node_transcripts "https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js"
click node_learning_reports "https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js"
click node_call_control "https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js"
click node_telephony_config "https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js"
click node_voice_session "https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/components/VoiceSession.tsx"
click node_next_start "https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/app/api/agent/start/route.ts"
click node_next_stop "https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/app/api/agent/stop/route.ts"
click node_next_status "https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/app/api/agent/status/%5Bid%5D/route.ts"
click node_next_token "https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/app/api/token/route.ts"
click node_next_sessions "https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/app/api/sessions/route.ts"
click node_next_dashboard "https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/app/dashboard/page.tsx"
click node_agora_lib "https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/lib/agora.ts"
click node_session_store "https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/lib/sessions.ts"
click node_legacy_ui "https://github.com/siddhantsinghrao/build-with-agora/blob/main/client/talk.html"

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_web_student,node_web_teacher,node_lead_cards,node_web_api toneBlue
class node_server_api,node_rtc_tokens,node_agent_control,node_transcripts,node_learning_reports,node_call_control,node_telephony_config toneAmber
class node_voice_session,node_next_start,node_next_stop,node_next_status,node_next_token,node_next_sessions,node_next_dashboard,node_agora_lib,node_session_store toneMint
class node_legacy_ui toneRose
class node_student,node_teacher,node_agora,node_llm,node_vobiz,node_phone_student toneIndigo
```

## Components

### StudyCircle Main

- [Student Console](https://github.com/siddhantsinghrao/build-with-agora/blob/main/web/components/StudentConsole.tsx): `web/components/StudentConsole.tsx`
- [Teacher Dashboard](https://github.com/siddhantsinghrao/build-with-agora/blob/main/web/components/TeacherDashboard.tsx): `web/components/TeacherDashboard.tsx`
- [Learning Cards](https://github.com/siddhantsinghrao/build-with-agora/blob/main/web/components/LeadCard.tsx): `web/components/LeadCard.tsx`
- [Web API Client](https://github.com/siddhantsinghrao/build-with-agora/blob/main/web/lib/api.ts): `web/lib/api.ts`

### Session Backend

- [Session API](https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js): `server/server.js`
- [RTC Tokens](https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js): `server/server.js`
- [Agent Control](https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js): `server/server.js`
- [Transcript Capture](https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js): `server/server.js`
- [Learning Reports](https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js): `server/server.js`
- [Outbound Calls](https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js): `server/server.js`
- [Telephony Config](https://github.com/siddhantsinghrao/build-with-agora/blob/main/server/server.js): `server/server.js`

### Next Voice App

- [Voice Session](https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/components/VoiceSession.tsx): `voice-app-next/components/VoiceSession.tsx`
- [Start Agent Route](https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/app/api/agent/start/route.ts): `voice-app-next/app/api/agent/start/route.ts`
- [Stop Agent Route](https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/app/api/agent/stop/route.ts): `voice-app-next/app/api/agent/stop/route.ts`
- [Agent Status Route](https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/app/api/agent/status/%5Bid%5D/route.ts): `voice-app-next/app/api/agent/status/[id]/route.ts`
- [Token Route](https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/app/api/token/route.ts): `voice-app-next/app/api/token/route.ts`
- [Sessions Route](https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/app/api/sessions/route.ts): `voice-app-next/app/api/sessions/route.ts`
- [Session Dashboard](https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/app/dashboard/page.tsx): `voice-app-next/app/dashboard/page.tsx`
- [Agora Client Logic](https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/lib/agora.ts): `voice-app-next/lib/agora.ts`
- [Session Store](https://github.com/siddhantsinghrao/build-with-agora/blob/main/voice-app-next/lib/sessions.ts): `voice-app-next/lib/sessions.ts`

### Legacy Calling

- [Counsellor UI](https://github.com/siddhantsinghrao/build-with-agora/blob/main/client/talk.html): `client/talk.html`

### Other components

- **Student**
- **Teacher**
- **Agora Services**
- **LLM Service**
- **Vobiz**
- **Student Phone**

## Connections

- Student → Student Console: uses (evidence: `README.md`)
- Student Console → Session API: calls session APIs (evidence: `README.md`)
- Teacher → Teacher Dashboard: views reports (evidence: `README.md`)
- Teacher Dashboard → Session API: loads live data (evidence: `README.md`)
- Teacher Dashboard → Learning Cards: shows student cards (evidence: `README.md`)
- Session API → RTC Tokens: issues tokens (evidence: `server/server.js`)
- Session API → Agent Control: starts and stops (evidence: `server/server.js`)
- Agent Control → Agora Services: controls agents (evidence: `server/server.js`)
- Session API → Transcript Capture: captures turns (evidence: `server/server.js`)
- Transcript Capture → LLM Service: forwards prompts (evidence: `server/server.js`)
- Session API → Learning Reports: extracts reports (evidence: `server/server.js`)
- Learning Reports → LLM Service: requests extraction (evidence: `server/server.js`)
- Session API → Outbound Calls: starts calls (evidence: `README.md`)
- Outbound Calls → Agora Services: uses SIP gateway (evidence: `README.md`)
- Outbound Calls → Vobiz: checks credentials (evidence: `server/server.js`)
- Counsellor UI → Session API: configures calling (evidence: `README.md`)
- Counsellor UI → Student Phone: calls (evidence: `README.md`)
- Voice Session → Start Agent Route: starts agent (evidence: `voice-app-next/components/VoiceSession.tsx`)
- Voice Session → Stop Agent Route: stops agent (evidence: `voice-app-next/components/VoiceSession.tsx`)
- Start Agent Route → Agora Client Logic: starts agent (evidence: `voice-app-next/app/api/agent/start/route.ts`)
- Start Agent Route → Session Store: adds session (evidence: `voice-app-next/app/api/agent/start/route.ts`)
- Stop Agent Route → Agora Client Logic: stops agent (evidence: `voice-app-next/app/api/agent/stop/route.ts`)
- Stop Agent Route → Session Store: removes session (evidence: `voice-app-next/app/api/agent/stop/route.ts`)
- Agent Status Route → Agora Client Logic: queries agent (evidence: `voice-app-next/app/api/agent/status/[id]/route.ts`)
- Token Route → Agora Client Logic: mints token (evidence: `voice-app-next/app/api/token/route.ts`)
- Sessions Route → Session Store: lists sessions (evidence: `voice-app-next/app/api/sessions/route.ts`)
- Session Dashboard → Sessions Route: reads sessions
- Telephony Config → Vobiz: tests credentials (evidence: `server/server.js`)
