Table of Contents
Phase I: Project Proposal
1.1 Introduction
The Sillah (صلة) project is a preventive health management system designed to help Saudi families identify hereditary cardiac risks through an easy-to-use digital platform.
It enables users to record their family health history, receive automatic risk alerts, and book preventive clinic appointments.
This report documents all project phases — from requirements to design, prototype, and testing — demonstrating a full software development process aligned with SE201 objectives.
1.2 Project Overview
1.2.1 Goals
- Promote Preventive Health Awareness: Promote public awareness regarding hereditary diseases and encourage early detection.
- Simplify Family Health Tracking: Provide a simple-to-use interface for families to follow and chart medical histories.
- Enable Smart Risk Detection: Use rule-based reasoning to automatically detect hereditary cardiac risk patterns.
- Support Action Through Integration: Link users to accredited clinics for consultations and checkups.
- Empower Public Health Systems: Demonstrate a scalable model that can be embedded in national healthcare systems.
1.2.2 Objective
To provide a user-friendly system that allows citizens to record family health data, analyze hereditary patterns, and take proactive steps toward cardiac screening.
1.2.3 Main Features
- Add and manage family members with health events
- Detect hereditary risks automatically
- Send personalized alerts and recommendations
- Access an Awareness Hub with educational content and checklists
- Book appointments with local clinics
1.2.4 Users
- General citizens (families)
- Healthcare Providers (view bookings)
- Administrators (manage awareness content)
Phase II: Requirements Analysis & Documentation
2.1 Functional Requirements
| ID | Requirement | Description | Priority |
|---|---|---|---|
| FR-01 | Add Family Member | User can record family members with name, relation, and health conditions | High |
| FR-02 | Add Health Event | User can specify a condition and age of onset | High |
| FR-03 | Generate Risk Alert | System detects hereditary risk and sends an alert | High |
| FR-04 | Book Appointment | User can select a clinic and confirm booking | Medium |
| FR-05 | View Awareness Content | User can access health tips and checklists | Medium |
| FR-06 | View Alert History | User can view past alerts | Low |
2.2 Non-Functional Requirements
2.2.1 Introduction & Overview
This document specifies the Non-Functional Requirements (NFRs) for the Sillah Family Health Management System across Usability, Reliability, and Security. The goal is to ensure the platform is simple to use, robust, and safe for all users in Saudi Arabia. Items marked [Conceptual] indicate production-level expectations. In Phase IV (Java prototype), those items will be simulated or documented, while core functionality will be implemented.
2.2.2 Usability Requirements
UR-01: Mobile-First Responsive Design
Priority: Critical
Phase IV: Implement
Rationale: Most users in Saudi Arabia access services via mobile; optimizing for phones maximizes reach.
User Stories: SIL-7 to SIL-16
Requirement: Interface must work across screen sizes, prioritizing mobile.
Acceptance Criteria:
- Passes Google Mobile-Friendly Test
- Verified on iPhone (Safari) and Android (Chrome)
- Viewport meta tag is set correctly
- Touch targets ≥ 44×44 px (WCAG)
- No horizontal scrolling
UR-02: WCAG 2.1 Level AA Accessibility
Priority: High
Phase IV: Implement core; document full compliance
Rationale: Public services must be accessible and legally compliant.
User Stories: SIL-7 to SIL-16
Requirement: Meet WCAG 2.1 AA guidelines.
Acceptance Criteria:
- WAVE/axe automated scan: zero critical errors
- Manual test with NVDA or JAWS
- Keyboard-only navigation succeeds
- Color contrast verified with WebAIM (≥ 4.5:1 normal text)
UR-03: Task Completion Efficiency
Priority: High
Phase IV: Implement
Rationale: Faster tasks increase adoption and adherence to preventive actions.
User Stories: SIL-7, SIL-13, SIL-14
Requirement: Key tasks should be quick and low-effort.
Acceptance Criteria:
- Build a basic family tree in < 5 minutes (≥ 15 participants)
- Find & download a checklist in < 3 minutes
- ≥ 90% success on critical tasks without help
UR-04: Bilingual Interface (Arabic & English)
Priority: High
Phase IV: Implement
Rationale: Serves both Arabic speakers and expatriates.
User Stories: SIL-7 to SIL-16
Requirement: Full bilingual support.
Acceptance Criteria:
- 100% UI translated
- RTL layout correct for Arabic
- Language preference persists
- Medical terminology reviewed by an Arabic-speaking clinician
UR-05: Clear Error Messages & Guidance
Priority: High
Phase IV: Implement
Rationale: Friendly, actionable errors reduce frustration and support load.
User Stories: SIL-7, SIL-8, SIL-15
Requirement: Errors must be specific, polite, and near the relevant field.
Acceptance Criteria:
- Messages free of technical jargon
- Inline placement beside fields
- Visible success states with confirmation
UR-06: Intuitive Information Architecture
Priority: High
Phase IV: Implement
Rationale: Logical structure lowers cognitive load.
User Stories: SIL-7 to SIL-16
Requirement: Content and features must be easy to find.
Acceptance Criteria:
- ≤ 3 clicks to any feature
- "Ease of finding" rating ≥ 4/5
- Breadcrumbs available site-wide
UR-07: Consistent UI & Design System
Priority: High
Phase IV: Implement
Rationale: Consistency reduces cognitive load and errors.
User Stories: SIL-7 to SIL-16
Requirement: Use a single component style (buttons, inputs, spacing, headings).
Acceptance Criteria:
- One button hierarchy (primary/secondary) applied site-wide
- 4/8 px spacing scale used consistently
- H1–H4 typography consistent across pages
UR-08: Progressive Disclosure
Priority: Medium
Phase IV: Implement
Rationale: Hide advanced options until needed to keep screens simple.
User Stories: SIL-7, SIL-11, SIL-15
Requirement: Collapsible/stepwise flows for long forms and settings.
Acceptance Criteria:
- Long tasks split into ≤ 5 clear steps
- Advanced options hidden by default, revealed on demand
- User completes add-member flow without scrolling more than one screen per step
UR-09: Forms – Validation, Defaults & Undo
Priority: High
Phase IV: Implement
Rationale: Fewer entry errors and easier recovery.
User Stories: SIL-7, SIL-8, SIL-13
Requirement: Real-time validation, sensible defaults, and undo for deletes.
Acceptance Criteria:
- Inline validation fires on blur and submit
- Common fields prefilled (e.g., city from profile)
- Delete shows snackbar with 10-second “Undo”
UR-10: Help, Hints & Empty States
Priority: Medium
Phase IV: Implement
Rationale: Users succeed without external documentation.
User Stories: SIL-11, SIL-12, SIL-16
Requirement: Contextual tips and meaningful empty states.
Acceptance Criteria:
- Each empty list/page shows a 1–2 step “how to start”
- Tooltips/help icons for non-obvious fields
- Help links resolve to in-app guidance
UR-11: Status, Loading & Save Feedback
Priority: High
Phase IV: Implement
Rationale: Clear feedback improves trust and perceived speed.
User Stories: SIL-9, SIL-10, SIL-13
Requirement: Visual loading states and explicit save/booking confirmations.
Acceptance Criteria:
- Loading shown if action > 300 ms
- Save/booking shows success toast with details
- Failures include reason + next action
UR-12: Locale Usability (Dates/Numbers/RTL Details)
Priority: Medium
Phase IV: Implement
Rationale: Locale-correct entry/format prevents mistakes.
User Stories: SIL-7 to SIL-16
Requirement: Use locale formats and mirror UI for RTL.
Acceptance Criteria:
- Dates use user locale (e.g., dd/mm/yyyy or Hijri label if shown)
- Numbers use Arabic/Western numerals per language
- All icons/layouts mirror correctly in RTL
2.2.3 Reliability Requirements
RR-01: Availability & Uptime [Conceptual]
Priority: Critical
Phase IV: Document
Rationale: Users need access when risk alerts matter most.
User Stories: SIL-7 to SIL-16
Requirement: High availability with minimal unplanned downtime.
Acceptance Criteria:
- Monthly uptime target 99.5% (≤ 3.65 hours downtime)
- Automated monitoring & alerts
- Public status page
RR-02: Fault Tolerance & Graceful Degradation
Priority: High
Phase IV: Implement core; document full design
Rationale: Prevent total failure when a component misbehaves.
User Stories: SIL-7 to SIL-16
Requirement: The system continues in a reduced mode if non-critical parts fail.
Acceptance Criteria:
- No crashes on data/IO errors; user sees a recoverable message
- Automatic retry with exponential backoff (max 3 attempts)
- Read-only mode available if writes fail
RR-03: Data Backup & Restore [Conceptual]
Priority: Critical
Phase IV: Document; prototype provides export/import
Rationale: Recover from data loss incidents.
User Stories: SIL-7 to SIL-16
Requirement: Define backup schedule and recovery targets.
Acceptance Criteria:
- RPO ≤ 24h; RTO ≤ 4h
- Backups encrypted at rest
- Prototype: JSON export/import verified on test data
RR-04: Data Accuracy & Integrity
Priority: Critical
Phase IV: Implement
Rationale: Incorrect risk results undermine the system's purpose.
User Stories: SIL-7 to SIL-10
Requirement: Protect data quality and detect risks accurately.
Acceptance Criteria:
- False negatives ≤ 1% on a defined test set
- False positives < 5% from entry errors
- DB constraints prevent impossible data
- 100% detection on known-risk test trees
RR-05: Performance & Response Time
Priority: High
Phase IV: Implement
Rationale: Fast responses increase trust and task completion.
User Stories: SIL-7, SIL-9, SIL-13
Requirement: Keep key actions responsive under typical load.
Acceptance Criteria:
- P95 response < 1.0s for add member, view alerts, book appointment
- P99 response < 2.5s for above actions
- Prototype includes simple timing output for these actions
RR-06: Scalability Path [Conceptual]
Priority: Medium
Phase IV: Document
Rationale: Prepare for increased users and data volume.
User Stories: SIL-7 to SIL-16
Requirement: Architecture supports horizontal scaling for stateless services.
Acceptance Criteria:
- Design notes for scaling UI/API independently
- No hard-coded limits in code for list sizes
- Prototype uses collections sized dynamically
RR-07: Observability & Logging
Priority: High
Phase IV: Implement core
Rationale: Diagnose issues and monitor reliability.
User Stories: SIL-9, SIL-10, SIL-16
Requirement: Structured logs with levels and correlation IDs.
Acceptance Criteria:
- INFO for user actions; WARN/ERROR for failures with reasons
- Each request/action includes a correlation ID in logs
- Prototype prints structured console logs for main flows
RR-08: Session Reliability & Auto-Save
Priority: Critical
Phase IV: Implement
Rationale: Prevent loss of in-progress data; aligns with SR-03 timeout note.
User Stories: SIL-7, SIL-8, SIL-15
Requirement: Stable sessions with safe inactivity handling.
Acceptance Criteria:
- Auto-save drafts every 30 seconds (or on step change)
- Inactivity logout at 15 minutes; warning at 60 seconds before
- On restart, user can restore last draft
RR-09: Consistency & Concurrency
Priority: High
Phase IV: Implement core; document full approach
Rationale: Avoid lost updates when multiple edits occur.
User Stories: SIL-7, SIL-8, SIL-10
Requirement: Use optimistic locking/version checks on updates.
Acceptance Criteria:
- Conflicting edits are detected and surfaced to the user
- Atomic add/edit operations for family members
- Prototype simulates version check in memory
2.2.4 Security Requirements
SR-01: Data Privacy & PII Protection
Priority: Critical
Phase IV: Implement core; document full policy
Rationale: Protect sensitive family medical data and comply with local regulations.
User Stories: SIL-7 to SIL-16
Requirement: Limit collection, mask sensitive fields, and restrict exposure.
Acceptance Criteria:
- Only necessary fields collected; optional items clearly labeled
- PII redacted in logs and debug output
- Access to PII requires authenticated session + role check
SR-02: Encryption (In Transit & At Rest) [Conceptual]
Priority: Critical
Phase IV: Document; prototype simulates at-rest via obfuscation
Rationale: Prevent eavesdropping and data theft.
User Stories: SIL-7 to SIL-16
Requirement: TLS 1.2+ for transit; encrypted storage for PII.
Acceptance Criteria:
- Design notes: TLS required for all endpoints; HSTS enabled
- At rest: keys managed outside code; encrypted backups (see RR-03)
- Prototype: no plaintext PII persisted to disk
SR-03: Authentication
Priority: Critical
Phase IV: Implement
Rationale: Only authorized users should access health data.
User Stories: SIL-15
Requirement: Follow secure authentication practices.
Acceptance Criteria:
- Weak passwords rejected
- Session tokens rotated at login
- Auto-logout after 15 minutes (mirrors RR-08)
- Prototype documents hashing policy; production uses bcrypt ≥ 12 rounds + breached-password checks
SR-04: Role-Based Access Control (RBAC)
Priority: Critical
Phase IV: Implement
Rationale: Enforce least privilege by role.
User Stories: SIL-7 to SIL-16
Requirement: Three roles with appropriate permissions.
Acceptance Criteria:
- Role set at account creation
- Unauthorized access attempts blocked and logged
- UI hides unavailable options
- Server-side role checks on every protected API
SR-05: Secure Input Validation & Output Encoding
Priority: High
Phase IV: Implement
Rationale: Prevent injection and XSS issues.
User Stories: SIL-7, SIL-8, SIL-15
Requirement: Validate on server side; encode all untrusted output.
Acceptance Criteria:
- Server rejects invalid age/relationship values with clear errors
- No direct rendering of raw user input without encoding
- Prototype unit tests cover typical injection payloads
SR-06: Secrets Management
Priority: High
Phase IV: Document; implement placeholder mechanism
Rationale: Prevent credential leaks.
User Stories: SIL-16
Requirement: No secrets committed to source control; use environment/config store.
Acceptance Criteria:
- Repo scan shows no hard-coded secrets/tokens
- Prototype reads secrets from environment variables only
SR-07: Security Logging & Audit Trails
Priority: High
Phase IV: Implement core (align with RR-07)
Rationale: Investigate incidents and unauthorized access attempts.
User Stories: SIL-9, SIL-10, SIL-16
Requirement: Log auth events, privilege changes, and access denials.
Acceptance Criteria:
- Login success/failure logged with correlation ID (no PII)
- RBAC denials recorded with reason
- Prototype prints structured “SECURITY” lines for these events
SR-08: Dependency & Vulnerability Management
Priority: Medium
Phase IV: Document; run basic checks
Rationale: Reduce risk from third-party libraries.
User Stories: SIL-16
Requirement: Keep libraries updated; scan for known CVEs.
Acceptance Criteria:
- Dependency list maintained; updates planned each sprint
- Prototype: build step includes a vulnerability check (report attached)
SR-09: Data Retention & Right to Erasure
Priority: Medium
Phase IV: Document; prototype supports delete/export
Rationale: Respect user control over personal data.
User Stories: SIL-15, SIL-16
Requirement: Define retention periods; allow user-initiated deletion/export.
Acceptance Criteria:
- Policy: default retention and deletion triggers defined
- Prototype: user data export (JSON) and delete path demonstrated
SR-10: Third-Party/Clinic Integration Security [Conceptual]
Priority: High
Phase IV: Document
Rationale: Securely interact with external clinic systems.
User Stories: SIL-13, SIL-14
Requirement: Use signed requests, least-privilege tokens, and input sanitization on responses.
Acceptance Criteria:
- Design specifies token scopes and rotation
- All inbound data validated before use
2.4 Traceability Matrix
| Requirement ID | Priority | Phase IV Status | Related User Stories | Verification Method |
|---|---|---|---|---|
| UR-01 | Critical | Implement | SIL-7 to SIL-16 | Mobile responsive test (Google Mobile-Friendly) |
| UR-02 | High | Implement | SIL-7 to SIL-16 | WAVE/axe scan + manual NVDA test |
| UR-03 | High | Implement | SIL-7, SIL-13, SIL-14 | Usability timing tests (avg <5 min) |
| UR-04 | High | Implement | SIL-7 to SIL-16 | Arabic/English switch verified |
| UR-05 | High | Implement | SIL-7, SIL-8, SIL-15 | Error message placement verified |
| UR-06 | High | Implement | SIL-7 to SIL-16 | Navigation ≤ 3 clicks |
| UR-07 | Medium | Document | SIL-7 to SIL-16 | Design system audit |
| UR-08 | Medium | Document | SIL-10 | First-time use UX evaluation |
| UR-09 | Medium | Document | SIL-11 | Readability test (grade ≤ 9) |
| UR-10 | Medium | Document | SIL-11, 12 | System feedback responses |
| UR-11 | Low | Document | SIL-12 | Help & support access test |
| UR-12 | Low | Document | SIL-12 | SUS ≥ 80 % target |
| RR-01 | Critical | Document | SIL-7 – SIL-16 | Availability log (target 99.5 %) |
| RR-02 | High | Document | SIL-7 – SIL-16 | Backup policy simulation |
| RR-03 | Medium | Document | SIL-7 – SIL-16 | Fault-tolerance test scenario |
| RR-04 | Critical | Implement | SIL-7 – SIL-10 | Data validation + accuracy check |
| RR-05 | High | Document | SIL-7 – SIL-16 | Browser/device compatibility test |
| RR-06 | Medium | Document | SIL-7 – SIL-16 | Performance load simulation |
| RR-07 | Medium | Document | SIL-11 | Content update review log |
| RR-08 | High | Implement | SIL-15 | Session persistence & auto-save |
| RR-09 | Medium | Document | SIL-14, 15 | API timeout/error test |
| RR-10 | Low | Simulate | SIL-13 | Notification delivery mock test |
| SR-01 | Critical | Document | SIL-15 | Data encryption at rest plan |
| SR-02 | Critical | Document | SIL-15 | Transport-layer encryption (HTTPS) |
| SR-03 | Critical | Implement | SIL-15 | Password & session security test |
| SR-04 | Critical | Implement | SIL-7 – SIL-16 | Role-based access validation |
| SR-05 | High | Document | SIL-7 – SIL-16 | Consent management audit |
| SR-06 | High | Document | SIL-7 – SIL-16 | Audit log review procedure |
| SR-07 | Critical | Implement | SIL-7 – SIL-10 | Input validation & sanitization test |
| SR-08 | High | Document | SIL-7 – SIL-10 | Privacy review (data minimization) |
| SR-09 | High | Implement | SIL-15 | Secure password reset scenario |
| SR-10 | High | Document | SIL-12 – SIL-14 | Awareness Hub content security check |
2.5 Implementation Summary
Total NFRs
32 Total
Phase IV Plan
- Implement: 18 (prototype core)
- Simulate: 1 (notification delivery)
- Document: 13 (production-scale, conceptual)
Prototype Focus
2.6 Ethics Considerations
The development and deployment of the Sillah Family Health Management System involve significant ethical considerations due to the sensitive nature of health data and the potential impact on users' healthcare decisions.
2.6.1 Data Privacy and Confidentiality
- Health Data Sensitivity: Family health history constitutes highly sensitive personal information requiring the highest level of protection against unauthorized access or disclosure.
- Informed Consent: Users must provide explicit, informed consent before their data is collected or processed, with clear explanations of how their information will be used.
- Data Minimization: Only essential health information required for hereditary risk assessment is collected, avoiding unnecessary personal data storage.
2.6.2 Algorithmic Fairness and Bias
- Inclusive Risk Assessment: The rule-based risk detection algorithms must be designed to work equitably across different demographic groups and family structures.
- Transparent Logic: Risk calculation methodologies should be explainable to users, avoiding "black box" decisions that cannot be justified or understood.
- Regular Validation: Risk detection rules should be periodically reviewed by medical professionals to ensure accuracy and prevent misdiagnosis.
2.6.3 User Autonomy and Decision-Making
- Educational Purpose: The system explicitly states that risk alerts are for educational and screening purposes only, not medical diagnoses.
- User Empowerment: The system provides information and recommendations while preserving users' autonomy in healthcare decisions.
- Voluntary Participation: All system usage is voluntary, with clear options to withdraw consent and request data deletion.
2.6.4 Social and Cultural Considerations
- Family Dynamics: The system respects potential cultural sensitivities around hereditary conditions and family health discussions.
- Language Accessibility: Bilingual support ensures equitable access for both Arabic and English speakers in Saudi Arabia.
- Digital Inclusion: Mobile-first design and accessibility features prevent exclusion of users with disabilities or limited technology access.
2.6.5 Professional Responsibility
- Medical Disclaimer: Clear disclaimers indicate that the system complements but does not replace professional medical advice.
- Content Accuracy: All educational materials are medically reviewed to prevent misinformation.
- Referral Integrity: Clinic recommendations are based on objective criteria without commercial influence or bias.
2.6.6 Implementation Ethics
- Transparent Development: The development process maintains transparency about system capabilities and limitations.
- Testing Ethics: User testing follows ethical guidelines with proper consent and data protection.
- Continuous Oversight: Regular ethical reviews ensure the system continues to operate responsibly as it evolves.
These ethical guidelines ensure that Sillah not only meets technical and functional requirements but also operates as a responsible, trustworthy healthcare technology that respects user rights and promotes equitable health outcomes.
