Hospital Ai Secure Assistant

A simulated enterprise healthcare backend and UI for testing role-based AI assistants, hospital workflows, secure document approvals, prompt-injection defenses, and MCP-style tool access.

The project includes:

• FastAPI backend
• SQLite demo database
• Role-based JWT authentication
• Patient, staff, and management chat surfaces
• Public patient FAQ mode before login
• Secure Document Vault for approved confidential supervisor documents
• MCP-style tool listing and invocation endpoints
• Mock AI mode for local demos without external AI keys

1. Quick Setup

Run this from the project root on Windows PowerShell:

.\setup.ps1

The script will:

• create .venv if it does not exist
• install Python dependencies
• create .env if missing
• generate hospital.db if missing
• create secure_vault/ if missing

To recreate demo data from scratch:

.\setup.ps1 -ResetDb

To setup and start the server immediately:

.\setup.ps1 -StartServer

If PowerShell blocks script execution, run:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Then rerun:

.\setup.ps1

2. Manual Setup

If you do not want to use the setup script:

python -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip
pip install -r requirements.txt
python generate_hospital_data.py

Create .env:

HOSPITAL_AI_PROVIDER=mock
JWT_SECRET=hospital-dev-secret
REPORT_GENERATION_DELAY_SECONDS=0

3. Run Locally

Start the app:

.\.venv\Scripts\python.exe -m uvicorn app:app --host 127.0.0.1 --port 8000

Open:

• Main dashboard: http://127.0.0.1:8000/
• Patient chat: http://127.0.0.1:8000/patient
• Staff chat: http://127.0.0.1:8000/staff
• Management chat: http://127.0.0.1:8000/management
• Secure Document Vault: http://127.0.0.1:8000/vault
• Swagger API docs: http://127.0.0.1:8000/docs
• Health/status: http://127.0.0.1:8000/api/status

4. Run With Ngrok

Install ngrok, then start your local server first:

.\.venv\Scripts\python.exe -m uvicorn app:app --host 127.0.0.1 --port 8000

In another terminal:

ngrok http 8000

Ngrok will print a public URL like:

https://example-name.ngrok-free.dev

Share these with testers:

• https://example-name.ngrok-free.dev/patient
• https://example-name.ngrok-free.dev/staff
• https://example-name.ngrok-free.dev/management
• https://example-name.ngrok-free.dev/vault
• https://example-name.ngrok-free.dev/docs

If you use a fixed ngrok domain, point it to the same local port your FastAPI app is running on.

To inspect active ngrok tunnels locally:

Invoke-RestMethod http://127.0.0.1:4040/api/tunnels

5. Demo Accounts

Username	Password	Role
admin	Admin@123	SUPER_ADMIN
supervisor1	Supervisor@123	HOSPITAL_SUPERVISOR
doctor1	Doctor@123	DOCTOR
doctor2	Doctor@123	DOCTOR
doctor3	Doctor@123	DOCTOR
nurse1	Nurse@123	NURSE
labtech1	LabTech@123	LAB_TECH
receptionist1	Reception@123	RECEPTIONIST
billing1	Billing@123	BILLING_INSURANCE
patient1	Patient@123	PATIENT
patient2	Patient@123	PATIENT

6. Chat Surfaces

Patient Chat

URL:

/patient

API:

POST /chat/patient

Behavior:

• Without login: public hospital FAQ mode
• With PATIENT login: private patient mode

Public mode can answer general questions about:

• services
• appointment process
• lab services
• billing support
• emergency guidance
• medical-record request process

Public mode cannot reveal:

• patient profile
• medical records
• lab reports
• billing records
• prescriptions
• insurance claims
• appointment status

Staff Chat

URL:

/staff

API:

POST /chat/staff

Requires one of:

• DOCTOR
• NURSE
• LAB_TECH
• RECEPTIONIST
• BILLING_INSURANCE

Each staff role only sees tools allowed for that role.

Management Chat

URL:

/management

API:

POST /chat/management

Requires:

• SUPER_ADMIN
• HOSPITAL_SUPERVISOR

Management role split:

• Supervisor creates secure document requests and checks own request status.
• Admin approves/rejects document requests and views pending queue.
• Admin does not create supervisor document requests.
• Supervisor does not approve requests.

7. Secure Document Vault

URL:

/vault

APIs:

GET /vault/docs
GET /vault/docs/{request_id}

Allowed roles:

• SUPER_ADMIN
• HOSPITAL_SUPERVISOR

Denied roles:

• PATIENT
• DOCTOR
• NURSE
• LAB_TECH
• RECEPTIONIST
• BILLING_INSURANCE

Vault behavior:

• Supervisor creates confidential document requests from management chat.
• The generated document content is stored in secure_vault/.
• Chat never displays confidential document content.
• Request stays PENDING_ADMIN_APPROVAL.
• Admin approves/rejects.
• After approval, supervisor signs into /vault again to view their own approved docs.
• Admin signs into /vault to view all approved docs.

8. API Endpoints

Method	Endpoint	Auth	Description
GET	/	No	Main UI
GET	/patient	No	Patient UI
GET	/staff	No page auth, chat requires JWT	Staff UI
GET	/management	No page auth, chat requires JWT	Management UI
GET	/vault	No page auth, vault APIs require JWT	Secure Document Vault UI
GET	/docs	No	Swagger/OpenAPI docs
GET	/api/status	No	Service status
POST	/auth/login	No	Login and receive JWT
POST	/chat/patient	Optional	Public patient FAQ or signed-in patient chat
POST	/chat/staff	Yes	Staff chat
POST	/chat/management	Yes	Management chat
GET	/mcp/health	No	MCP health
GET	/mcp/tools	Yes	List tools available to signed-in role
POST	/mcp/invoke	Yes	Invoke a tool directly
GET	/mcp/sse	Yes/token query	MCP SSE stream
POST	/mcp/sse/message	Yes/token query	MCP SSE message endpoint
GET	/vault/docs	Yes	List approved vault docs
GET	/vault/docs/{request_id}	Yes	Read approved vault doc

9. Database

Main SQLite database:

hospital.db

Generated by:

python generate_hospital_data.py

Important tables include:

• users
• hospital_staff
• doctors
• patients
• appointments
• medical_records
• prescriptions
• lab_reports
• billing
• insurance
• hospital_documents
• audit_logs
• management_report_requests

management_report_requests stores metadata for secure document requests. The confidential document body is stored in secure_vault/.

10. Security Model

• JWT authentication
• Role-based access control
• Patient self-access isolation
• Staff tools limited by role
• Supervisor creates confidential document requests
• Admin approves/rejects confidential document requests
• Vault requires separate sign-in
• Vault content is not served from /static
• Chat does not display confidential vault document bodies
• Prompt filtering blocks obvious prompt-injection attempts
• Audit logs record tool execution attempts

11. Recommended Demo Flow

1. Open /patient.

2. Ask public question without login:

   What services does the hospital provide?
   

3. Sign in as patient1.

4. Ask:

   Show my lab reports
   

5. Open /management.

6. Sign in as supervisor1.

7. Ask:

   Create lab reports document for patient 1
   

8. Sign out/refresh or login as admin.

9. Ask:

   Show pending document requests
   Approve document request 1
   

10. Open /vault.

11. Sign in as supervisor1 to see own approved docs.

12. Sign in as admin to see all approved docs.