Repository navigation
Software Architecture
This document defines the software architecture of SaludVital, a healthcare appointment management system. It describes the architectural style, application layers, functional modules, communication flow, security principles, data persistence, and deployment approach.
The architecture provides a maintainable, secure, modular, and testable foundation for the system.
SaludVital follows a Modular Monolith Architecture.
The application is deployed as a single application while its internal functionality is separated into modules with clearly defined responsibilities.
This approach allows the development team to organize the codebase by business domain without introducing the operational complexity of a microservices architecture.
- Modularity: Each module is responsible for a specific business domain.
- Separation of concerns: Presentation, business logic, data access, and infrastructure are separated.
- Single source of business rules: Appointment rules are shared across web and WhatsApp interactions.
- Security by design: Authentication, authorization, validation, and data protection are enforced at the appropriate layers.
- Testability: Modules and application layers can be tested independently where practical.
- Maintainability: Changes should remain localized whenever possible.
- Consistency: Database transactions protect operations that must succeed or fail together.
| Component | Technology | Responsibility |
|---|---|---|
| Runtime | Node.js | Executes the server-side application |
| Web framework | Express.js | Routing, middleware, and HTTP request handling |
| Presentation | Pug | Server-rendered HTML views |
| Styling | Tailwind CSS | Responsive user interface styling |
| ORM | Sequelize | Models, queries, relationships, and transactions |
| Database | MySQL | Persistent application data |
| Authentication | JSON Web Tokens (JWT) | Authenticated session and token handling |
| Password security | bcrypt | Password hashing and verification |
| Unit testing | Jest | Unit tests |
| Integration testing | Supertest | HTTP and API integration tests |
| End-to-end testing | Playwright | User workflow and browser tests |
| Accessibility testing | Playwright with axe-core | Automated accessibility checks |
Exact dependency versions will be recorded in package.json and the project's dependency lockfile.
The application is organized into the following logical layers:
Responsible for rendering pages and handling user interactions.
Responsibilities:
- Render server-side HTML using Pug.
- Display Spanish-language interface messages.
- Provide responsive layouts for mobile devices, tablets, and desktop screens.
- Submit user input to application routes.
- Display validation errors and operation results.
Responsible for receiving HTTP requests and applying cross-cutting controls.
Responsibilities:
- Define application routes.
- Parse and validate request data through the appropriate middleware.
- Authenticate protected requests.
- Enforce role-based access control.
- Handle errors consistently.
- Prevent unauthorized access to protected functionality.
Responsible for executing use cases and enforcing business rules.
Responsibilities:
- Register and manage users.
- Authenticate users and handle password recovery.
- Manage doctor schedules and availability.
- Book, cancel, and reschedule appointments.
- Record diagnoses, treatments, and prescriptions according to permissions.
- Coordinate notifications.
- Process administrative operations.
- Reuse appointment rules across supported interaction channels.
Responsible for communicating with the database through Sequelize models and queries.
Responsibilities:
- Define entity models and relationships.
- Execute database queries.
- Manage transactions for operations requiring consistency.
- Enforce and handle database constraints.
- Prevent duplicate bookings and inconsistent schedule updates.
Responsible for external communication and technical services.
Responsibilities:
- Connect to MySQL.
- Send email notifications through a configured provider.
- Integrate with the WhatsApp Business Platform Cloud API.
- Provide a development WhatsApp simulator.
- Process notification delivery results and retries.
- Read environment-specific configuration.
The application is divided into the following modules.
| Module | Main responsibilities |
|---|---|
| Authentication | Login, JWT validation, logout, password changes, and password recovery |
| Patients | Patient registration, personal information, and patient records |
| Doctors | Doctor profiles and professional information |
| Specialties | Specialty management and doctor-specialty assignments |
| Schedules | Doctor availability, working hours, and schedule exceptions |
| Appointments | Booking, cancellation, rescheduling, status transitions, and conflict prevention |
| Diagnoses | Recording and consulting clinical diagnoses according to permissions |
| Prescriptions | Recording and consulting prescriptions according to permissions |
| Notifications | Notification preferences, templates, delivery tracking, and retries |
| Identity verification and appointment-related conversational workflows | |
| Administration | User management, role management, system configuration, and administrative operations |
| Reporting | Dashboard metrics and authorized operational reports |
| Audit | Traceability of sensitive administrative and clinical operations |
Modules should communicate through clearly defined application interfaces rather than accessing another module's internal implementation unnecessarily.
A typical web request follows this flow:
- A user interacts with a Pug-rendered page.
- The browser sends an HTTP request to an Express route.
- Middleware performs the required authentication, authorization, and input validation.
- The corresponding module executes the application use case.
- Business services enforce the applicable rules.
- Sequelize accesses MySQL, using transactions when required.
- The application prepares the response.
- Express returns the rendered page or the appropriate HTTP response.
- Relevant notification tasks are processed through the notification module.
The exact response format depends on the route and the interaction being handled.
SaludVital has three application roles:
- Patient
- Doctor
- Administrator
All roles use a common login entry point. After successful authentication, the application identifies the user's role and directs the user to the corresponding dashboard.
Security requirements include:
- Store passwords as bcrypt hashes, never as plaintext.
- Use JWTs with expiration and secure handling.
- Authenticate protected requests on the server.
- Enforce role-based permissions in backend middleware and application logic.
- Validate resource ownership and authorized care relationships where applicable.
- Never rely exclusively on hidden buttons or frontend restrictions for authorization.
- Require explicit confirmation before granting administrator privileges.
- Audit sensitive role changes and administrative account operations.
- Restrict clinical information to authorized users.
- Protect secrets and environment-specific configuration.
Administrator access to diagnoses and prescriptions is read-only. Creating or modifying clinical records must follow the permissions defined for authorized clinical workflows.
Appointment operations must enforce the same business rules regardless of whether a request originates from the web interface or WhatsApp.
The application must:
- Offer only available appointment slots.
- Enforce the minimum five-hour advance booking requirement.
- Reject patient cancellation or rescheduling requests made less than 24 hours before the appointment.
- Keep the same doctor when rescheduling an existing appointment.
- Validate availability again when confirming a booking or rescheduling operation.
- Prevent concurrent requests from reserving the same slot.
- Use database transactions and appropriate constraints for operations that must remain consistent.
- Preserve appointment history and audit relevant administrative changes.
Database consistency must not depend exclusively on frontend validation.
Notifications are handled by an internal application module rather than a separate microservice.
Supported channels may include email, SMS, and WhatsApp, depending on configuration, provider availability, user preferences, and required consent.
Notification workflows include:
- Appointment confirmation.
- Appointment cancellation and rescheduling.
- Eligible appointment reminders.
- Relevant clinical notifications.
- General system updates.
The WhatsApp module uses an adapter-based integration approach:
- Development: A simulator supports local development and testing.
- Production: The intended integration is the Meta WhatsApp Business Platform Cloud API.
WhatsApp workflows reuse the same application services and appointment business rules as the web application.
Before performing protected appointment operations, WhatsApp users must be identified and verified through the approved verification process. Clinical diagnoses, prescriptions, and medical history must not be disclosed through WhatsApp.
Notification failures must be tracked and retried where appropriate. A delivery failure must not undo a successfully committed appointment operation.
MySQL is the relational persistence layer, accessed through Sequelize.
The principal entities include:
- Users and roles.
- Patients and doctors.
- Specialties and doctor-specialty assignments.
- Doctor schedules and schedule exceptions.
- Appointments and appointment statuses.
- Diagnoses and prescriptions.
- Notifications, preferences, and templates.
- WhatsApp requests.
- Audit logs.
The database design must define primary keys, foreign keys, unique constraints, appropriate indexes, and relationships.
Transactions must protect operations such as appointment booking, schedule changes, and other workflows that modify related records.
The detailed schema and entity relationships are documented in the Database Design and Entity Relationship Diagram Wiki pages.
SaludVital is deployed as a single Node.js application connected to a MySQL database.
The deployment environment must provide:
- A supported Node.js runtime.
- Application dependencies installed from the project lockfile.
- Environment-specific configuration.
- A reachable MySQL instance.
- A production build of the Tailwind CSS stylesheet.
- Access to configured notification providers when those integrations are enabled.
- Appropriate logging, error handling, and operational monitoring.
Pug templates are rendered on the server. Tailwind CSS is compiled for the application; the production interface must not depend on the Tailwind CDN.
Database credentials, JWT secrets, and external integration credentials must be supplied through secure environment configuration and must not be committed to version control.
Development, testing, and production environments must use appropriate configurations and credentials.
Testing is organized by scope:
- Unit tests: Validate individual business functions and module behavior.
- Integration tests: Verify routes, middleware, database interactions, and module integration.
- End-to-end tests: Validate complete user workflows in a browser.
- Authorization tests: Verify role restrictions, resource ownership, and unauthorized access attempts.
- Concurrency tests: Verify that simultaneous appointment requests cannot create conflicting reservations.
- Accessibility tests: Identify common accessibility issues in rendered pages.
- Responsive interface tests: Verify essential workflows on mobile, tablet, and desktop viewport sizes.
Tests must cover successful operations, validation failures, permission violations, and relevant error scenarios.
The following decisions guide implementation:
- The system remains a modular monolith unless an explicit architecture review approves a change.
- Business rules must be enforced on the server.
- Web and WhatsApp workflows must reuse shared application services.
- Clinical records must be protected through backend authorization.
- Appointment and schedule operations must preserve data consistency.
- External notification providers must be isolated behind integration interfaces where practical.
- Application secrets must remain outside version control.
- Functional modules must have clear responsibilities and avoid unnecessary coupling.
- Product Vision and Scope
- Functional Requirements
- Stakeholders and User Roles
- Database Design
- Entity Relationship Diagram
- Security and Privacy
- Testing Strategy
- Deployment Guide
This document must be updated whenever an approved architectural decision changes the system's layers, modules, technology stack, security model, integrations, or deployment approach.
Architecture changes must be reviewed through the project's established Git workflow and documented in the relevant pull request.