2:I[7012,["4765","static/chunks/4765-f5afdf8061f456f3.js","9856","static/chunks/9856-3b185291364d9bef.js","6687","static/chunks/app/docs/%5B...slug%5D/page-e07536548216bee4.js"],"MarkdownRenderer"]
4:I[9856,["4765","static/chunks/4765-f5afdf8061f456f3.js","9856","static/chunks/9856-3b185291364d9bef.js","6687","static/chunks/app/docs/%5B...slug%5D/page-e07536548216bee4.js"],""]
5:I[4126,[],""]
7:I[9630,[],""]
8:I[4278,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"HeadingProvider"]
9:I[1476,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"Header"]
a:I[3167,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"Sidebar"]
b:I[7409,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"PageFrame"]
3:T1bb9,
# AI Agent Quick Start

**Last Updated:** 2025-12-01

This guide helps AI coding assistants (Claude, GPT, Copilot, etc.) quickly understand and work on VoiceAssist.

---

## Project Overview

**VoiceAssist** is a HIPAA-compliant medical AI assistant platform with:

- **Voice Mode:** Thinker-Talker pipeline (Deepgram STT → GPT-4o → ElevenLabs TTS)
- **Text Mode:** Streaming chat with citations
- **Knowledge Base:** Medical textbooks, guidelines, literature
- **Admin Panel:** User management, analytics, KB administration

---

## Key Directories

```
/home/asimo/VoiceAssist/
├── apps/
│   ├── web-app/              # React frontend (main app)
│   ├── admin-panel/          # Admin dashboard
│   └── docs-site/            # Next.js documentation site
├── packages/
│   ├── api-client/           # Type-safe API client
│   ├── types/                # Shared TypeScript types
│   ├── ui/                   # Shared UI components
│   └── utils/                # Shared utilities
├── services/
│   └── api-gateway/          # FastAPI backend
│       └── app/
│           ├── api/          # REST endpoints
│           ├── services/     # Business logic (Thinker, Talker, etc.)
│           └── models/       # Database models
└── docs/                     # Documentation source
```

---

## Critical Files

### Voice Pipeline (Thinker-Talker)

| File                                                                    | Purpose               |
| ----------------------------------------------------------------------- | --------------------- |
| `services/api-gateway/app/services/thinker_service.py`                  | LLM orchestration     |
| `services/api-gateway/app/services/talker_service.py`                   | TTS synthesis         |
| `services/api-gateway/app/services/thinker_talker_websocket_handler.py` | WebSocket handling    |
| `services/api-gateway/app/services/sentence_chunker.py`                 | Text chunking for TTS |
| `apps/web-app/src/hooks/useThinkerTalkerSession.ts`                     | Frontend voice hook   |

### API Endpoints

| File                                            | Purpose                  |
| ----------------------------------------------- | ------------------------ |
| `services/api-gateway/app/api/conversations.py` | Chat CRUD                |
| `services/api-gateway/app/api/voice.py`         | Voice session management |
| `services/api-gateway/app/api/realtime.py`      | Chat WebSocket           |
| `services/api-gateway/app/api/auth.py`          | Authentication           |

### Frontend Components

| File                                         | Purpose               |
| -------------------------------------------- | --------------------- |
| `apps/web-app/src/components/ChatView.tsx`   | Main chat interface   |
| `apps/web-app/src/components/VoicePanel.tsx` | Voice mode UI         |
| `apps/web-app/src/hooks/useChatSession.ts`   | Chat state management |

---

## Documentation Index

### Architecture

- [THINKER_TALKER_PIPELINE.md](../THINKER_TALKER_PIPELINE.md) - Voice pipeline architecture
- [UNIFIED_ARCHITECTURE.md](../UNIFIED_ARCHITECTURE.md) - System overview
- [BACKEND_ARCHITECTURE.md](../BACKEND_ARCHITECTURE.md) - API Gateway design
- [FRONTEND_ARCHITECTURE.md](../FRONTEND_ARCHITECTURE.md) - React app structure

### API Reference

- [API_REFERENCE.md](../API_REFERENCE.md) - Endpoint overview
- [api-reference/rest-api.md](../api-reference/rest-api.md) - Complete REST docs
- [api-reference/voice-pipeline-ws.md](../api-reference/voice-pipeline-ws.md) - Voice WebSocket protocol
- [WEBSOCKET_PROTOCOL.md](../WEBSOCKET_PROTOCOL.md) - Chat WebSocket protocol

### Services

