# ijunaidkhan/medical-ai-frontdesk architecture

> Architecture diagram of the GitHub repository ijunaidkhan/medical-ai-frontdesk, 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/ijunaidkhan/medical-ai-frontdesk
- Repository: https://github.com/ijunaidkhan/medical-ai-frontdesk

## Overview

AI Medical Front Desk is a multi-tenant receptionist platform with an Angular practice-management app and NestJS API. Staff sign in, manage practice and approved knowledge, configure the receptionist, and test it in chat; the API also supports conversation review, tasks, audit, and phone-number administration. PostgreSQL enforces tenant isolation. The graph follows documented routes and sampled/indexed references; some subsystem internals and web-to-API client calls were not excerpted, so those links are omitted.

Main entry points: [`apps/api/src/agent/agent.service.ts`](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/agent/agent.service.ts) (Test receptionist), [`apps/web/src/app/app.routes.ts`](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/web/src/app/app.routes.ts) (Practice console), [`apps/web/src/app/features/knowledge/knowledge.page.ts`](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/web/src/app/features/knowledge/knowledge.page.ts) (Knowledge editor), [`apps/api/src/knowledge/knowledge.service.ts`](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/knowledge/knowledge.service.ts) (Knowledge management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Practice web app"]
  node_webapp["Practice console<br/>[app.routes.ts]"]
  node_web_auth["Session state<br/>[auth.service.ts]"]
  node_knowledge_ui["Knowledge editor<br/>[knowledge.page.ts]"]
  node_ai_ui["AI settings"]
  node_chat_ui["Test chat<br/>[test-chat.page.ts]"]
  node_activity_ui["Activity review<br/>[activity.page.ts]"]
end

subgraph group_api["API and receptionist"]
  node_auth_api["Authentication<br/>[auth.service.ts]"]
  node_knowledge["Knowledge management"]
  node_ai_config["Receptionist setup<br/>[ai.service.ts]"]
  node_agent["Test receptionist<br/>[agent.service.ts]"]
  node_model["Language model<br/>[language-model.ts]"]
  node_safety["Safety controls"]
  node_conversations["Conversation review"]
  node_tasks["Callback tasks<br/>[tasks.service.ts]"]
  node_members["Team access<br/>[members.service.ts]"]
  node_practice["Practice profile"]
  node_audit["Audit trail<br/>[audit.service.ts]"]
  node_phones["Phone administration"]
end

subgraph group_data["Tenant data"]
  node_database[("PostgreSQL<br/>[database.module.ts]")]
end

subgraph group_integrations["External systems"]
  node_twilio["Twilio"]
  node_llm["Model provider"]
end

node_staff(("Practice staff"))

node_staff -->|"uses"| node_webapp
node_webapp -->|"restores session"| node_web_auth
node_webapp -->|"routes to"| node_knowledge_ui
node_webapp -->|"routes to"| node_ai_ui
node_webapp -->|"routes to"| node_chat_ui
node_webapp -->|"routes to"| node_activity_ui
node_staff -->|"signs in"| node_auth_api
node_knowledge_ui -.->|"manages knowledge"| node_knowledge
node_ai_ui -.->|"configures"| node_ai_config
node_chat_ui -.->|"tests receptionist"| node_agent
node_agent -->|"uses model"| node_model
node_agent -->|"applies safety"| node_safety
node_agent -->|"loads settings"| node_ai_config
node_agent -->|"creates tasks"| node_tasks
node_agent -->|"stores conversations"| node_database
node_agent -.->|"requests completions"| node_llm
node_knowledge_ui -->|"requests service"| node_knowledge
node_activity_ui -.->|"reviews calls"| node_conversations
node_staff -->|"manages callbacks"| node_tasks
node_staff -->|"manages team"| node_members
node_staff -->|"updates practice"| node_practice
node_staff -->|"reviews activity"| node_audit
node_staff -->|"connects numbers"| node_phones
node_phones -.->|"configures numbers"| node_twilio
node_auth_api -->|"reads sessions"| node_database
node_knowledge -.->|"stores approved sources"| node_database

click node_webapp "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/web/src/app/app.routes.ts"
click node_web_auth "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/web/src/app/core/auth/auth.service.ts"
click node_knowledge_ui "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/web/src/app/features/knowledge/knowledge.page.ts"
click node_ai_ui "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/web/src/app/features/ai-settings/ai-settings.page.ts"
click node_chat_ui "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/web/src/app/features/test-chat/test-chat.page.ts"
click node_activity_ui "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/web/src/app/features/activity/activity.page.ts"
click node_auth_api "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/auth/auth.service.ts"
click node_knowledge "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/knowledge/knowledge.service.ts"
click node_ai_config "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/ai/ai.service.ts"
click node_agent "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/agent/agent.service.ts"
click node_model "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/agent/model/language-model.ts"
click node_safety "https://github.com/ijunaidkhan/medical-ai-frontdesk/tree/main/apps/api/src/agent/safety"
click node_conversations "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/agent/conversations.service.ts"
click node_tasks "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/tasks/tasks.service.ts"
click node_members "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/members/members.service.ts"
click node_practice "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/practices/practices.service.ts"
click node_audit "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/audit/audit.service.ts"
click node_phones "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/voice/phone-numbers.service.ts"
click node_database "https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/database/database.module.ts"

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_webapp,node_web_auth,node_knowledge_ui,node_ai_ui,node_chat_ui,node_activity_ui toneBlue
class node_auth_api,node_knowledge,node_ai_config,node_agent,node_model,node_safety,node_conversations,node_tasks,node_members,node_practice,node_audit,node_phones toneAmber
class node_database toneMint
class node_twilio,node_llm toneRose
class node_staff toneIndigo
```

## Components

### Practice web app

- [Practice console](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/web/src/app/app.routes.ts): `apps/web/src/app/app.routes.ts`
- [Session state](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/web/src/app/core/auth/auth.service.ts): `apps/web/src/app/core/auth/auth.service.ts`
- [Knowledge editor](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/web/src/app/features/knowledge/knowledge.page.ts): `apps/web/src/app/features/knowledge/knowledge.page.ts`
- [AI settings](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/web/src/app/features/ai-settings/ai-settings.page.ts): `apps/web/src/app/features/ai-settings/ai-settings.page.ts`
- [Test chat](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/web/src/app/features/test-chat/test-chat.page.ts): `apps/web/src/app/features/test-chat/test-chat.page.ts`
- [Activity review](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/web/src/app/features/activity/activity.page.ts): `apps/web/src/app/features/activity/activity.page.ts`

### API and receptionist

- [Authentication](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/auth/auth.service.ts): `apps/api/src/auth/auth.service.ts`
- [Knowledge management](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/knowledge/knowledge.service.ts): `apps/api/src/knowledge/knowledge.service.ts`
- [Receptionist setup](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/ai/ai.service.ts): `apps/api/src/ai/ai.service.ts`
- [Test receptionist](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/agent/agent.service.ts): `apps/api/src/agent/agent.service.ts`
- [Language model](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/agent/model/language-model.ts): `apps/api/src/agent/model/language-model.ts`
- [Safety controls](https://github.com/ijunaidkhan/medical-ai-frontdesk/tree/main/apps/api/src/agent/safety): `apps/api/src/agent/safety`
- [Conversation review](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/agent/conversations.service.ts): `apps/api/src/agent/conversations.service.ts`
- [Callback tasks](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/tasks/tasks.service.ts): `apps/api/src/tasks/tasks.service.ts`
- [Team access](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/members/members.service.ts): `apps/api/src/members/members.service.ts`
- [Practice profile](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/practices/practices.service.ts): `apps/api/src/practices/practices.service.ts`
- [Audit trail](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/audit/audit.service.ts): `apps/api/src/audit/audit.service.ts`
- [Phone administration](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/voice/phone-numbers.service.ts): `apps/api/src/voice/phone-numbers.service.ts`

### Tenant data

- [PostgreSQL](https://github.com/ijunaidkhan/medical-ai-frontdesk/blob/main/apps/api/src/database/database.module.ts): `apps/api/src/database/database.module.ts`

### External systems

- **Twilio**
- **Model provider**

### Other components

- **Practice staff**

## Connections

- Practice staff → Practice console: uses (evidence: `README.md`)
- Practice console → Session state: restores session (evidence: `apps/web/src/app/app.config.ts`)
- Practice console → Knowledge editor: routes to (evidence: `apps/web/src/app/app.routes.ts`)
- Practice console → AI settings: routes to (evidence: `apps/web/src/app/app.routes.ts`)
- Practice console → Test chat: routes to (evidence: `apps/web/src/app/app.routes.ts`)
- Practice console → Activity review: routes to (evidence: `apps/web/src/app/app.routes.ts`)
- Practice staff → Authentication: signs in (evidence: `README.md`)
- Knowledge editor → Knowledge management: manages knowledge
- AI settings → Receptionist setup: configures
- Test chat → Test receptionist: tests receptionist
- Test receptionist → Language model: uses model (evidence: `apps/api/src/agent/agent.service.ts`)
- Test receptionist → Safety controls: applies safety (evidence: `apps/api/src/agent/agent.service.ts`)
- Test receptionist → Receptionist setup: loads settings (evidence: `apps/api/src/agent/agent.service.ts`)
- Test receptionist → Callback tasks: creates tasks (evidence: `apps/api/src/agent/agent.service.ts`)
- Test receptionist → PostgreSQL: stores conversations (evidence: `apps/api/src/agent/agent.service.ts`)
- Test receptionist → Model provider: requests completions
- Knowledge editor → Knowledge management: requests service
- Activity review → Conversation review: reviews calls
- Practice staff → Callback tasks: manages callbacks (evidence: `README.md`)
- Practice staff → Team access: manages team (evidence: `README.md`)
- Practice staff → Practice profile: updates practice (evidence: `README.md`)
- Practice staff → Audit trail: reviews activity (evidence: `README.md`)
- Practice staff → Phone administration: connects numbers (evidence: `README.md`)
- Phone administration → Twilio: configures numbers
- Authentication → PostgreSQL: reads sessions (evidence: `apps/api/src/auth/auth.service.ts`)
- Knowledge management → PostgreSQL: stores approved sources
