Proxy Smart -- Documentation ​

Comprehensive documentation for the Proxy Smart platform: a stateless FHIR proxy with OAuth 2.0, SMART App Launch 2.2.0, and an intelligent admin interface.

Platform Overview ​

Proxy Smart sits between SMART apps and FHIR servers, handling authentication and authorization without storing clinical data. The platform includes 6 frontend apps, an MCP server, and a shared component library.

Architecture ​

┌─────────────────────────────────────────────────────────────┐
│                      Frontend Apps                           │
│  Patient Portal │ Consent │ DTR │ Patient Picker │ Admin UI │
│                      SMART DICOM Template                   │
│                                                             │
│  All built with @proxy-smart/shared-ui (SmartAppShell)      │
└──────────────────────────┬──────────────────────────────────┘
                           │ SMART App Launch 2.2.0
┌──────────────────────────▼──────────────────────────────────┐
│                    Proxy Smart Backend                        │
│  Elysia/Bun │ OAuth Proxy │ FHIR Proxy │ MCP Server          │
└──────────┬──────────┬──────────┬────────────────────────────┘
           │          │          │
     ┌─────▼───┐ ┌────▼────┐ ┌──▼───────┐
     │Keycloak │ │FHIR R4  │ │Orthanc   │
     │  (IdP)  │ │Server(s)│ │(DICOMweb)│
     └─────────┘ └─────────┘ └──────────┘

Apps ​

External Apps (separate repositories) ​

Deployment: External apps deploy independently from their own CI pipelines. Each app builds its static assets and pushes them into a shared apps_static Docker volume mounted at /app/backend/public/apps. The backend serves them at /apps/{app-name}/. This decouples app release cycles from the core platform.

Key Features ​

• SMART App Launch 2.2.0 -- Full OAuth 2.0 with PKCE, JWT validation, scope-based access control, refresh token rotation
• Stateless FHIR Proxy -- No clinical data stored; requests pass through to your FHIR servers
• Shared UI Library -- @proxy-smart/shared-ui with SmartAppShell, design system, hooks
• Admin Dashboard -- React UI for managing apps, users, servers, scopes, and identity providers
• MCP Server -- Streamable HTTP endpoint at /mcp exposing all admin tools
• Consent Management -- Patient consent app for authorization flows
• DTR App -- Da Vinci Documentation, Templates & Rules
• Medical Imaging -- DICOMweb proxy (QIDO-RS & WADO-RS) with Cornerstone3D viewer
• Access Control -- Physical access integrations (Kisi, UniFi Access)
• Docker & CDK -- Docker Compose for dev/staging, AWS CDK for production (ECS Fargate, RDS, WAF)

Documentation ​

Apps (in this repo) ​

• Admin UI -- Platform administration
• Patient Picker -- Patient selection for standalone launch
• SMART DICOM Template -- Imaging algorithm starter kit

Apps (external repositories) ​

• Patient Portal -- Health records, imaging, IPS viewer
• Consent Manager -- FHIR Consent resource management
• DTR / Prior Auth -- Da Vinci DTR workflow

Shared UI ​

• Shared UI Library -- @proxy-smart/shared-ui, SmartAppShell, design system, hooks

Admin UI ​

• Dashboard Overview -- System overview and health monitoring
• User Management -- Healthcare users and FHIR associations
• SMART Apps -- Application registration and management
• FHIR Servers -- Server configuration and monitoring
• Scope Management -- FHIR permissions and templates
• Access Control -- Physical door management (Kisi, UniFi Access)
• Monitoring & Observability -- OAuth, FHIR health, consent, and audit monitoring

MCP ​

• MCP HTTP Server -- Streamable HTTP endpoint architecture and usage
• Backend API Tools -- Auto-generated tools from Elysia routes
• Backend MCP HTTP Client -- HTTP-based MCP client
• Backend MCP Streamable Client -- Streamable HTTP MCP client

Imaging & DICOMweb ​

• DICOMweb Proxy -- QIDO-RS & WADO-RS proxy endpoints, authentication, and deployment
• Patient Portal Imaging -- ImagingStudy cards, Cornerstone3D viewer, and DICOMweb client library

SMART on FHIR ​

• SMART 2.2.0 Implementation Checklist -- Spec compliance status

Guides ​

• Deployment -- Docker Compose, production, AWS CDK
• Environment Variables -- Configuration reference
• Version Management -- Branching, versioning, and releases

Additional Resources ​

• SMART App Launch Framework
• FHIR R4 Specification
• OAuth 2.0 RFC
• OpenID Connect