Project Documentation
System analysis, design, implementation notes, and evaluation plan for MediSecure AI. This record distinguishes what is visible in the current codebase from what remains proposed or requires verification.
Developed by Anyoha Elvis Chidumebi, Computer Science Student · Supervisor: Dr. Ugo Nwankwo · HOD: Prof. Arinze Nwaeze
Project Overview
MediSecure AI is an existing Vite, React, and TypeScript web application for demonstrating a privacy-aware medical-image decision-support workflow in a Nigerian academic context. The current repository contains public pages, role-oriented dashboards, Blink database access wrappers, client-side privacy utilities, offline/PWA mechanisms, and a demo inference mode.
It is important to separate the working interface from the complete research system described in some product copy. The inspected repository does not contain model weights, a training service, a federated coordinator, a custom backend, or automated behavioural tests. Those areas are labelled PARTIALLY IMPLEMENTED, PROPOSED, or PENDING VERIFICATION below.
Academic integrity rule: claims about hospitals, patients, model performance, certifications, deployments, security controls, and clinical usefulness are not treated as implemented unless they can be verified from code or supplied evidence.
Introduction
1.1 Background
Medical image analysis can support clinicians by highlighting patterns for further review. Health data is sensitive, institutions may not be able to centralise patient images, and a research prototype must not be presented as a certified medical device. MediSecure AI explores a privacy-aware interface around chest X-ray classification and federated-learning concepts.
1.2 Motivation
The motivation is to explore how institutions could collaborate on machine-learning research while retaining local control over source data. This is an academic and architectural motivation; the repository does not prove a live hospital deployment or a completed clinical study.
1.3 Objectives
- Provide a role-oriented web interface for a medical AI research prototype.
- Represent users, cases, screenings, hospital nodes, training rounds, privacy settings, models, and audit events.
- Demonstrate client-side privacy utilities such as PII stripping, noise mechanisms, and RDP-style accounting.
- Provide explicit consent, medical-disclaimer, and research-prototype messaging.
- Identify the implementation gaps that must be addressed before real deployment.
1.4 Methodology Summary
The most defensible description of the visible development approach is iterative Agile-style development: requirements, planning, design, development, testing, review, refinement, deployment, and maintenance. Formal sprint records were not found in the repository.
1.5 Results / Expected Results
DOCUMENTED The current result is a working research-oriented web interface with demo-mode flows and typed data access. Model performance, clinical usefulness, federated training performance, and privacy guarantees are not verified results in this repository.
1.6 Limitations and Scope
The verified scope is the existing frontend, Blink SDK data access, UI-level role gating, client-side privacy helpers, legal/safety pages, and offline/PWA mechanisms. Training, inference infrastructure, secure node transport, server enforcement, and automated behavioural testing remain incomplete or unverified.
Literature Review
2.1 Introduction
This review is structured around the literature themes named by the existing About page. The abbreviated references below require bibliographic verification before inclusion in a final thesis.
| Author / year | Study / technology | Method / key relevance | Limitation for this project |
|---|---|---|---|
| Abadi et al. (2016) | Deep learning with differential privacy | DP-SGD background | Full citation and exact application require verification |
| McMahan et al. (2017) | Communication-efficient learning from decentralised data | FedAvg background | No executable aggregator in current repository |
| Kaissis et al. (2020) | Privacy-preserving federated learning in medical imaging | Healthcare privacy context | External source must be checked |
| Sheller et al. (2020) | Federated learning in medicine | Multi-institution collaboration context | External source must be checked |
| Beaulieu-Jones et al. (2019) | Privacy-preserving distributed deep learning | Distributed learning comparison | External source must be checked |
| Rieke et al. (2020) | Future of digital health with federated learning | Digital health context | External source must be checked |
| Kermany et al. (2018) | Medical image classification dataset / deep learning | Research dataset context | Dataset provenance and license require verification |
2.2 Artificial Intelligence in Medical Diagnosis
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.3 Machine Learning in Healthcare
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.4 Deep Learning
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.5 Medical Image Classification
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.6 Chest X-ray Analysis
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.7 ResNet-50
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.8 Federated Learning
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.9 FedAvg
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.10 Differential Privacy
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.11 DP-SGD
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.12 Privacy-Preserving Machine Learning
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.13 Secure Communication in Healthcare
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.14 Healthcare Data Protection
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.15 Nigerian Data Protection Context
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.16 Existing Related Systems
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.17 Comparative Analysis
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.18 Research Gap
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.19 Conceptual Framework
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
2.20 Chapter Summary
This required subsection should be expanded using verified scholarly sources. In the current application, the related concept is represented in UI copy, domain types, or client utilities rather than a complete research implementation. Mark claims about performance, novelty, deployment, regulation, or clinical usefulness as requiring verification.
Methodology & System Analysis
3.1 Software Development Methodology
Agile Software Development is suitable because the project combines changing interface requirements, AI experimentation, continuous testing, security refinement, and incremental implementation. Scrum should not be claimed unless separate Scrum evidence exists.
| Stage | Activities | Deliverables | Advantages / limitations |
|---|---|---|---|
| Requirements | Identify roles, workflows, privacy and safety needs | Requirement list | Keeps scope visible; may change during research |
| Planning | Prioritise increments and risks | Iteration plan | Supports incremental delivery; requires discipline |
| Design | Design routes, entities, diagrams and responsive UI | Design specification | Finds inconsistencies early |
| Development | Implement React modules, SDK wrappers and utilities | Working increments | Fast feedback; partial features must be labelled |
| Testing | Run static checks and planned behavioural tests | Test evidence | Current behavioural suite is pending |
| Review / refinement | Inspect preview, claims, links and security boundaries | Refined release | Reduces unsupported claims |
| Deployment / maintenance | Publish, monitor, update and document | Published prototype | Real deployment requires governance |
3.2 Existing System Analysis
The existing system analysed here is a conceptual centralised medical-data workflow, not a named hospital deployment. In such a workflow, patient images and clinical metadata may be transferred to a shared server for training or analysis. Potential weaknesses include central exposure, data ownership conflicts, institutional barriers, access-control complexity, and regulatory risk.
3.3 Proposed High-Level Model
The proposed model keeps source images at a local node, performs local model operations, applies a privacy mechanism to an update, and sends an intended protected update to a coordinator for aggregation. In the current repository, these stages are represented by domain fields and administrative screens; executable node/coordinator services are proposed or pending verification.
3.4 Analysis and Justification
The proposed architecture is justified as a privacy-aware research direction, not as proof that the current frontend executes federated training. The distinction allows the academic report to describe design intent while remaining consistent with the codebase.
System Design
4.1 Introduction
The design describes the current user interface and data model while identifying proposed backend and machine-learning components. All diagram labels use the same terminology: user, interface, application layer, local node, ResNet-50, DP-SGD, protected update, coordinator, FedAvg, and global model.
4.2 Objectives of the System Design
The design prioritises role separation, responsive access, explicit medical safety language, privacy-aware data presentation, auditability, and a clear boundary between demo outputs and verified results.
4.3 Control Centre Design
PARTIALLY IMPLEMENTED The admin area contains dashboard, federated training, nodes, models, privacy, users, audit, and settings pages. A complete operational control centre with live orchestration, certificate management, transport monitoring, and real-time alerts is PROPOSED.
4.4 Interface Specifications
| Interface | Purpose | Users | Inputs | Outputs | Status |
|---|---|---|---|---|---|
| Login | Access the application | All roles | Email and role | Session or error | PARTIALLY IMPLEMENTED |
| Patient screening | Collect symptom responses | Patient / provider | Question responses | Risk level / recommendation | IMPLEMENTED |
| Medical image | Capture or select an image | Provider | Camera frame / image | Preview blob / data URL | PARTIALLY IMPLEMENTED |
| Prediction result | Display decision-support output | Provider / patient | Case/result record | Label, confidence, summaries | PARTIALLY IMPLEMENTED |
| Audit logs | Review platform events | Auditor / admin | Search and severity filters | Read-only event list | IMPLEMENTED |
| Documentation | Explain status and design | All users | Navigation | Academic chapters and diagrams | IMPLEMENTED |
4.5 Data Dictionary — Verified Application Tables
| Table | Key fields | Purpose | Status |
|---|---|---|---|
| users | id, email, full_name, role, is_active, consent fields | Users and roles | IMPLEMENTED |
| federated_nodes | id, name, institution, status, dataset_size, privacy / TLS metadata | Displayed node records | IMPLEMENTED |
| training_rounds | id, round_number, status, quorum, metrics, epsilon | Round metadata | IMPLEMENTED |
| privacy_configs | id, config_name, epsilon, delta, noise_multiplier | Privacy configurations | IMPLEMENTED |
| global_models | id, version, architecture, metrics, model_hash | Model registry metadata | IMPLEMENTED |
| cases | id, provider_id, patient_id, diagnosis, confidence, findings | Case/report records | IMPLEMENTED |
| symptom_screenings | id, user_id, responses, score, risk_level | Screening records | IMPLEMENTED |
| audit_logs | id, timestamp, event_type, severity, details | Audit events | IMPLEMENTED |
| notifications | id, user_id, message, type, is_read | Notifications | IMPLEMENTED |
| contact_messages | id, name, email, subject, message | Contact submissions | IMPLEMENTED |
4.6 Algorithms and Mathematical Specifications
DOCUMENTED The source contains Gaussian and Laplace noise helpers, RDP curve and conversion helpers, PII stripping, age binning, DP count release, and budget tracking. A production DP-SGD training loop, executable FedAvg coordinator, and model evaluation pipeline are not present.
4.7 Variables Used in Programming
| Variable | Module / source | Purpose | Status |
|---|---|---|---|
| role | auth / routes | Selected or stored user role | IMPLEMENTED |
| diagnosis / confidence | case and demo types | Decision-support result fields | PARTIALLY IMPLEMENTED |
| epsilon / delta | dp.ts and privacy types | Privacy accounting parameters | PARTIALLY IMPLEMENTED |
| roundNumber / quorum | training types | Round progress metadata | IMPLEMENTED |
| globalModel / local update | design terminology | Federated model concepts | PROPOSED |
Software Testing & Evaluation
TypeScript and ESLint are available as static checks. No dedicated unit, integration, end-to-end, model-evaluation, federated-training, privacy-accountant, performance, or user-acceptance test suite was found. Behavioural outcomes must remain PENDING EXECUTION.
| Test ID | Area | Test case | Expected result | Actual / status |
|---|---|---|---|---|
| T01 | Build | TypeScript and ESLint check | No errors | PENDING TESTING |
| T02 | Authentication | Register, login, logout, role redirect | Correct access and error states | PENDING TESTING |
| T03 | Database | Create/list/update domain records | Records persist and normalise | PENDING TESTING |
| T04 | Image workflow | Capture or select image | Preview and validation work | PENDING TESTING |
| T05 | AI | Run demo and configured API path | Correct source/status label | PENDING TESTING |
| T06 | Privacy | Run utilities and budget tracking | Expected mathematical outputs | PENDING TESTING |
| T07 | Responsive UI | Review narrow phone and desktop layouts | No blocking overflow | PENDING TESTING |
| T08 | Security | Attempt unauthorised route and invalid input | Access denied / validation shown | PENDING TESTING |
Implementation & Documentation
| Module ID | Module | Purpose / evidence | Implementation status |
|---|---|---|---|
| M01 | Authentication | Email lookup, registration, local session, role and approval gating. | PARTIALLY IMPLEMENTED |
| M02 | User Management | User listing, activation/deactivation, and account settings. | IMPLEMENTED |
| M03 | Patient Management | Patient dashboard, screening records, cases, and emergency snapshot UI. | PARTIALLY IMPLEMENTED |
| M04 | Medical Image Capture | Browser camera capture and image preview; upload/inference pipeline incomplete. | PARTIALLY IMPLEMENTED |
| M05 | AI Inference | Demo payload plus optional external inference API contract. | PARTIALLY IMPLEMENTED |
| M06 | ResNet-50 Model | Model metadata and demo labels; weights/training code absent. | DOCUMENTED |
| M07 | Differential Privacy | Noise, RDP-style accounting, PII stripping, and budget utilities. | PARTIALLY IMPLEMENTED |
| M08 | Federated Learning | Node, round, quorum, privacy, and model data structures. | PARTIALLY IMPLEMENTED |
| M09 | FedAvg Aggregation | Aggregation method stored as metadata; coordinator absent. | PROPOSED |
| M10 | Secure Communication | TLS/gRPC fields represented; transport not present. | PENDING VERIFICATION |
| M11 | Audit Logging | Typed audit CRUD and client event logging. | IMPLEMENTED |
| M12 | Reporting | Case/report screens and patient-facing summaries. | PARTIALLY IMPLEMENTED |
| M13 | Control Centre | Admin pages for nodes, rounds, models, privacy, users and audits. | PARTIALLY IMPLEMENTED |
Technology and platform
| Technology | Category | Purpose | Status |
|---|---|---|---|
| React + TypeScript | Frontend | Application UI and type-safe modules | IMPLEMENTED |
| Vite + TanStack Router | Platform | Build and file-based routing | IMPLEMENTED |
| Tailwind CSS | UI styling | Responsive design tokens and utilities | IMPLEMENTED |
| Blink SDK | Data platform | Typed database access and project client | IMPLEMENTED |
| ResNet-50 / PyTorch / Opacus | AI / ML | Named model design and documentation | PENDING VERIFICATION |
| FedAvg / DP-SGD | Federated privacy | Domain terminology and proposed architecture | PARTIALLY IMPLEMENTED |
| gRPC / mTLS / X.509 | Transport security | Schema/documentation fields | PENDING VERIFICATION |
Security separation
Implemented or visible: route-level role redirects, approval gating, consent fields, audit event writes, PII stripping helpers, app-lock UI, legal pages, and offline state handling.
Recommended / pending verification: password hashing and verification, secure server sessions, server-enforced authorisation, row-level security, actual DICOM sanitisation, mTLS, private CA, certificate revocation, encryption-at-rest, backup/recovery, and threat-model testing.
Changeover to the System
MediSecure AI is a research prototype. The repository does not establish that it replaces a live hospital information system, so a legacy migration claim would be inaccurate.
Recommended strategy: preparation, pilot, training, acceptance testing, phased deployment, monitoring, and rollback capability. Any future clinical use requires independent validation, governance, and applicable regulatory review.
Project Summary
MediSecure AI currently provides a structured research-oriented web interface and data model for a privacy-aware medical AI concept. It presents roles, cases, screenings, model metadata, privacy metrics, audit events, and offline/PWA support.
The academic boundary is explicit: the repository supports the interface and several client-side utilities, while model training, federated execution, secure node transport, server-side authentication enforcement, and formal experimental evaluation remain incomplete or unverified.
MediSecure AI is a research and decision-support prototype. It does not replace qualified medical professionals. AI outputs must be clinically reviewed before decisions are made. No clinical certification or regulatory approval is claimed.