Skip to content

FULL_STACK.md

Latest commit

 

History

History
282 lines (226 loc) · 6.18 KB

FULL_STACK.md

File metadata and controls

282 lines (226 loc) · 6.18 KB
Raw

MedSecure Full-Stack Application

Project Overview

MedSecure is a HIPAA-compliant medical document summarization platform with:

  • Backend: FastAPI + MongoDB (Python)
  • Frontend: Next.js (JavaScript/React)
  • Security: RBAC, PII masking, encryption

Architecture

┌─────────────────────┐
│   Next.js Frontend  │ (Port 3000)
│   - Upload UI       │
│   - Results Display │
└──────────┬──────────┘
           │ HTTP/JSON
           ▼
┌─────────────────────┐
│   FastAPI Backend   │ (Port 8000)
│   - API Endpoints   │
│   - RBAC Security   │
│   - PII Masking     │
│   - NER Service     │
│   - LLM Summarizer  │
│   - Verification    │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│     MongoDB         │ (Port 27017)
│   - Document Store  │
│   - Summary Cache   │
└─────────────────────┘

Quick Start

Terminal 1: Backend

cd c:\Users\DELL\Medsecure

# Start MongoDB
docker-compose up -d mongo

# Start FastAPI
uvicorn app.main:app --reload --port 8000

Terminal 2: Frontend

cd c:\Users\DELL\Medsecure\frontend

# Install dependencies (first time only)
npm install

# Start development server
npm run dev

Terminal 3: Test

# In backend directory
pytest -v tests/

Accessing the Application

Frontend Features

🎯 Main Upload Page

  • Drag-and-drop file upload
  • Real-time validation
  • Processing indicator
  • Error handling

📊 Results Display

  • Masked Document — PII removed with tags
  • Generated Summary — AI-powered summary
  • Extracted Entities — Medical terms identified
  • Verification Status — Hallucination check result
  • Quality Metrics — Summary statistics

🔐 Security

  • RBAC via X-User header
  • Client-side error handling
  • Secure API communication
  • No sensitive data in localStorage

Backend Endpoints Used

POST /api/v1/summaries

Submit a medical document for processing.

Request:

{
  "text": "Patient John Doe...",
  "document_id": "optional-id"
}

Response:

{
  "summary_id": "507f1f77bcf86cd799439011",
  "masked_text": "Patient [NAME]...",
  "summary": "Patient with...",
  "verified": true,
  "entities": [{"text": "diabetes", "label": "CONDITION"}]
}

GET /api/v1/summaries/{id}

Retrieve a previously processed summary.

Environment Configuration

Backend (.env)

MONGO_URI=mongodb://localhost:27017
MONGO_DB=medsecure
RBAC_EDITOR_USERS=editor@example.com

Frontend (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_USER_EMAIL=editor@example.com

Deployment

Docker Compose (Full Stack)

docker-compose up

Starts:

  • MongoDB on port 27017
  • FastAPI on port 8000
  • Frontend on port 3000

Individual Deployment

Backend (Docker):

docker build -t medsecure-api .
docker run -p 8000:8000 -e MONGO_URI=mongodb://mongo:27017 medsecure-api

Frontend (Docker):

cd frontend
docker build -t medsecure-frontend .
docker run -p 3000:3000 medsecure-frontend

Development Workflow

  1. Backend Changes

  2. Frontend Changes

    • Edit files in frontend/pages/, frontend/components/
    • Next.js reloads automatically
    • Check http://localhost:3000

  3. Adding Features

    • Backend: Add service in app/services/
    • Backend: Add endpoint in app/api/routes.py
    • Frontend: Update lib/api.js and components

Testing

Backend Tests

pytest -v tests/

Security Scan

bandit -r app
pip-audit

Frontend Development

npm run lint
npm run build

File Structure

MedSecure/
├── app/                    # FastAPI backend
├── frontend/              # Next.js frontend
│   ├── pages/
│   │   ├── index.js      # Main upload page
│   │   ├── _app.js
│   │   └── _document.js
│   ├── components/
│   │   ├── Header.jsx
│   │   ├── FileUpload.jsx
│   │   ├── ResultsDisplay.jsx
│   │   └── LoadingSpinner.jsx
│   ├── lib/
│   │   └── api.js        # API client
│   ├── styles/
│   │   └── globals.css   # Tailwind
│   └── package.json
├── docker-compose.yml
├── Dockerfile
└── README.md

Troubleshooting

Frontend can't connect to backend

  1. Check backend is running: http://localhost:8000/docs
  2. Verify NEXT_PUBLIC_API_URL is correct
  3. Check CORS settings in backend if needed
  4. Check browser console for errors

MongoDB connection error

docker-compose up -d mongo
mongosh  # Connect to test

Port already in use

# Frontend
npm run dev -- -p 3001

# Backend
uvicorn app.main:app --reload --port 8001

Node modules issues

cd frontend
rm -rf node_modules package-lock.json
npm install

Next Steps

  1. ✅ Backend API is running
  2. ✅ Frontend is running
  3. Try uploading a test document
  4. Review results
  5. Implement Phase 1-3 enhancements in EXECUTION_PIPELINE.md

Performance Notes

  • Upload: Frontend file reading is instant
  • Processing: Backend pipeline typically 1-3 seconds
  • Display: Results render immediately
  • Scalability: Can optimize with task queue (Celery)

Security Notes

  • All PII is masked on the backend (not frontend)
  • RBAC is enforced via X-User header (implement OAuth2 for production)
  • Encryption keys should be in secure vaults (not .env in production)
  • HTTPS required for production deployment

Support

See individual READMEs: