Repository navigation
Functional Requirements
Document type: Product and system requirements
Project: SaludVital
Status: Consolidated draft for Issue #2 — Document Functional Requirements
User interface language: Spanish
Technical documentation and source code language: English
This document defines the functional requirements for SaludVital, a web-based medical appointment management system. SaludVital supports patient registration and self-service, doctor consultation workflows, administrative operations, appointment scheduling, clinical-record consultation, notifications, and a menu-based WhatsApp integration.
The application shall use a modular monolithic architecture. Business rules for appointments, identity verification, authorization, and availability shall be enforced by the backend and reused across web and WhatsApp workflows.
This document consolidates the requirements and decisions confirmed so far. Items explicitly identified as pending policy decisions must be resolved before the affected functionality is considered complete.
A patient may:
- Register a patient account through public registration.
- Sign in and sign out.
- Recover a forgotten password using an email reset link.
- View and update permitted personal and contact information.
- View permitted medical profile information.
- Book appointments with available doctors and specialties.
- View their own appointments.
- Cancel or reschedule their own eligible appointments at least 24 hours before the scheduled start.
- Consult their own authorized diagnoses, prescriptions, and clinical history.
- Configure supported notification preferences.
- Request supported appointment operations through WhatsApp after identity verification.
A patient shall not be able to create or modify diagnoses or prescriptions through the patient portal.
A doctor may:
- Sign in and sign out.
- View their dashboard, own agenda, own appointments, and configured schedule.
- Filter and search their own appointments.
- Start and complete eligible consultations.
- Record consultation duration.
- Create and manage clinical records within authorized clinical workflows.
- Search for patients and access clinical information only when an authorized care relationship permits it.
- View their professional profile.
- Request schedule or appointment changes through an administrator.
- Recover or change their password.
Doctors shall not register their own doctor accounts, directly modify their schedules, or directly cancel or reschedule appointments. A doctor may have only one consultation in progress at a time.
An administrator may:
- Sign in and sign out.
- View administrative metrics and reports.
- View, search, edit, activate, and deactivate users.
- Filter users by role and change user roles.
- Create administrator accounts through the User Management section.
- Register and manage patients.
- Register and manage doctors.
- Create and manage medical specialties and assign them to doctors.
- Configure schedules and schedule exceptions for all doctors.
- Create and manage appointments according to the applicable rules.
- View all doctors' appointments and the system calendar.
- Consult diagnoses and prescriptions, including their associated patients and responsible doctors, subject to authorized access.
- Access the WhatsApp administration section.
- Review audit records.
Administrators may consult clinical information only within explicitly authorized permissions. Administrative functions shall not allow administrators to create or modify diagnoses or prescriptions.
The system shall authenticate users, enforce role-based authorization, validate input, protect data integrity, prevent conflicting bookings, enforce consultation concurrency rules, generate notifications, integrate with the configured WhatsApp provider or development simulator, and record relevant security and administrative events.
The system shall provide a single login page for Patients, Doctors, and Administrators. The form shall include email, password, a Sign In action, a Forgot Password link, and a Register link for users who do not have an account.
The login page shall not ask users to choose a role. After successful authentication, the backend shall identify the assigned role and redirect the user to the corresponding dashboard.
The backend shall validate credentials. Invalid-login responses shall not reveal whether a particular email address exists. Inactive or disabled accounts shall not be permitted to access protected functionality.
Public registration shall create Patient accounts only. Doctor accounts shall be created by an authorized administrator. Administrator accounts shall be created only by an authenticated administrator through the User Management section.
No public registration workflow shall permit a user to assign themselves the Doctor or Administrator role.
Password recovery shall use an email reset link consistently from both the login page and the patient profile/dashboard.
The recovery workflow shall:
- Ask the user to enter their email address.
- Send a time-limited reset link through the configured email service, when appropriate.
- Open a reset form from the link.
- Require a new password and password confirmation.
- Validate the reset token, its expiration, and the password policy.
- Invalidate the reset token after successful use.
Recovery responses shall not disclose whether an account exists. Expired, invalid, or previously used links shall be rejected. The process shall include reasonable safeguards against repeated requests and abuse.
Authenticated users shall be able to change their password by providing their current password, a new password, and confirmation of the new password. The system shall validate the current password and the configured password policy before saving the change. The system may require an additional verification step according to the security policy.
Passwords shall be stored using a secure password-hashing algorithm such as bcrypt with an appropriate work factor. Plaintext passwords shall never be stored or logged. Recovery tokens shall be protected, expire, and be invalidated after use.
The application shall use JWT authentication with a defined expiration policy for protected requests. Invalid, expired, or revoked credentials shall not grant access. Token handling and storage shall follow the application's security design.
The backend shall enforce role-based permissions for every protected operation. Supported roles are Patient, Doctor, and Administrator. A user shall only access resources and actions permitted by their role and, where relevant, their relationship to the patient, doctor, or appointment.
Hiding a user-interface control shall not be considered sufficient authorization.
The patient registration form shall require:
- First name.
- Last name.
- Email address.
- Phone number.
- Date of birth.
- Document type.
- Document number.
- Residential department.
- City or municipality.
- Password.
- Password confirmation.
The interface shall display validation errors in Spanish.
First name and last name shall each be required and limited to 50 characters. They shall accept letters and digits, including Spanish accented vowels and ñ/Ñ, and shall reject spaces and invalid characters according to the agreed field rule. The same rule shall be enforced on the backend.
Email shall be required, have a maximum length of 80 characters, use a valid email format, and be unique among user accounts. The backend and database shall prevent duplicates, including concurrent registration attempts.
Phone shall be required, contain digits only, and contain no more than 15 digits. Phone numbers shall be stored as strings so leading zeros are preserved.
Date of birth shall be required, represent a valid date, and not be in the future.
The document type dropdown shall offer:
- CC — Colombian Citizenship ID.
- CE — Foreigner ID.
- TI — Identity Card.
Passport shall not be offered in the defined patient registration form.
The document number shall be required, contain digits only, and have a maximum length of 15 digits. The system shall enforce uniqueness according to the applicable document-type/document-number rule.
The form shall offer a predefined list of Colombian departments. Municipality options shall depend on the selected department. Changing the department shall clear the current municipality selection and load the municipalities associated with the new department. The backend shall validate the department/municipality relationship.
Passwords shall be required to include at least one uppercase letter, at least three lowercase letters, at least one number, and at least one special character. Password length shall comply with configured minimum and maximum limits. Password confirmation shall match. The same password policy shall apply to registration, password changes, and password resets.
After successful validation, the system shall create a user with the Patient role and the associated patient profile. Duplicate user identities shall be rejected. User-facing success and validation messages shall be in Spanish.
The system shall support patient records that do not have an active web account, when created through an authorized workflow. A patient record alone shall not be treated as proof of identity or permission to access existing appointments.
Patients shall be able to view and update permitted personal information, including first name, last name, email, phone, date of birth, document information subject to applicable restrictions, department, and municipality. Updates shall be validated by the backend and shall preserve uniqueness constraints.
The patient profile shall support permitted medical information, including blood type, allergies, and existing conditions. Editing permissions for sensitive medical information shall be enforced by the backend.
The profile shall support permitted address information and emergency contacts. Emergency contact details shall include first name, last name, phone number, and email. The system shall validate the submitted information.
Patients shall be able to configure supported channels: email, SMS, and WhatsApp. Preferences shall cover appointment confirmations, reminders, cancellations, rescheduling, new-diagnosis notifications, and general system updates.
The standard appointment reminder shall be scheduled 24 hours before an eligible appointment. The interface shall provide Save Changes and Cancel actions. Saving shall persist preferences; canceling shall discard unsaved changes. The system shall not send through unavailable, unsupported, or unauthorized channels.
After login, patients shall be redirected to a dashboard providing access to appointment booking, My Appointments, Clinical History, Profile, Notification Preferences, Password Management, and Sign Out. Summary counts shall be based on the authenticated patient's records only.
Patients shall be able to consult their own authorized clinical history, diagnoses, and prescriptions. Clinical records may include the date, responsible doctor, vital signs, diagnosis, treatment, prescription, and additional notes.
The interface shall allow the patient to open and close clinical-record details. Patients shall not be able to create or modify diagnoses or prescriptions.
Patients shall be able to select an active specialty available for booking.
After a specialty is selected, the doctor list shall show eligible doctors associated with that specialty. Changing the specialty shall clear incompatible doctor, date, and time selections.
Patients shall select a date based on the selected doctor's configured schedule and applicable schedule exceptions. Past dates and past time slots shall not be bookable.
Appointment slots shall be generated in 30-minute intervals based on the doctor's configured schedule and exceptions. The system shall exclude occupied slots, slots outside the schedule, blocked slots, and slots that fail the minimum advance-booking rule.
A patient shall book an appointment at least five hours before its scheduled start. For example, if the current time is 10:00, the earliest eligible start time is 15:00, subject to schedule and availability. The backend shall enforce the rule using the applicable server-side time and timezone.
Before creating an appointment, the system shall show a summary of the selected specialty, doctor, date, time, and relevant details. The patient must confirm before the appointment is created.
The backend shall revalidate availability at booking time and prevent two patients from booking the same conflicting doctor time slot. Appropriate database transactions, constraints, locking, or equivalent concurrency controls shall be used. If the slot becomes unavailable, the system shall reject the booking and display a clear Spanish message.
The system shall support these appointment statuses:
- Pending.
- In Progress.
- Completed.
- Cancelled.
Only authorized workflows may change status. Relevant appointment history shall be preserved.
Patients shall be able to view their own appointments, including specialty, doctor, date/time, status, and permitted actions. The interface shall provide an appropriate empty state when no appointments exist.
A patient may cancel an eligible appointment only when the cancellation is requested at least 24 hours before the scheduled start time. If fewer than 24 hours remain, the normal patient cancellation workflow shall reject the request.
The rule shall be enforced by the backend and shall also apply to WhatsApp cancellation requests. The system shall validate ownership, current appointment status, and any required confirmation before cancelling.
A patient may reschedule an eligible appointment only when the request is made at least 24 hours before the currently scheduled start time. If fewer than 24 hours remain, the normal patient rescheduling workflow shall reject the request.
The same rule shall be enforced by the backend and WhatsApp workflows.
Rescheduling shall retain the same doctor. The patient shall not switch doctors as part of a rescheduling operation. To book with a different doctor, the patient must cancel the existing appointment, if still eligible for cancellation, and create a new booking with the desired doctor.
Before confirming a reschedule, the backend shall validate the new date and time against the same doctor's schedule, the five-hour minimum advance-booking rule, schedule exceptions, current appointment status, and all conflicting appointments. The backend shall atomically revalidate availability and save the change so two patients cannot acquire the same doctor/time slot concurrently.
If the new slot is unavailable or the operation fails, the system shall not leave the appointment in a partially updated state. The system shall preserve relevant history and notify affected parties according to the notification rules.
Only an authorized administrator shall create doctor accounts and associate them with a user record, professional profile, and specialties. Doctors shall not self-register through the public patient registration form.
Doctors shall be able to view their own professional profile and permitted account information, change their password, and sign out.
Doctors shall be able to view their configured schedule and relevant exceptions. Doctors shall not edit schedules directly; they must request changes through an authorized administrator.
The doctor dashboard shall display appointments scheduled for today, active patients, consultations completed during the current week, and average consultation duration.
Metrics shall be calculated from persisted records. Average consultation duration shall use completed consultations with valid start and end timestamps.
An active patient shall be defined as a unique patient with at least one completed consultation in the previous rolling 12 months. Cancelled-only appointments and future appointments without a completed consultation shall not qualify. Each patient shall be counted once in the metric.
The doctor dashboard shall show the doctor's appointments for the current day, including appointment time, patient, reason for visit when available, status, and available actions. It shall show the next appointment when one exists. Doctors shall only see appointments assigned to them.
Doctors shall be able to filter their own appointments by Pending, In Progress, Completed, and Cancelled status and search their own appointments by permitted patient information. Search results alone shall not grant access to clinical history. The backend shall authorize every protected read.
A doctor may start an eligible appointment assigned to them only if they have no other consultation in progress. When a consultation starts, the backend shall validate the appointment, verify authorization, record the start timestamp, change the appointment status to In Progress, and start measuring duration.
A doctor may have only one consultation in progress at a time and must finish it before starting another. The backend shall enforce this rule across tabs, devices, and concurrent requests. Client-side button disabling alone is insufficient. A rejected attempt shall produce a clear Spanish message.
During an authorized consultation, the doctor shall be able to record symptoms, how the patient feels, applicable vital signs, diagnosis, treatment, prescription when applicable, and additional clinical notes. Records shall be associated with the correct patient, responsible doctor, and consultation or appointment.
When finishing a consultation, the system shall record the end timestamp, calculate and persist duration, save authorized clinical records, associate diagnoses and prescriptions with the patient and doctor, and change the appointment status to Completed. The doctor shall then be eligible to start another consultation.
The operation shall prevent duplicate completion and maintain consistent appointment and clinical records if an error occurs.
Doctors shall be able to search for patients using permitted identifying information, including document number, name, or email. Search results shall expose only the information required for identification and authorized workflows.
A doctor may access a patient's clinical history only when an assigned appointment or another explicitly authorized care relationship permits access. Searching for a patient shall not automatically grant access to their full history.
Access to records created by another doctor shall be limited to what is justified and permitted by the authorized care relationship.
Authorized clinical records shall show applicable diagnosis date, responsible doctor, vital signs, diagnosis, treatment, prescription, and notes. The interface shall allow authorized users to open and close record details. Only users with appropriate permissions may view the information.
The administrator dashboard shall show general operational metrics, including registered patients, registered doctors, active specialties, appointments by status, appointment activity over a selected period, and relevant notification or scheduling issues where supported.
The administrator shall be able to view all users and search or filter them by role, edit permitted user information, change roles, and activate or deactivate accounts.
The administrator shall be able to create administrator accounts from the User Management section. An administrator may change a Patient account to an Administrator account. Before granting the Administrator role, the system shall request explicit confirmation.
Only authenticated administrators shall be permitted to create administrator accounts or change roles. The backend shall enforce these permissions. Public registration shall remain restricted to patients.
Role changes, administrator account creation, and account deactivation shall be recorded in the audit log, including the responsible administrator, timestamp, affected user, and action.
The administrator shall be able to view and register patients with their required personal information. Administrative patient registration shall follow the same validation, uniqueness, and integrity rules as other authorized registration workflows. The system shall distinguish a patient record from an active web account.
The administrator shall be able to register doctors, edit permitted professional information, activate or deactivate doctor accounts, assign specialties, and configure schedules.
When a doctor is deactivated, the system shall identify and cancel that doctor's future pending appointments according to the deactivation workflow, preserve their history, record the administrative action, and notify affected patients through configured channels.
The administrator shall be able to create, view, edit, activate, and deactivate specialties. Each specialty shall have a name and description. The administrator shall be able to assign specialties to doctors. Inactive specialties shall not be offered for new bookings, and historical records shall retain their associations.
The administrator shall be able to create appointments and view appointments across all doctors. Details shall include date/time, patient, doctor, specialty, status, and relevant history where applicable.
Administrative appointment operations shall use the same availability, authorization, scheduling, and concurrency rules as other workflows. The administrator shall be able to perform permitted appointment changes, including changes needed after a doctor reports an emergency or availability issue.
When the administrator cancels or reschedules an appointment, the system shall record the reason and audit details and notify affected patients as appropriate.
The administrator shall have a calendar showing appointments across all doctors on their corresponding dates. The administrator shall be able to open an appointment to view its details. Calendar data shall reflect authorized status and schedule changes.
The administrator shall be able to view and manage schedules and schedule exceptions for all doctors.
When a schedule change makes future appointments incompatible with the updated schedule, the system shall cancel only the affected appointments and preserve those that remain compatible. The administrator shall provide a reason. The system shall record the responsible administrator, timestamp, reason, and affected appointments in the audit log.
Affected patients shall be notified through configured and authorized channels. Schedule changes and appointment cancellations shall be processed consistently so that the system does not retain invalid bookings. Notification failures shall be retryable and shall not undo a successfully committed schedule change.
The administrator shall be able to consult diagnoses in the database and identify the associated patient and responsible doctor, subject to authorized access. The administrator shall also be able to consult prescriptions and identify their associated patient and responsible doctor, subject to authorized access.
Administrative clinical access shall be read-only. Administrators shall not create or modify diagnoses or prescriptions through administrative functions.
The administrative portal shall provide a dedicated WhatsApp section for the supported operational functions of the integration. Available controls shall respect the administrator's permissions and the configured provider capabilities. WhatsApp appointment operations shall use the standard backend rules for identity verification, authorization, availability, and appointment management.
The administrator shall be able to view supported reports about system activity, users, appointments, and operational metrics. Reports shall be based on persisted records and respect authorization and privacy requirements.
Administrators shall be able to sign out securely. Protected pages and operations shall require valid authentication after sign-out.
The system shall support notifications for appointment confirmation, cancellation, rescheduling, and reminders.
The system shall support scheduling appointment reminders 24 hours before an eligible appointment. Before sending, it shall verify that the appointment remains eligible and has not been cancelled or otherwise invalidated.
The system shall support configured notifications for new diagnosis availability and general system updates. Messages shall avoid unnecessary disclosure of sensitive clinical information, particularly in previews and channels that may be visible to others.
The system shall support configured email, SMS, and WhatsApp adapters and respect patient preferences, channel availability, and applicable authorization or consent requirements. A channel that is unavailable or unauthorized shall not be used.
The system shall maintain appropriate notification records, including event, intended recipient, channel, creation time, and delivery status where available. Transient delivery failures shall be retryable. Retries shall be controlled to avoid uncontrolled duplicate notifications.
The WhatsApp integration shall provide a Spanish-language automated menu with these options:
- Book an appointment.
- Check availability.
- Consult my appointments.
- Reschedule an appointment.
- Cancel an appointment.
The initial implementation shall use this menu-based flow rather than relying on unrestricted natural-language interpretation. No support-agent menu option is required in the defined initial menu.
A person may request supported appointment operations through WhatsApp without having a SaludVital web account, but must have a valid patient record and complete the required verification. If the person has no patient record, the system shall direct them to the required registration process before booking.
In the initial version, patients may request appointments only for themselves, not for family members or third parties.
For protected WhatsApp operations, the system shall require the patient's document number and a verification code sent to the patient's previously registered and verified WhatsApp number. The document number alone shall not authorize access.
The system shall validate the code, its expiration, and applicable attempt limits before allowing the user to consult, cancel, or reschedule existing appointments. The system shall not disclose another patient's information.
WhatsApp appointment operations shall reuse the same backend business rules as the web application, including specialty and doctor availability, 30-minute slots, the five-hour minimum booking lead time, conflict prevention, appointment status validation, the 24-hour cancellation and rescheduling deadlines, same-doctor rescheduling, and identity/authorization checks.
The WhatsApp integration shall not bypass backend validation.
The initial WhatsApp integration shall not disclose diagnoses, prescriptions, or clinical history. It shall focus on supported appointment operations and related notifications.
The intended production integration shall use the Meta WhatsApp Business Platform Cloud API, subject to provider configuration, platform policies, and applicable messaging requirements. Development shall support a simulator or mock adapter so workflows can be tested without a production connection.
Provider-specific code shall be isolated behind an integration interface and shall not be tightly coupled to appointment business logic.
The system shall maintain consistent relationships among users, patients, doctors, specialties, schedules, appointments, consultations, diagnoses, prescriptions, and notifications. Database constraints and backend validation shall prevent invalid relationships and duplicate identities.
Related operations shall use appropriate transactional controls.
The system shall record relevant security and administrative events, including:
- Administrator account creation.
- User role changes.
- Account activation and deactivation.
- Administrative appointment cancellation or rescheduling.
- Doctor schedule changes that affect appointments.
- Other critical operations defined by the security policy.
Audit records shall identify the responsible actor, action, affected resource, timestamp, and reason when required and available. Audit logs shall not contain plaintext passwords, reset tokens, verification codes, or unnecessary sensitive clinical information.
Appointment and clinical history shall be preserved according to the applicable retention policy. Deactivation, cancellation, or other lifecycle changes shall not silently delete records required for traceability and authorized consultation.
All operations that create, modify, or retrieve protected data shall be validated on the backend. Client-side validation shall improve usability but shall not replace server-side validation.
The application shall use parameterized queries, ORM protections, or equivalent safe database-access techniques. User-supplied values shall not be concatenated into executable SQL statements.
Patients shall not access another patient's private information. Doctors shall not access appointments or clinical records outside their authorized relationships. Administrative permissions shall be enforced on the backend.
Personal and clinical information shall be exposed only to authorized users and only as required for the requested operation. Sensitive information shall not be unnecessarily included in logs, URLs, notifications, or error messages.
Password-reset links and WhatsApp verification codes shall expire and be protected against reuse and excessive attempts. Responses shall avoid revealing account existence. Verification secrets shall not be logged in plaintext.
User-facing pages, forms, validation messages, notifications, and instructions shall be presented in Spanish. Source code identifiers and technical documentation shall be in English.
The application shall be usable on mobile phones, tablets, laptops, and desktop screens. Forms, dashboards, tables, calendars, menus, and dialogs shall adapt to smaller screens.
The interface shall clearly identify invalid fields and provide understandable Spanish error messages. Validation feedback shall not rely on color alone.
Interactive elements shall support appropriate labels, keyboard navigation, visible focus, and accessible error feedback. Accessibility shall be assessed using automated tools and manual checks.
The following details remain to be specified before the related functionality can be considered fully defined:
- Exact minimum and maximum password lengths.
- The complete list and source of Colombian departments and municipalities.
- The precise set of user fields that each role may edit, including restrictions on changing email, document identity, or other sensitive fields.
- The detailed report catalogue, filters, and export formats.
- The exact metrics and definitions beyond the active-patient definition already established.
- Data retention periods and any applicable deletion/anonymization workflow.
- Whether and how patients may edit blood type, allergies, and conditions, and whether those changes require review.
- The final policy for doctor deactivation when appointments are already In Progress or otherwise not Pending.
- Operational details for rescheduling when the patient is exactly at the 24-hour boundary, using a consistent server-side timestamp and timezone.
The following rules are already defined and shall not be treated as unresolved: patients must cancel or reschedule at least 24 hours before the scheduled start; rescheduling must retain the same doctor; a slot must be revalidated atomically; WhatsApp requires the document number plus a code sent to the previously registered and verified WhatsApp number; password recovery uses an email link; and schedule changes cancel only future appointments made incompatible by the new schedule.
This document is ready for requirements review when:
- Patient, Doctor, and Administrator capabilities are documented.
- Registration fields and validation rules are documented.
- Login, password change, and email-link password recovery are documented.
- Booking, availability, concurrency, cancellation, and rescheduling rules are explicit.
- Doctor consultation and single-active-consultation restrictions are explicit.
- Clinical history authorization is documented.
- Administrative user, patient, doctor, specialty, appointment, calendar, schedule, clinical consultation, WhatsApp, and report functions are documented.
- Notification, identity verification, security, audit, and data-integrity requirements are documented.
- Remaining details requiring product decisions are tracked and not silently replaced with assumptions.
Implementation shall be validated with suitable unit, integration, end-to-end, authorization, concurrency, and accessibility tests.