Smart Patient Care Management System – Implementation Guide

Backend (FastAPI) Implementation Steps

1. Project bootstrap

   • Created the backend/ directory, virtual environment helpers, requirements.txt, and pyproject.toml.
   • Declared dependencies such as FastAPI, SQLAlchemy, passlib (bcrypt), structlog, databases, and pytest.

2. Configuration and logging

   • Implemented environment-driven settings in app/core/config.py using pydantic-settings.
   • Added structured logging with request correlation IDs in app/core/logging_config.py.
   • Registered shared middleware (CORS, gzip, trusted hosts, request logging) in app/core/middleware.py.

3. Security layer

   • Built JWT utilities and password hashing in app/core/security.py.
   • Added dependency helpers in app/core/dependencies.py for database sessions and role-based guards.

• Centralized domain exceptions plus FastAPI handlers in app/core/exceptions.py and app/core/error_handlers.py.

4. Database models and schemas

   • Defined SQLAlchemy models for users, patients, nurse calls, feedback, and audit events under app/models/.
   • Created matching Pydantic schemas in app/schemas/ for request/response validation.
   • Configured the async session factory and initialization helpers in app/db/session.py and app/db/init_db.py.

5. Service layer

   • Wrote business logic modules (app/services/) for authentication, user provisioning, nurse-call workflow (create, acknowledge, resolve, escalate), feedback processing (submit, sentiment score, review), audit logging, and profile persistence in a JSON document store.
   • Implemented an in-memory event bus (app/core/events.py) to publish nurse-call and feedback events for future real-time subscribers.

6. API layer

   • Exposed REST endpoints across routers in app/api/v1/endpoints/:
     • /auth – login, token issuance, current user introspection.
     • /patients – list patients, read the current patient record tied to the authenticated user.
     • /nurse-calls – submit patient calls, list active queues, acknowledge/resolve/escalate, patient-specific history.
     • /feedback – submit feedback, list open items for clinicians, mark reviewed.
     • /profiles – read/update preference documents stored in JSON.
     • /health – liveness/readiness checks for observability.
   • Registered the routers in app/api/v1/api.py and finalised the FastAPI app factory in app/main.py.

7. Seeding and tests

   • app/db/init_db.py creates tables, seeds default users (patient, nurse, clinician, admin), and populates user profile documents.
   • Async integration tests (backend/tests/test_use_cases.py) validate the “Respond to Nurse Call” and “Submit Feedback” flows.
   • Verified with python -m pytest, ensuring the API meets the core use-case requirements.

Frontend (React + Vite) Implementation Steps

1. Scaffold

   • Generated the Vite React setup inside frontend/spcms-ui/.
   • Added TypeScript configuration (tsconfig.json, tsconfig.node.json), vite.config.ts, and .env.example exposing VITE_API_URL.

2. Shared utilities

   • Implemented Axios API client (src/api/client.ts) with token injection and unauthorized handler.
   • Built an authentication context (src/context/AuthContext.tsx) that stores user info, persists JWT tokens, and exposes a custom hook (src/hooks/useAuth.ts).
   • Delivered UI helpers (layout, protected route guard, metric cards, status pills) for reuse across pages.

3. Routing and layout

   • Defined routing rules in src/App.tsx, enforcing role-based access for patient, nurse, clinician, and admin personas.
   • Created a top navigation layout (src/components/Layout.tsx) that displays user identity, role, and logout action.

4. Feature pages

   • Patient portal (src/pages/PatientPortal.tsx): shows room/risk metrics, lets patients submit nurse calls and experience feedback, and lists recent call status.
   • Nurse command center (src/pages/NurseCommand.tsx): presents the active queue with actions to acknowledge, resolve, and escalate calls, pulling data from the backend every few seconds.
   • Clinical insights (src/pages/ClinicalInsights.tsx): lists new feedback with sentiment scores; clinicians can mark feedback as closed or keep it in review.
   • Profile page (src/pages/ProfilePage.tsx): allows any user to edit quick actions and notification channels stored in the JSON document store.
   • Supporting pages include LoginPage for authentication and NotFound for unmatched routes.

5. Build and verification

   • Installed dependencies with npm install; optionally ran npm audit fix --force to address advisory warnings.
   • Confirmed a clean production build using npm run build.
   • During development, npm run dev serves the UI at http://localhost:5173.

Step-by-Step Usage

1. Backend

   cd backend
   python -m venv .venv # Once
   .\.venv\Scripts\activate
   pip install -r requirements.txt # Once
   uvicorn app.main:app --reload

2. Frontend

   cd frontend/spcms-ui
   npm install # Once 
   cp .env.example .env   # edit VITE_API_URL if the backend runs elsewhere, Once
   npm run dev # default port 5173
   npm run dev # if you want multiple clients to test end-to-end, open another terminal, the next ports will be 5174, 5175

3. Accounts for testing

   • Patient portal: patient.alvarez / PatientPortal!23
   • Patient portal (additional sample): patient.nguyen / PatientPortal!45
   • Nurse command center: nurse.johnson / NurseCommand!23
   • Clinician insights: clinician.tan / ClinicianInsight!23
   • Clinician insights (additional sample): clinician.singh / ClinicianInsight!45
   • Administrator: admin / 123

4. Testing

   • Run automated backend tests: python -m pytest
   • Manual walkthroughs are documented in docs/testing.md

Supporting Documentation

• docs/solution_design.md – shows alignment with the architecture decisions from Assignments 1–3.
• docs/prompts.md – records the primary prompts used to generate code.
• docs/runbook.md – provides operational guidance for running demos.
• docs/use_cases.md and docs/demo_script.md – map functionality to use cases and outline demo steps.