{"id":49486073,"url":"https://github.com/glav/realtime-website","last_synced_at":"2026-05-01T01:30:52.433Z","repository":{"id":340715536,"uuid":"1166111243","full_name":"glav/realtime-website","owner":"glav","description":"test site for realtime voice interaction","archived":false,"fork":false,"pushed_at":"2026-02-26T06:01:20.000Z","size":468,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-26T10:59:45.556Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/glav.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-24T22:17:41.000Z","updated_at":"2026-02-24T22:17:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/glav/realtime-website","commit_stats":null,"previous_names":["glav/realtime-website"],"tags_count":null,"template":false,"template_full_name":"glav/template-python","purl":"pkg:github/glav/realtime-website","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glav%2Frealtime-website","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glav%2Frealtime-website/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glav%2Frealtime-website/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glav%2Frealtime-website/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glav","download_url":"https://codeload.github.com/glav/realtime-website/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glav%2Frealtime-website/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32482460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"ssl_error","status_checked_at":"2026-04-30T13:12:06.837Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-01T01:30:50.596Z","updated_at":"2026-05-01T01:30:52.419Z","avatar_url":"https://github.com/glav.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Azure OpenAI Realtime Chatbot\n\nA web application for real-time text chat with Azure OpenAI GPT models, using RBAC-based authentication.\n\n![React frontend chat interface connected via WebSocket to Python backend, which authenticates to Azure OpenAI Realtime API through Entra ID. The screenshot shows a real-time chat application with message history, user input field, connection status indicator, and responsive design for the web-based chatbot interface.](./docs/realtime-chat-site-screenshot.png)\n\n## How It Works\n\n```\n┌─────────────┐     WebSocket     ┌─────────────┐     WebSocket     ┌──────────────────┐\n│   Browser   │ ←──────────────→  │   Python    │ ←──────────────→  │  Azure OpenAI    │\n│  (React)    │                   │   Backend   │                   │  Realtime API    │\n└─────────────┘                   └─────────────┘                   └──────────────────┘\n                                        │\n                                        │ DefaultAzureCredential\n                                        │ (az login / Managed Identity)\n                                        ↓\n                                  ┌─────────────┐\n                                  │  Entra ID   │\n                                  └─────────────┘\n```\n\nThe **React frontend** provides a chat UI that connects via WebSocket to the **Python backend**. The backend acts as a secure proxy to the Azure OpenAI Realtime API, handling authentication using `DefaultAzureCredential`.\n\n## Documentation\n\n- **[Voice Communication Architecture](./docs/voice-communication-architecture.md)** - Detailed sequence diagram and component breakdown for real-time voice interaction\n- **[Azure OpenAI Realtime Chatbot Objective](./docs/azure-openai-realtime-chatbot.md)** - Project goals, requirements, and technical specifications\n- **[Azure AD Setup Guide](./docs/azure-ad-setup.md)** - Authentication and RBAC configuration\n\n## Prerequisites\n\n1. **Azure CLI** - Logged in with `az login`\n2. **Azure OpenAI Resource** - With a realtime model deployment (e.g., `gpt-4o-realtime-preview`)\n3. **RBAC Role Assignment** - User must have `Cognitive Services OpenAI User` role on the Azure OpenAI resource\n4. **uv** - Python dependency manager ([install guide](https://github.com/astral-sh/uv))\n5. **Node.js** - For the frontend (v18+)\n\n### Assigning the RBAC Role\n\n```bash\n# Get your user object ID\nUSER_ID=$(az ad signed-in-user show --query id -o tsv)\n\n# Get your Azure OpenAI resource ID (replace with your values)\nRESOURCE_GROUP=\"your-resource-group\"\nOPENAI_RESOURCE=\"your-openai-resource\"\nRESOURCE_ID=$(az cognitiveservices account show \\\n    --resource-group $RESOURCE_GROUP \\\n    --name $OPENAI_RESOURCE \\\n    --query id -o tsv)\n\n# Assign the Cognitive Services OpenAI User role\naz role assignment create \\\n    --assignee $USER_ID \\\n    --role \"Cognitive Services OpenAI User\" \\\n    --scope $RESOURCE_ID\n```\n\n## Quick Start\n\n### 1. Install dependencies\n\n```bash\n# Backend (Python)\nuv sync\n\n# Frontend (Node.js)\ncd web \u0026\u0026 npm install\n```\n\n### 2. Configure environment\n\nCreate a `.env` file in the repository root:\n\n```bash\n# .env (in repo root)\nAZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com\nAZURE_OPENAI_DEPLOYMENT=gpt-4o-realtime-preview\n```\n\nThe frontend uses the Vite dev server proxy to communicate with the backend, so no separate frontend configuration is required for development.\n\n### 3. Authenticate with Azure\n\n```bash\naz login\n```\n\n### 4. Start the servers\n\n**Option A: Two terminals**\n\n```bash\n# Terminal 1: Backend (port 8000)\nuv run python src/server.py\n\n# Terminal 2: Frontend (port 5173)\ncd web \u0026\u0026 npm run dev\n```\n\n**Option B: Single terminal (background backend)**\n\n```bash\nuv run python src/server.py \u0026\ncd web \u0026\u0026 npm run dev\n```\n\n### 5. Open the app\n\nNavigate to http://localhost:5173\n\nThe UI will show a green \"Backend ready\" indicator when everything is working. If you see auth errors, ensure you've run `az login` and have the RBAC role assigned.\n\n## Configuration Reference\n\n| Variable | Location | Description |\n|----------|----------|-------------|\n| `AZURE_OPENAI_ENDPOINT` | `.env` (root) | Your Azure OpenAI resource URL |\n| `AZURE_OPENAI_DEPLOYMENT` | `.env` (root) | The realtime model deployment name |\n| `PORT` | `.env` (root) | Backend port (default: 8000) |\n\n## Backend API\n\nThe Python backend (`src/server.py`) exposes:\n\n| Endpoint | Protocol | Description |\n|----------|----------|-------------|\n| `/api/health` | HTTP GET | Health check - returns JSON with connection status and credential validity |\n| `/api/realtime` | WebSocket | Proxy to Azure OpenAI Realtime API - forwards messages bidirectionally |\n\nAuthentication uses `DefaultAzureCredential`, which automatically picks up:\n- `az login` credentials (local development)\n- Managed Identity (Azure deployments)\n- Environment variables, VS Code credentials, etc.\n\n## Frontend\n\nThe React frontend (`web/`) provides:\n- Chat interface with message history\n- Real-time WebSocket connection to the backend\n- Connection status indicator\n- Error handling and helpful messages\n\nThe Vite dev server proxies `/api/*` requests to `http://localhost:8000`, so the frontend and backend work together seamlessly.\n\n## Project Structure\n\n```\n├── src/\n│   ├── server.py          # Python backend - WebSocket proxy to Azure OpenAI\n│   └── load_env.py        # .env file discovery and loading\n├── web/\n│   ├── src/\n│   │   ├── App.tsx        # Main React component\n│   │   ├── services/\n│   │   │   └── realtimeService.ts  # WebSocket client\n│   │   └── components/\n│   │       └── Chat/      # Chat UI components\n│   ├── vite.config.ts     # Vite config with API proxy\n│   └── package.json       # Frontend dependencies\n├── pyproject.toml         # Python dependencies (managed by uv)\n├── .env                   # Backend configuration (gitignored)\n└── README.md\n```\n\n## Troubleshooting\n\n### \"Credential not valid\" error\n- Run `az login` to authenticate\n- Verify you have the `Cognitive Services OpenAI User` role assigned to your Azure user\n\n### \"Backend unreachable\" in the UI\n- Ensure the backend is running: `uv run python src/server.py`\n- Check the backend console for errors\n\n### WebSocket connection fails\n- Verify `AZURE_OPENAI_ENDPOINT` and `AZURE_OPENAI_DEPLOYMENT` are set correctly in `.env`\n- Check the backend logs for detailed error messages\n\n---\n\n## Development Tools\n\n### Linting and Formatting (Python)\n\n```bash\nuv sync --group dev\nuv run ruff check .\nuv run ruff format .\n```\n\n### Frontend Testing\n\n```bash\ncd web\nnpm run test           # Unit tests\nnpm run test:e2e       # Playwright E2E tests\nnpm run lint           # ESLint\n```\n\n---\n\n## AI-Assisted Workflow\n\nThis repository includes GitHub Copilot integration with reusable prompt commands in `.agent/`:\n\n- **`.agent/commands/`** - Slash commands for common tasks (e.g., `/setup:agents-md-creation`)\n- **`.agent/standards/`** - Templates for ADRs, feature specs, task plans\n- **`.agent/instructions/`** - Coding guidelines for different file types\n\n### Spec-Driven Development (SDD)\n\nA structured 9-step workflow for feature development with quality gates. See `.agent/commands/sdd/README.md` for full documentation.\n\nThe devcontainer includes GitHub Copilot CLI (`copilot`) and Teambot for AI-assisted workflows.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglav%2Frealtime-website","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglav%2Frealtime-website","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglav%2Frealtime-website/lists"}