- [services/thinker-service.md](../services/thinker-service.md) - ThinkerService API
- [services/talker-service.md](../services/talker-service.md) - TalkerService API

### Data

- [DATA_MODEL.md](../DATA_MODEL.md) - Database schema
- [CONFIGURATION_REFERENCE.md](../CONFIGURATION_REFERENCE.md) - Environment variables

---

## Machine-Readable Endpoints

The docs site provides JSON endpoints for programmatic access:

| Endpoint                 | Description                      |
| ------------------------ | -------------------------------- |
| `GET /agent/index.json`  | Documentation system metadata    |
| `GET /agent/docs.json`   | Full document list with metadata |
| `GET /search-index.json` | Full-text search index           |

**Base URL:** `https://assistdocs.asimo.io`

See [Agent API Reference](../ai/AGENT_API_REFERENCE.md) for details.

---

## Common Tasks

### Adding a New API Endpoint

1. Create route in `services/api-gateway/app/api/<module>.py`
2. Add schema in `services/api-gateway/app/schemas/<module>.py`
3. Register in `services/api-gateway/app/main.py`
4. Add TypeScript types in `packages/types/src/`
5. Update API client in `packages/api-client/src/`

### Adding a Frontend Feature

1. Create component in `apps/web-app/src/components/`
2. Add hooks in `apps/web-app/src/hooks/`
3. Use shared UI from `packages/ui/`
4. Use API client from `packages/api-client/`

### Modifying Voice Pipeline

1. ThinkerService changes: `thinker_service.py`
2. TalkerService changes: `talker_service.py`
3. WebSocket protocol: `thinker_talker_websocket_handler.py`
4. Frontend hooks: `useThinkerTalkerSession.ts`

---

## Code Patterns

### Backend (Python/FastAPI)

```python
# Typical endpoint structure
@router.post("/conversations/{id}/messages")
async def create_message(
    id: UUID,
    request: CreateMessageRequest,
    user: User = Depends(get_current_user),
    db: Session = Depends(get_db)
) -> MessageResponse:
    # Business logic
    return MessageResponse(...)
```

### Frontend (React/TypeScript)

```typescript
// Typical hook usage
const { messages, sendMessage, isLoading } = useChatSession(conversationId);

// Voice mode
const { startListening, stopListening, isRecording } = useThinkerTalkerSession({
  onTranscript: (text) => console.log(text),
  onAudio: (audio) => playAudio(audio),
});
```

---

## Testing

```bash
# Backend tests
cd services/api-gateway
pytest tests/ -v

# Frontend tests
pnpm test

# Type checking
pnpm typecheck

# Linting
pnpm lint
```

---

## Environment Setup

Required API keys (in `.env`):

```bash
OPENAI_API_KEY=sk-...          # GPT-4o for Thinker
DEEPGRAM_API_KEY=...           # Speech-to-text
ELEVENLABS_API_KEY=...         # Text-to-speech
DATABASE_URL=postgresql://...   # PostgreSQL
REDIS_URL=redis://...          # Cache
```

---

## Quick References

- **OpenAPI Spec:** `http://localhost:8000/openapi.json`
- **Swagger UI:** `http://localhost:8000/docs`
- **Health Check:** `http://localhost:8000/health`
- **Docs Site:** `https://assistdocs.asimo.io`

---

## Related Documentation

