Overview

ChartChat is a digital health platform that allows patients to view, understand, and interact with their own medical records. It connects to EHR systems, pulls health data into a unified record, and provides an AI-powered chat assistant that answers patient questions based strictly on their own records.

This documentation covers everything about how ChartChat is built, deployed, and maintained — from the patient-facing portal to the backend API, infrastructure, and AI layer.

What's in this documentation

Section	What it covers
Functional	What each feature does from a user perspective — member portal flows, admin portal capabilities
Technical	How each component is built — architecture, configuration, APIs, database, deployment
AI	The AI chat backend — models, retrieval, safety layers, API endpoints, infrastructure

Components

Component	Description	Production	Staging
Member Portal	Patient-facing web app for viewing health records	`https://portal.chartchathealth.com`	`http://dev.chartchathealth.com`
Admin Portal	Internal tool for hospital and system administration	`https://admin.chartchathealth.com`	`https://devadmin.chartchathealth.com`
Server	Node.js backend API with FHIR, auth, and EHR integration	`https://api.chartchathealth.com`	—
AI Tools	FastAPI Python backend — AI chat, record translation, embedding sync	`https://chatapi.chartchathealth.com`	—

Tech Stack

Layer	Technology
Frontend	React, Vite, TypeScript
Backend (API)	Node.js, Express, TypeScript
Backend (AI)	Python 3.12, FastAPI, Uvicorn
LLM	Qwen3-8B — self-hosted via vLLM
Embeddings	BGE-M3 (BAAI) — self-hosted, 1,024-dimensional
Data Model	FHIR R4
Database	PostgreSQL + pgvector extension
Cache	Redis
Infrastructure	nginx, PM2, Jenkins CI/CD, AWS EC2, RDS

Top-Level Folder Structure

chartchat/
├── memberportal/              # Member Portal (Vite/React frontend)
├── packages/
│   ├── agent/                 # AI agent utilities
│   ├── ai-tools/              # AI tooling helpers
│   ├── app/                   # Medplum app package
│   ├── bot-layer/             # Bot Lambda layer
│   ├── ccda/                  # C-CDA document support
│   ├── cdk/                   # AWS CDK infrastructure
│   ├── chartchat-docs/        # Project documentation site (this site)
│   ├── cli/                   # Medplum CLI
│   ├── cli-wrapper/           # CLI wrapper utilities
│   ├── core/                  # Core shared library
│   ├── create-medplum/        # Project scaffolding tool
│   ├── definitions/           # FHIR definitions & schemas
│   ├── docs/                  # Medplum upstream docs
│   ├── dosespot-react/        # DoseSpot e-prescribing React components
│   ├── e2e/                   # End-to-end tests
│   ├── eslint-config/         # Shared ESLint config
│   ├── fhir-router/           # FHIR routing utilities
│   ├── fhirtypes/             # Generated FHIR TypeScript types
│   ├── generator/             # FHIR type & JSON schema generator
│   ├── graphiql/              # GraphiQL explorer
│   ├── health-gorilla-core/   # Health Gorilla integration (core)
│   ├── health-gorilla-react/  # Health Gorilla integration (React)
│   ├── hl7/                   # HL7 v2 parsing
│   ├── mock/                  # Mock FHIR client for tests
│   ├── chartchat-admin/     # Admin Portal (Vite/React frontend)
│   ├── react/                 # Shared React component library
│   ├── react-hooks/           # Shared React hooks
│   └── server/                # Backend API server (Node.js)
├── graphify-out/              # Knowledge graph output
├── postgres/                  # Postgres config/scripts (local dev only)
├── scripts/                   # Dev & build scripts (upstream medplum, not used)
├── terraform/                 # Terraform infrastructure (AWS)
├── Jenkinsfile-memberportal   # CI/CD pipeline definition
├── docker-compose.yml         # Local dev stack
├── turbo.json                 # Turborepo pipeline config
└── tsconfig.json              # Root TypeScript config

Getting Started

Follow these steps in order to get the full stack running locally.

Step 1 — Clone the repository

git clone https://bitbucket.org/chartchat_health/chartchat.git
cd chartchat

Step 2 — Install all dependencies

Run this from the root of the repo. npm workspaces will install dependencies for all packages in one go.

npm install

Step 3 — Build the shared packages

The monorepo has shared packages (core, fhirtypes, react, react-hooks, definitions, etc.) that must be compiled before the apps can run. You have two options:

Option A — Build everything (slow, thorough)

