# randakamal/slotsaver architecture

> Architecture diagram of the GitHub repository randakamal/slotsaver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/randakamal/slotsaver
- Repository: https://github.com/randakamal/slotsaver

## Overview

SlotSaver recovers appointment cancellations by turning stored customer intent into ranked, policy-checked outreach and an atomic rebooking. The documented autonomous path filters eligibility, ranks candidates, calls them in sequence, applies escalating incentives, and recursively recovers a displaced booking. The web dashboard exposes calendar, recovery, patient, outreach, voice, and profile workflows; the backend also provides memory and configurable business rules. Edges reflect README-described behavior or SOURCE INDEX references; unsampled modules are represented at their exact paths, with uncertain wiring omitted.

Main entry points: [`apps/web/app/page.tsx`](https://github.com/randakamal/slotsaver/blob/main/apps/web/app/page.tsx) (Dashboard pages), [`apps/api/app/services/recovery_service.py`](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/recovery_service.py) (Plan state machine), [`apps/api/app/main.py`](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/main.py) (FastAPI entry), [`apps/api/app/services/outreach_service.py`](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/outreach_service.py) (Outreach decisions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Business dashboard"]
  node_dashboard["Dashboard pages<br/>[page.tsx]"]
  node_calendar["Appointment calendar"]
  node_recovery_ui["Recovery panel<br/>[RecoveryPanel.tsx]"]
  node_outreach_ui["Outreach queue<br/>[OutreachQueue.tsx]"]
  node_voice_ui["Voice widget<br/>[VoiceAgent.tsx]"]
  node_profile_ui["Profile settings"]
end

subgraph group_recovery["Recovery workflow"]
  node_api["FastAPI entry<br/>[main.py]"]
  node_recovery_routes["Recovery endpoints<br/>[recovery.py]"]
  node_scheduler["Recovery scheduler"]
  node_recovery_service["Plan state machine"]
  node_slot_recovery["Slot planning<br/>[slot_recovery.py]"]
end

subgraph group_decision["Intent and decisions"]
  node_ranker["Candidate ranking<br/>[ranker.py]"]
  node_nemotron["Nemotron client<br/>[client.py]"]
  node_preferences["Preference extraction"]
  node_memory["Patient memory<br/>[patient_memory.py]"]
end

subgraph group_operations["Scheduling and outreach"]
  node_appointment_service["Appointment service"]
  node_outreach_service["Outreach decisions"]
  node_calls["Outbound calls<br/>[call_service.py]"]
  node_business_service["Business profile service"]
end

subgraph group_state["Business state"]
  node_appointment_store[("Appointment records<br/>[appointment.py]")]
  node_profile_store[("Business profiles")]
  node_database[("SQL database<br/>[session.py]")]
end

node_owner(("Business owner"))
node_customer(("Customer"))
node_nemotron_service{{"NVIDIA Nemotron"}}
node_elevenlabs{{"ElevenLabs voice"}}
node_twilio{{"Twilio telephony"}}

node_owner -->|"uses"| node_dashboard
node_dashboard -->|"opens calendar"| node_calendar
node_dashboard -->|"views recovery"| node_recovery_ui
node_dashboard -->|"views outreach"| node_outreach_ui
node_dashboard -->|"opens voice"| node_voice_ui
node_owner -->|"configures"| node_profile_ui
node_calendar -.->|"requests appointments"| node_api
node_recovery_ui -->|"polls plans"| node_api
node_profile_ui -.->|"updates profile"| node_api
node_api -->|"registers routes"| node_recovery_routes
node_api -->|"starts scheduler"| node_scheduler
node_recovery_routes -->|"ranks candidates"| node_ranker
node_recovery_routes -->|"advances response"| node_recovery_service
node_scheduler -->|"resolves call outcomes"| node_recovery_service
node_scheduler -->|"plans cancellations"| node_slot_recovery
node_slot_recovery -->|"ranks eligible candidates"| node_ranker
node_ranker -->|"requests ranking"| node_nemotron
node_nemotron -->|"calls model API"| node_nemotron_service
node_slot_recovery -->|"checks and books slots"| node_appointment_service
node_recovery_service -->|"books accepted slot"| node_appointment_service
node_recovery_service -->|"advances candidate"| node_outreach_service
node_outreach_service -->|"places approved call"| node_calls
node_outreach_service -->|"decides outreach and offer"| node_nemotron
node_calls -->|"starts phone call"| node_elevenlabs
node_elevenlabs -->|"routes telephony"| node_twilio
node_customer -->|"shares scheduling intent"| node_voice_ui
node_voice_ui -.->|"submits intent"| node_preferences
node_preferences -.->|"extracts preferences"| node_nemotron
node_outreach_service -->|"reads patient history"| node_memory
node_business_service -->|"reads and updates"| node_profile_store
node_appointment_service -->|"reads and updates"| node_appointment_store
node_recovery_service -->|"persists plan state"| node_database
node_appointment_store -->|"stored in"| node_database
node_profile_store -->|"stored in"| node_database

click node_dashboard "https://github.com/randakamal/slotsaver/blob/main/apps/web/app/page.tsx"
click node_calendar "https://github.com/randakamal/slotsaver/blob/main/apps/web/components/appointments/AppointmentCalendar.tsx"
click node_recovery_ui "https://github.com/randakamal/slotsaver/blob/main/apps/web/components/recovery/RecoveryPanel.tsx"
click node_outreach_ui "https://github.com/randakamal/slotsaver/blob/main/apps/web/components/outreach/OutreachQueue.tsx"
click node_voice_ui "https://github.com/randakamal/slotsaver/blob/main/apps/web/components/calls/VoiceAgent.tsx"
click node_profile_ui "https://github.com/randakamal/slotsaver/blob/main/apps/web/components/settings/BusinessProfileSettings.tsx"
click node_api "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/main.py"
click node_recovery_routes "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/api/routes/recovery.py"
click node_scheduler "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/recovery_scheduler.py"
click node_recovery_service "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/recovery_service.py"
click node_slot_recovery "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/slot_recovery.py"
click node_ranker "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/agents/nemotron/ranker.py"
click node_nemotron "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/agents/nemotron/client.py"
click node_preferences "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/preference_service.py"
click node_memory "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/patient_memory.py"
click node_appointment_service "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/appointment_service.py"
click node_outreach_service "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/outreach_service.py"
click node_calls "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/call_service.py"
click node_business_service "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/business_profile_service.py"
click node_appointment_store "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/db/models/appointment.py"
click node_profile_store "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/db/models/business_profile.py"
click node_database "https://github.com/randakamal/slotsaver/blob/main/apps/api/app/db/session.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_dashboard,node_calendar,node_recovery_ui,node_outreach_ui,node_voice_ui,node_profile_ui toneBlue
class node_api,node_recovery_routes,node_scheduler,node_recovery_service,node_slot_recovery toneAmber
class node_ranker,node_nemotron,node_preferences,node_memory toneMint
class node_appointment_service,node_outreach_service,node_calls,node_business_service toneRose
class node_appointment_store,node_profile_store,node_database,node_owner,node_customer,node_nemotron_service,node_elevenlabs,node_twilio toneIndigo
```

## Components

### Business dashboard

- [Dashboard pages](https://github.com/randakamal/slotsaver/blob/main/apps/web/app/page.tsx): `apps/web/app/page.tsx`
- [Appointment calendar](https://github.com/randakamal/slotsaver/blob/main/apps/web/components/appointments/AppointmentCalendar.tsx): `apps/web/components/appointments/AppointmentCalendar.tsx`
- [Recovery panel](https://github.com/randakamal/slotsaver/blob/main/apps/web/components/recovery/RecoveryPanel.tsx): `apps/web/components/recovery/RecoveryPanel.tsx`
- [Outreach queue](https://github.com/randakamal/slotsaver/blob/main/apps/web/components/outreach/OutreachQueue.tsx): `apps/web/components/outreach/OutreachQueue.tsx`
- [Voice widget](https://github.com/randakamal/slotsaver/blob/main/apps/web/components/calls/VoiceAgent.tsx): `apps/web/components/calls/VoiceAgent.tsx`
- [Profile settings](https://github.com/randakamal/slotsaver/blob/main/apps/web/components/settings/BusinessProfileSettings.tsx): `apps/web/components/settings/BusinessProfileSettings.tsx`

### Recovery workflow

- [FastAPI entry](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Recovery endpoints](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/api/routes/recovery.py): `apps/api/app/api/routes/recovery.py`
- [Recovery scheduler](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/recovery_scheduler.py): `apps/api/app/services/recovery_scheduler.py`
- [Plan state machine](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/recovery_service.py): `apps/api/app/services/recovery_service.py`
- [Slot planning](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/slot_recovery.py): `apps/api/app/services/slot_recovery.py`

### Intent and decisions

- [Candidate ranking](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/agents/nemotron/ranker.py): `apps/api/app/agents/nemotron/ranker.py`
- [Nemotron client](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/agents/nemotron/client.py): `apps/api/app/agents/nemotron/client.py`
- [Preference extraction](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/preference_service.py): `apps/api/app/services/preference_service.py`
- [Patient memory](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/patient_memory.py): `apps/api/app/services/patient_memory.py`

### Scheduling and outreach

- [Appointment service](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/appointment_service.py): `apps/api/app/services/appointment_service.py`
- [Outreach decisions](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/outreach_service.py): `apps/api/app/services/outreach_service.py`
- [Outbound calls](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/call_service.py): `apps/api/app/services/call_service.py`
- [Business profile service](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/services/business_profile_service.py): `apps/api/app/services/business_profile_service.py`

### Business state

- [Appointment records](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/db/models/appointment.py): `apps/api/app/db/models/appointment.py`
- [Business profiles](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/db/models/business_profile.py): `apps/api/app/db/models/business_profile.py`
- [SQL database](https://github.com/randakamal/slotsaver/blob/main/apps/api/app/db/session.py): `apps/api/app/db/session.py`

### Other components

- **Business owner**
- **Customer**
- **NVIDIA Nemotron**
- **ElevenLabs voice**
- **Twilio telephony**

## Connections

- Business owner → Dashboard pages: uses
- Dashboard pages → Appointment calendar: opens calendar
- Dashboard pages → Recovery panel: views recovery
- Dashboard pages → Outreach queue: views outreach
- Dashboard pages → Voice widget: opens voice
- Business owner → Profile settings: configures
- Appointment calendar → FastAPI entry: requests appointments
- Recovery panel → FastAPI entry: polls plans
- Profile settings → FastAPI entry: updates profile
- FastAPI entry → Recovery endpoints: registers routes (evidence: `apps/api/app/main.py`)
- FastAPI entry → Recovery scheduler: starts scheduler (evidence: `apps/api/app/main.py`)
- Recovery endpoints → Candidate ranking: ranks candidates (evidence: `apps/api/app/api/routes/recovery.py`)
- Recovery endpoints → Plan state machine: advances response (evidence: `apps/api/app/api/routes/recovery.py`)
- Recovery scheduler → Plan state machine: resolves call outcomes
- Recovery scheduler → Slot planning: plans cancellations
- Slot planning → Candidate ranking: ranks eligible candidates
- Candidate ranking → Nemotron client: requests ranking
- Nemotron client → NVIDIA Nemotron: calls model API
- Slot planning → Appointment service: checks and books slots
- Plan state machine → Appointment service: books accepted slot (evidence: `apps/api/app/services/recovery_service.py`)
- Plan state machine → Outreach decisions: advances candidate (evidence: `apps/api/app/services/recovery_service.py`)
- Outreach decisions → Outbound calls: places approved call (evidence: `apps/api/app/services/outreach_service.py`)
- Outreach decisions → Nemotron client: decides outreach and offer (evidence: `apps/api/app/services/outreach_service.py`)
- Outbound calls → ElevenLabs voice: starts phone call
- ElevenLabs voice → Twilio telephony: routes telephony
- Customer → Voice widget: shares scheduling intent
- Voice widget → Preference extraction: submits intent
- Preference extraction → Nemotron client: extracts preferences
- Outreach decisions → Patient memory: reads patient history (evidence: `apps/api/app/services/outreach_service.py`)
- Business profile service → Business profiles: reads and updates (evidence: `apps/api/app/services/business_profile_service.py`)
- Appointment service → Appointment records: reads and updates (evidence: `apps/api/app/services/appointment_service.py`)
- Plan state machine → SQL database: persists plan state (evidence: `apps/api/app/services/recovery_service.py`)
- Appointment records → SQL database: stored in (evidence: `apps/api/app/db/models/appointment.py`)
- Business profiles → SQL database: stored in (evidence: `apps/api/app/db/models/business_profile.py`)