- [Agent Onboarding](../ai/AGENT_ONBOARDING.md) - Detailed onboarding guide
- [Agent Task Index](../ai/AGENT_TASK_INDEX.md) - Common tasks and relevant docs
- [Claude Execution Guide](../CLAUDE_EXECUTION_GUIDE.md) - Claude-specific guidelines
6:["slug","start/ai-agents","c"]
0:["X7oMT3VrOffzp0qvbeOas",[[["",{"children":["docs",{"children":[["slug","start/ai-agents","c"],{"children":["__PAGE__?{\"slug\":[\"start\",\"ai-agents\"]}",{}]}]}]},"$undefined","$undefined",true],["",{"children":["docs",{"children":[["slug","start/ai-agents","c"],{"children":["__PAGE__",{},[["$L1",["$","div",null,{"children":[["$","div",null,{"className":"mb-6 flex items-center justify-between gap-4","children":[["$","div",null,{"children":[["$","p",null,{"className":"text-sm text-gray-500 dark:text-gray-400","children":"Docs / Raw"}],["$","h1",null,{"className":"text-3xl font-bold text-gray-900 dark:text-white","children":"AI Agent Quick Start"}],["$","p",null,{"className":"text-sm text-gray-600 dark:text-gray-400","children":["Sourced from"," ",["$","code",null,{"className":"font-mono text-xs","children":["docs/","start/ai-agents.md"]}]]}]]}],["$","a",null,{"href":"https://github.com/mohammednazmy/VoiceAssist/edit/main/docs/start/ai-agents.md","target":"_blank","rel":"noreferrer","className":"inline-flex items-center gap-2 rounded-md border border-gray-200 dark:border-gray-700 px-3 py-1.5 text-sm text-gray-700 dark:text-gray-200 hover:border-primary-500 dark:hover:border-primary-400 hover:text-primary-700 dark:hover:text-primary-300","children":"Edit on GitHub"}]]}],["$","div",null,{"className":"rounded-lg border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 p-6","children":["$","$L2",null,{"content":"$3"}]}],["$","div",null,{"className":"mt-6 flex flex-wrap gap-2 text-sm","children":[["$","$L4",null,{"href":"/reference/all-docs","className":"inline-flex items-center gap-1 rounded-md bg-gray-100 px-3 py-1 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700","children":"← All documentation"}],["$","$L4",null,{"href":"/","className":"inline-flex items-center gap-1 rounded-md bg-gray-100 px-3 py-1 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700","children":"Home"}]]}]]}],null],null],null]},[null,["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children","docs","children","$6","children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","notFoundStyles":"$undefined"}]],null]},[null,["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children","docs","children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","notFoundStyles":"$undefined"}]],null]},[[[["$","link","0",{"rel":"stylesheet","href":"/_next/static/css/7f586cdbbaa33ff7.css","precedence":"next","crossOrigin":"$undefined"}]],["$","html",null,{"lang":"en","className":"h-full","children":["$","body",null,{"className":"__className_f367f3 h-full bg-white dark:bg-gray-900","children":[["$","a",null,{"href":"#main-content","className":"skip-to-content","children":"Skip to main content"}],["$","$L8",null,{"children":[["$","$L9",null,{}],["$","$La",null,{}],["$","main",null,{"id":"main-content","className":"lg:pl-64","role":"main","aria-label":"Documentation content","children":["$","$Lb",null,{"children":["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":{"fontFamily":"system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"","height":"100vh","textAlign":"center","display":"flex","flexDirection":"column","alignItems":"center","justifyContent":"center"},"children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":{"display":"inline-block","margin":"0 20px 0 0","padding":"0 23px 0 0","fontSize":24,"fontWeight":500,"verticalAlign":"top","lineHeight":"49px"},"children":"404"}],["$","div",null,{"style":{"display":"inline-block"},"children":["$","h2",null,{"style":{"fontSize":14,"fontWeight":400,"lineHeight":"49px","margin":0},"children":"This page could not be found."}]}]]}]}]],"notFoundStyles":[]}]}]}]]}]]}]}]],null],null],["$Lc",null]]]]
c:[["$","meta","0",{"name":"viewport","content":"width=device-width, initial-scale=1"}],["$","meta","1",{"charSet":"utf-8"}],["$","title","2",{"children":"AI Agent Quick Start | Docs | VoiceAssist Docs"}],["$","meta","3",{"name":"description","content":"Quick start guide for AI coding assistants working on VoiceAssist."}],["$","meta","4",{"name":"keywords","content":"VoiceAssist,documentation,medical AI,voice assistant,healthcare,HIPAA,API"}],["$","meta","5",{"name":"robots","content":"index, follow"}],["$","meta","6",{"name":"googlebot","content":"index, follow"}],["$","link","7",{"rel":"canonical","href":"https://assistdocs.asimo.io"}],["$","meta","8",{"property":"og:title","content":"VoiceAssist Documentation"}],["$","meta","9",{"property":"og:description","content":"Comprehensive documentation for VoiceAssist - Enterprise Medical AI Assistant"}],["$","meta","10",{"property":"og:url","content":"https://assistdocs.asimo.io"}],["$","meta","11",{"property":"og:site_name","content":"VoiceAssist Docs"}],["$","meta","12",{"property":"og:type","content":"website"}],["$","meta","13",{"name":"twitter:card","content":"summary"}],["$","meta","14",{"name":"twitter:title","content":"VoiceAssist Documentation"}],["$","meta","15",{"name":"twitter:description","content":"Comprehensive documentation for VoiceAssist - Enterprise Medical AI Assistant"}],["$","meta","16",{"name":"next-size-adjust"}]]
1:null