System Requirements Document (SRD)

Project Name: raven-clinic

1. Introduction

The raven-clinic project is designed to provide a seamless, AI-powered receptionist system for small clinics. The system will handle both chat and voice interactions, enabling patients to book, reschedule, or cancel appointments, inquire about clinic details, and receive personalized assistance. The focus is on simplicity, speed, and user-friendliness, ensuring that even non-technical clinic staff can manage the system with ease.

This document outlines the system requirements, features, and design principles to ensure the successful implementation of the raven-clinic AI receptionist.

2. System Overview

The raven-clinic system will act as a virtual receptionist, capable of interacting with patients via chat or voice. It will guide users through a structured yet flexible flow, starting with a greeting, language selection, and open-ended input handling. The system will prioritize patient-centric features such as appointment booking, rescheduling, and cancellations, while also addressing general inquiries like clinic timings, doctor availability, and location.

Key highlights of the system include:

• Support for both English and Hindi languages.
• Personalized greetings for returning patients when data is available.
• Polite fallback handling for unsupported languages or unclear inputs.
• Lightweight and fast operation, tailored for small clinics.

The system will ensure a professional and human-like interaction experience, enhancing patient satisfaction and clinic efficiency.

3. Functional Requirements

Core Features

• As a Patient, I should be able to interact with the system via chat or voice.
• As a Patient, I should be greeted politely and asked to select my preferred language (English or Hindi).
• As a Patient, I should be able to make open-ended requests without being restricted to a fixed menu.
• As a Patient, I should be able to:
  • Book an appointment by providing my name, doctor (if known), date, and time.
  • Cancel an appointment by providing my name and appointment details.
  • Reschedule an appointment by providing existing details and new date/time.
  • Ask general questions about clinic timings, doctor availability, and location.
• As a Patient, I should receive a confirmation before any appointment action is finalized.
• As a Patient, I should be greeted by name if I am a returning user and my data is available.
• As a Patient, I should receive a polite fallback message if I select an unsupported language or provide unclear input.
• As a Patient, I should receive a polite closing message at the end of every interaction.

Behavioral Rules

• The system must always confirm important actions (e.g., appointment bookings, cancellations).
• The system must handle unsupported languages by asking the user to choose between English or Hindi.
• The system must handle unclear input by politely asking the user to repeat.
• The system must keep responses short, polite, and human-like.

4. User Personas

1. Patient

• Primary User: Patients interacting with the clinic for appointments or inquiries.
• Needs: Simple and fast interaction, support for both chat and voice, and language options (English/Hindi).
• Behavior: May provide open-ended requests or unclear input; expects polite and human-like responses.

2. Clinic Staff (Optional Future Support)

• Secondary User: Clinic staff managing appointments or checking schedules.
• Needs: Quick access to appointment details and schedules.
• Behavior: Minimal interaction; primarily uses the system for operational tasks.

5. Visuals Colors and Theme

Unique Color Palette for raven-clinic

• Background: #F4F9F9 (Soft Mint Green)
• Surface: #FFFFFF (Pure White)
• Text: #333333 (Deep Charcoal Gray)
• Accent: #007BFF (Vivid Blue for highlights and buttons)
• Muted Tones: #A6A6A6 (Neutral Gray for secondary text and placeholders)

This palette reflects a clean, professional, and calming aesthetic suitable for a healthcare setting.

6. Signature Design Concept

Interactive Floating Clinic Reception Desk

The homepage will feature a 3D floating reception desk in the center of the screen, surrounded by subtle animations of clinic-related icons (e.g., stethoscopes, calendars, clocks). As users interact, the desk will "respond" with micro-animations:

• Greeting Animation: A friendly wave icon appears when the system greets the user.
• Language Selection: Clicking a language option will cause the desk to "light up" in the selected language's color (e.g., blue for English, green for Hindi).
• Appointment Actions: Booking, rescheduling, or canceling an appointment will trigger a subtle "stamp" animation, symbolizing confirmation.
• Closing Interaction: A "Thank You" banner will unfurl from the desk as the interaction ends.

Transitions between sections will be smooth and fluid, with soft color shifts and gentle zoom effects to maintain user engagement.

7. Non-Functional Requirements

• Performance: The system must respond to user inputs within 2 seconds.
• Scalability: Designed to handle up to 50 concurrent users without degradation.
• Availability: 99.9% uptime to ensure reliability for clinic operations.
• Security: All patient data must be encrypted and comply with local data protection laws.
• Localization: Support for English and Hindi languages, with the ability to add more in the future.

8. Tech Stack

Frontend

• React for Web
• React Native for Mobile App

Backend

• Python
• FastAPI

Database

• MySQL (with Alembic for migrations)

AI Models

• GPT 5.4 for user-friendly responses
• Claude 4.6 Opas for coding or academic queries

AI Tools

• Langchain for conversational flow
• Litellm for LLM routing

Orchestration

• Docker for local development
• Kubernetes for server-side orchestration

9. Assumptions and Constraints

Assumptions

• Patients will primarily interact with the system for appointment-related tasks.
• The clinic operates in India, so timezone and locale defaults will be set to IST (Indian Standard Time).
• The system will initially support only English and Hindi languages.

Constraints

• The system must remain lightweight and simple to accommodate small clinics with minimal technical infrastructure.
• All interactions must comply with local healthcare data privacy regulations.

10. Glossary

• AI Receptionist: The virtual assistant handling patient interactions.
• IST: Indian Standard Time, the timezone for the clinic's operations.
• LLM: Large Language Model, used for natural language understanding.
• Fallback Handling: The system's response to unsupported languages or unclear inputs.
• Micro-Animations: Small, interactive animations that enhance user experience.