# vaishali-dhanoa/hcai-project architecture

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

- Interactive diagram: https://gitdiagram.com/vaishali-dhanoa/hcai-project
- Repository: https://github.com/vaishali-dhanoa/hcai-project

## Overview

This repository is a multi-agent discussion playground with a browser UI and Python backend, plus a root-level simulation/CLI package. The primary user journey is to set up agents and a topic (optionally with a dataset), run discussion rounds, and follow live turns, visuals, and metrics. The backend implementation and frontend wiring are only partly excerpted; documented or indexed connections are shown where supported, and uncertain integration links are dashed.

Main entry points: [`frontend/src/App.tsx`](https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/App.tsx) (Playground UI), [`backend/app/simulation.py`](https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/simulation.py) (Round orchestration), [`backend/main.py`](https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/main.py) (API and sockets), [`app/simulation.py`](https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/simulation.py) (Root simulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser experience"]
  node_frontend_app["Playground UI<br/>[App.tsx]"]
  node_api_client["HTTP client<br/>[api.ts]"]
  node_ws_client["Live updates<br/>[ws.ts]"]
  node_arena["Discussion arena<br/>[ArenaTable.tsx]"]
  node_visual_card["Visual renderer<br/>[VisualCard.tsx]"]
  node_dashboard["Visual dashboard"]
  node_data_preview["Dataset preview"]
  node_tts["Speech playback<br/>[useTTS.ts]"]
end

subgraph group_service["Backend service"]
  node_http_api["API and sockets<br/>[main.py]"]
  node_session_state["Session state<br/>[state.py]"]
end

subgraph group_discussion["Discussion engine"]
  node_discussion_runner["Round orchestration<br/>[simulation.py]"]
  node_agent_factory["Agent creation<br/>[agent_factory.py]"]
  node_agent_models["Domain models<br/>[models.py]"]
  node_speaker_selection["Speaker selection<br/>[selection.py]"]
  node_safety["Civility controls<br/>[safety.py]"]
  node_metrics["Emergent metrics<br/>[metrics.py]"]
  node_llm["Language generation<br/>[llm.py]"]
end

subgraph group_data_visuals["Data and visuals"]
  node_dataset_parser["Dataset parsing<br/>[dataset.py]"]
  node_auto_visual["Visual generation<br/>[auto_visual.py]"]
  node_chart_compute["Chart computation<br/>[chart_compute.py]"]
end

subgraph group_legacy_runtime["Root simulation runtime"]
  node_cli["CLI entry<br/>[cli.py]"]
  node_legacy_sim["Root simulation<br/>[simulation.py]"]
  node_legacy_metrics["Root metrics<br/>[metrics.py]"]
  node_legacy_models["Root domain models<br/>[models.py]"]
  node_legacy_agents["Root agent factory<br/>[agent_factory.py]"]
  node_legacy_safety["Root civility controls<br/>[safety.py]"]
  node_legacy_selection["Root speaker selection<br/>[selection.py]"]
end

node_participant(("Participant"))

node_participant -->|"uses"| node_frontend_app
node_frontend_app -->|"requests actions"| node_api_client
node_frontend_app -->|"opens live feed"| node_ws_client
node_frontend_app -->|"renders arena"| node_arena
node_frontend_app -->|"renders dashboard"| node_dashboard
node_frontend_app -->|"renders preview"| node_data_preview
node_frontend_app -->|"renders visuals"| node_visual_card
node_arena -->|"renders visuals"| node_visual_card
node_dashboard -->|"renders visuals"| node_visual_card
node_frontend_app -->|"plays speech"| node_tts
node_tts -->|"requests audio"| node_api_client
node_api_client -.->|"sends API requests"| node_http_api
node_ws_client -.->|"receives events"| node_http_api
node_http_api -->|"reads and updates"| node_session_state
node_http_api -->|"creates agents"| node_agent_factory
node_http_api -->|"parses uploads"| node_dataset_parser
node_http_api -->|"runs rounds"| node_discussion_runner
node_discussion_runner -->|"selects speakers"| node_speaker_selection
node_discussion_runner -->|"checks civility"| node_safety
node_discussion_runner -->|"computes metrics"| node_metrics
node_discussion_runner -->|"generates discussion"| node_llm
node_discussion_runner -->|"generates visuals"| node_auto_visual
node_discussion_runner -->|"computes charts"| node_chart_compute
node_agent_factory -->|"builds agents"| node_agent_models
node_discussion_runner -->|"uses domain types"| node_agent_models
node_cli -->|"creates agents"| node_legacy_agents
node_cli -->|"runs simulation"| node_legacy_sim
node_legacy_sim -->|"selects speakers"| node_legacy_selection
node_legacy_sim -->|"checks civility"| node_legacy_safety
node_legacy_sim -->|"computes metrics"| node_legacy_metrics
node_legacy_sim -->|"uses domain types"| node_legacy_models
node_legacy_agents -->|"builds agents"| node_legacy_models

click node_frontend_app "https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/api.ts"
click node_ws_client "https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/ws.ts"
click node_arena "https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/components/ArenaTable.tsx"
click node_visual_card "https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/components/VisualCard.tsx"
click node_dashboard "https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/components/DashboardCanvas.tsx"
click node_data_preview "https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/components/DataPreviewTable.tsx"
click node_tts "https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/hooks/useTTS.ts"
click node_http_api "https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/main.py"
click node_session_state "https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/state.py"
click node_dataset_parser "https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/dataset.py"
click node_discussion_runner "https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/simulation.py"
click node_agent_factory "https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/agent_factory.py"
click node_agent_models "https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/models.py"
click node_speaker_selection "https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/selection.py"
click node_safety "https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/safety.py"
click node_metrics "https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/metrics.py"
click node_llm "https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/llm.py"
click node_auto_visual "https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/auto_visual.py"
click node_chart_compute "https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/chart_compute.py"
click node_cli "https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/cli.py"
click node_legacy_sim "https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/simulation.py"
click node_legacy_metrics "https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/metrics.py"
click node_legacy_models "https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/models.py"
click node_legacy_agents "https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/agent_factory.py"
click node_legacy_safety "https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/safety.py"
click node_legacy_selection "https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/selection.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_frontend_app,node_api_client,node_ws_client,node_arena,node_visual_card,node_dashboard,node_data_preview,node_tts toneBlue
class node_http_api,node_session_state toneAmber
class node_discussion_runner,node_agent_factory,node_agent_models,node_speaker_selection,node_safety,node_metrics,node_llm toneMint
class node_dataset_parser,node_auto_visual,node_chart_compute toneRose
class node_cli,node_legacy_sim,node_legacy_metrics,node_legacy_models,node_legacy_agents,node_legacy_safety,node_legacy_selection,node_participant toneIndigo
```

## Components

### Browser experience

- [Playground UI](https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [HTTP client](https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Live updates](https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/ws.ts): `frontend/src/ws.ts`
- [Discussion arena](https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/components/ArenaTable.tsx): `frontend/src/components/ArenaTable.tsx`
- [Visual renderer](https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/components/VisualCard.tsx): `frontend/src/components/VisualCard.tsx`
- [Visual dashboard](https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/components/DashboardCanvas.tsx): `frontend/src/components/DashboardCanvas.tsx`
- [Dataset preview](https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/components/DataPreviewTable.tsx): `frontend/src/components/DataPreviewTable.tsx`
- [Speech playback](https://github.com/vaishali-dhanoa/hcai-project/blob/main/frontend/src/hooks/useTTS.ts): `frontend/src/hooks/useTTS.ts`

### Backend service

- [API and sockets](https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/main.py): `backend/main.py`
- [Session state](https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/state.py): `backend/app/state.py`

### Discussion engine

- [Round orchestration](https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/simulation.py): `backend/app/simulation.py`
- [Agent creation](https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/agent_factory.py): `backend/app/agent_factory.py`
- [Domain models](https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/models.py): `backend/app/models.py`
- [Speaker selection](https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/selection.py): `backend/app/selection.py`
- [Civility controls](https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/safety.py): `backend/app/safety.py`
- [Emergent metrics](https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/metrics.py): `backend/app/metrics.py`
- [Language generation](https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/llm.py): `backend/app/llm.py`

### Data and visuals

- [Dataset parsing](https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/dataset.py): `backend/app/dataset.py`
- [Visual generation](https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/auto_visual.py): `backend/app/auto_visual.py`
- [Chart computation](https://github.com/vaishali-dhanoa/hcai-project/blob/main/backend/app/chart_compute.py): `backend/app/chart_compute.py`

### Root simulation runtime

- [CLI entry](https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/cli.py): `app/cli.py`
- [Root simulation](https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/simulation.py): `app/simulation.py`
- [Root metrics](https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/metrics.py): `app/metrics.py`
- [Root domain models](https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/models.py): `app/models.py`
- [Root agent factory](https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/agent_factory.py): `app/agent_factory.py`
- [Root civility controls](https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/safety.py): `app/safety.py`
- [Root speaker selection](https://github.com/vaishali-dhanoa/hcai-project/blob/main/app/selection.py): `app/selection.py`

### Other components

- **Participant**

## Connections

- Participant → Playground UI: uses
- Playground UI → HTTP client: requests actions (evidence: `frontend/src/App.tsx`)
- Playground UI → Live updates: opens live feed (evidence: `frontend/src/App.tsx`)
- Playground UI → Discussion arena: renders arena (evidence: `frontend/src/App.tsx`)
- Playground UI → Visual dashboard: renders dashboard (evidence: `frontend/src/App.tsx`)
- Playground UI → Dataset preview: renders preview (evidence: `frontend/src/App.tsx`)
- Playground UI → Visual renderer: renders visuals (evidence: `frontend/src/App.tsx`)
- Discussion arena → Visual renderer: renders visuals (evidence: `frontend/src/components/ArenaTable.tsx`)
- Visual dashboard → Visual renderer: renders visuals (evidence: `frontend/src/components/DashboardCanvas.tsx`)
- Playground UI → Speech playback: plays speech (evidence: `frontend/src/App.tsx`)
- Speech playback → HTTP client: requests audio (evidence: `frontend/src/hooks/useTTS.ts`)
- HTTP client → API and sockets: sends API requests
- Live updates → API and sockets: receives events
- API and sockets → Session state: reads and updates (evidence: `backend/main.py`)
- API and sockets → Agent creation: creates agents (evidence: `backend/main.py`)
- API and sockets → Dataset parsing: parses uploads (evidence: `backend/main.py`)
- API and sockets → Round orchestration: runs rounds (evidence: `backend/main.py`)
- Round orchestration → Speaker selection: selects speakers (evidence: `backend/app/simulation.py`)
- Round orchestration → Civility controls: checks civility (evidence: `backend/app/simulation.py`)
- Round orchestration → Emergent metrics: computes metrics (evidence: `backend/app/simulation.py`)
- Round orchestration → Language generation: generates discussion (evidence: `backend/app/simulation.py`)
- Round orchestration → Visual generation: generates visuals (evidence: `backend/app/simulation.py`)
- Round orchestration → Chart computation: computes charts (evidence: `backend/app/simulation.py`)
- Agent creation → Domain models: builds agents (evidence: `backend/app/agent_factory.py`)
- Round orchestration → Domain models: uses domain types (evidence: `backend/app/simulation.py`)
- CLI entry → Root agent factory: creates agents (evidence: `app/cli.py`)
- CLI entry → Root simulation: runs simulation (evidence: `app/cli.py`)
- Root simulation → Root speaker selection: selects speakers (evidence: `app/simulation.py`)
- Root simulation → Root civility controls: checks civility (evidence: `app/simulation.py`)
- Root simulation → Root metrics: computes metrics (evidence: `app/simulation.py`)
- Root simulation → Root domain models: uses domain types (evidence: `app/simulation.py`)
- Root agent factory → Root domain models: builds agents (evidence: `app/agent_factory.py`)