Builds all packages in the entire monorepo including docs.

npm run build

Option B — Build:fast (recommended for daily dev)

Builds only the server, the Medplum app package, and the shared packages they depend on. Much faster than a full build.

npm run build:fast

This builds the following packages (Turborepo resolves the dependency chain automatically):

Package	Description
`@medplum/server`	Backend API server
`@medplum/app`	Medplum app package
`@medplum/core`	Core shared library
`@medplum/fhirtypes`	Generated FHIR TypeScript types
`@medplum/react`	Shared React component library
`@medplum/react-hooks`	Shared React hooks
`@medplum/definitions`	FHIR definitions and schemas

The Member Portal and Admin Portal are not included in build:fast — they have their own install and dev steps below.

Step 4 — Start PostgreSQL and Redis via Docker

The server requires PostgreSQL and Redis to be running before it starts. The easiest way to run them locally is with Docker Compose.

From the root of the repo:

docker-compose up

This starts three services:

Service	Port	Default credentials
PostgreSQL	`5432`	user: `medplum` / password: `medplum`
Redis	`6379`	password: `medplum`
Wiki.js	`3001`	—

Changing the default passwords

Open docker-compose.yml in the root of the repo and update the relevant environment variables:

services:
  postgres:
    environment:
      - POSTGRES_USER=medplum
      - POSTGRES_PASSWORD=medplum   # ← change this

  redis:
    command: redis-server --requirepass medplum  # ← change this

warning

If you change the passwords here, you must also update them in packages/server/medplum.config.json to match, otherwise the server will fail to connect.

Step 5 — Start the Server

cd packages/server
npm run dev

The server starts at http://localhost:8103.

To verify it is running:

curl http://localhost:8103/healthcheck

npm run dev uses tsx watch which hot-reloads on file changes — use this during development.
npm run start runs the compiled dist/ output — use this for production.

Step 6 — Start the Member Portal

Open a new terminal:

cd memberportal
npm install
npm run dev

Opens at http://localhost:3000 (or the next available port if 3000 is already in use).

Step 7 — Start the Admin Portal

Open another terminal:

cd packages/chartchat-admin
npm install
npm run dev

Opens at http://localhost:3000 (or the next available port if 3000 is already in use).

Summary — all commands at a glance

# 1. Clone and install
git clone https://bitbucket.org/chartchat_health/chartchat.git && cd chartchat
npm install

# 2. Build shared packages
npm run build:fast

# 3. Start infrastructure (new terminal)
docker-compose up

# 4. Start server (new terminal)
cd packages/server && npm run dev

# 5. Start Member Portal (new terminal)
cd memberportal && npm install && npm run dev

# 6. Start Admin Portal (new terminal)
cd packages/chartchat-admin && npm install && npm run dev

Internal Tools

Tool	URL
Jenkins CI/CD	`https://jenkins.chartchathealth.com`
Wiki	`https://wiki.chartchathealth.com`

Architecture Diagram

┌─────────────────┐     ┌─────────────────┐
│  Member Portal  │     │  Admin Portal   │
│  (Vite/React)   │     │  (Vite/React)   │
└────────┬────────┘     └────────┬────────┘
         │                       │
         └──────────┬────────────┘
                    │ HTTPS
         ┌──────────▼────────────┐
         │       Server          │
         │  (Node.js / Express)  │
         └──────┬────────┬───────┘
                │        │
    ┌───────────▼──┐  ┌──▼────────────────┐
    │  PostgreSQL  │  │    AI Tools        │
    │   + Redis    │  │  (FastAPI/Python)  │
    └──────────────┘  └──────┬────────────┘
                             │
                ┌────────────▼────────────┐
                │   LLM EC2 (g5.xlarge)   │
                │  LLM: Qwen3-8B (vLLM)  │
                │  Embed: BGE-M3 (BAAI)   │
                └─────────────────────────┘

What's in this documentation​

Components​

Tech Stack​

Top-Level Folder Structure​

Getting Started​

Step 1 — Clone the repository​

Step 2 — Install all dependencies​

Step 3 — Build the shared packages​

Option A — Build everything (slow, thorough)​

Option B — Build:fast (recommended for daily dev)​

Step 4 — Start PostgreSQL and Redis via Docker​

Changing the default passwords​

Step 5 — Start the Server​

Step 6 — Start the Member Portal​

Step 7 — Start the Admin Portal​

Summary — all commands at a glance​

Internal Tools​

Architecture Diagram​