Proxy Smart

A stateless proxy that adds OAuth 2.0 and SMART App Launch authorization to existing FHIR servers.

Quick Start • Features • Architecture • Documentation • Discord

---

What is Proxy Smart?

Proxy Smart sits between your SMART apps and FHIR servers, handling authentication and authorization. It doesn't store any clinical data — requests pass through to your existing FHIR servers, and the proxy manages OAuth flows and access control.

You provide	Proxy Smart handles
A FHIR server (HAPI FHIR, Microsoft FHIR Server, AWS HealthLake, etc.)	SMART App Launch 2.2.0 flows
Keycloak (included in Docker setup)	OAuth 2.0 authorization & token management
Your SMART apps	Scope-based access control & FHIR proxying

Quick Start

Requirements: Node.js ≥18, Bun ≥1.0, Docker

# Clone the repository
git clone https://github.com/max-health-inc/proxy-smart.git
cd proxy-smart

# Start everything
bun docker:dev
bun install
bun run dev

Then open:

Service	URL
Admin UI	http://localhost:5173
Backend API	http://localhost:8445
Keycloak	http://localhost:8080

Features

🔐 Stateless FHIR Proxy

No clinical data in the proxy means a smaller attack surface, simpler compliance (HIPAA, GDPR), easy horizontal scaling, and less infrastructure to manage. Audit logging for access patterns and OAuth flows is available when needed.

🏥 SMART App Launch 2.2.0

Full implementation of the SMART App Launch specification — apps that follow the standard work out of the box. OAuth 2.0 with PKCE, JWT validation, scope-based access control, refresh token rotation, and enterprise SSO via SAML 2.0 and OIDC.

🖥️ Admin Dashboard

Built-in React admin UI for managing SMART apps, FHIR server connections, users, and scopes — no manual config editing required.

🤖 AI Assistant & MCP Server

Built-in AI assistant with RAG for documentation queries, exposed via an MCP server for programmatic integration with AI tools.

Layer	Protocol	What
Internal tools	Function calling (AI SDK)	Elysia routes called in-process by the built-in AI assistant
Generated MCP server	MCP Streamable HTTP	Python FastMCP server auto-generated from the backend OpenAPI spec
External MCP servers	MCP Streamable HTTP / SSE	User-configured third-party servers (GitHub, Pylance, custom)

🐳 Docker-Ready

One-command development and production deployments with Docker Compose, including mono-container and multi-container options.

Architecture

SMART App → Proxy Smart → FHIR Server
                ↓
            Keycloak (OAuth)

graph TB
    subgraph Clients
        A[Admin UI]
        B[SMART Apps]
    end
  
    subgraph "Proxy Smart (Bun/Elysia)"
        D[FHIR Proxy]
        E[OAuth Endpoints]
        F[WebSocket]
        G[AI Assistant]
    end
  
    subgraph Identity
        H[Keycloak]
        I[(PostgreSQL)]
    end
  
    subgraph "FHIR Servers"
        K[HAPI FHIR]
        L[Other FHIR]
    end
  
    A --> D
    A --> F
    B --> E
    B --> D
  
    E --> H
    D --> H
    H --> I
  
    D --> K
    D --> L
    
    G -.-> |OpenAI| X((API))

Loading

Workspaces

Workspace	Description
backend/	Elysia API server, FHIR proxy, OAuth endpoints
ui/	React admin dashboard
consent-app/	Patient consent management UI
dtr-app/	Documentation, Templates & Rules (DTR) app
shared-ui/	Shared React components and utilities
infra/	AWS CDK infrastructure
mcp-server/	Generated Python MCP server

Tech Stack

Layer	Technologies
Backend	Bun, Elysia, TypeScript
Frontend	React 19, Vite, Tailwind CSS
Identity	Keycloak + PostgreSQL
Testing	Vitest, Playwright
Infra	Docker, AWS CDK

PostgreSQL only stores user/config data. Clinical data stays on your FHIR servers.

Documentation

Getting Started SMART 2.2.0 Implementation Status Admin UI Dashboard User Management SMART Apps FHIR Servers Scope Management

Technical Version Management AI & MCP MCP HTTP Server MCP Integration Backend API Tools

Docker

# Development (mono container)
bun run docker:dev
# → http://localhost:8445/webapp/

# Production (separate containers)
bun run docker:prod
# → Frontend: http://localhost:5173
# → Backend: http://localhost:8445

All Docker commands

Command	Description
bun run docker:dev	Start dev containers
bun run docker:dev:build	Build and start
bun run docker:dev:down	Stop
bun run docker:dev:logs	View logs
bun run docker:prod	Start prod containers
bun run docker:prod:build	Build and start
bun run docker:prod:down	Stop
bun run docker:prod:logs	View logs
bun run docker:backend	Backend only
bun run docker:ui	UI only
bun run docker:mono	Monolithic

Roadmap

Current: v0.0.2-alpha — Working toward SMART App Launch 2.2.0 compliance.

Milestone	Goal
v0.0.5-beta	PKCE, v2 scope syntax, token introspection
v0.1.0	Full SMART 2.2.0 compliance
v1.0.0	Production ready

See the implementation checklist for details.

Branching Strategy

Branch	Purpose
main	Production releases (auto-tagged)
test	Beta releases (-beta suffix)
develop	Alpha releases (-alpha suffix)
dev/*	Feature branches (no PR required)

Contributing

1. Fork the repo
2. Create a branch (dev/your-feature)
3. Make changes with tests
4. Submit PR

See CONTRIBUTING.md for guidelines.

License

Dual licensed:

• AGPL v3 — open source / non-commercial use
• Commercial license — available for proprietary use

See LICENSE-DUAL.md for details.

Support

• 🤖 AI Assistant (built-in)
• 💬 Discord
• 📖 Documentation
• 🐛 GitHub Issues

---

SMART App Launch • FHIR R4 • Keycloak