Skip to content
OHDSIPublic

About

A complete reimplementation of OHDSI ATLAS for cohort definition and analysis, built with Vue 3 and TypeScript.

Resources

Stars

13 stars

Watchers

3 watching

Forks

Latest commit

 

History

360 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ATLAS v3.0

Unit Tests E2E Tests Lint & Type Check Coverage

A complete reimplementation of OHDSI ATLAS for cohort definition and analysis, built with Vue 3 and TypeScript.

Overview

ATLAS v3.0 is a reimplementation of OHDSI ATLAS with a focus on:

  • Modern web technologies (Vue 3, TypeScript, Vuetify 3)
  • Improved user experience and performance
  • Comprehensive test coverage
  • Modular plugin architecture
  • Multi-language support

Features

Core Functionality

  • Cohort Builder: Define and manage patient cohorts with complex criteria
  • Concept Search: Search and browse OMOP CDM concepts
  • Concept Sets: Create and manage reusable concept sets
  • Data Sources: Visualize CDM data with interactive reports and charts
  • Authentication: Secure login with JWT-based authentication
  • Internationalization: Multi-language support with dynamic translation loading

Plugin System

Extensible architecture allowing custom plugins to add new features and integrations.

Technology Stack

  • Frontend Framework: Vue 3.5+ (Composition API)
  • UI Components: Vuetify 3.5+ (Material Design)
  • Language: TypeScript 5.9+ (strict mode)
  • State Management: Pinia 2.1+
  • Routing: Vue Router 4.2+

ATLAS v3.0 uses hash-based client routing. Deep links and callback UI URLs should use the #/... form (for example https://localhost/atlas/#/cohorts or https://localhost/atlas/#/oauth/callback).

  • Charting: ECharts 6.0+ with vue-echarts
  • Validation: Zod (runtime validation)
  • Build Tool: Vite 7.3+
  • Backend: WebAPI 3.0 (Java 21, Spring Boot 3.5)
  • Cache: TrexSQL (DuckDB-backed query cache, loaded as a WebAPI plugin)

Setup

A working ATLAS v3.0 deployment has three independent components:

  • A relational database holding the WebAPI schema, the OMOP CDM schemas you want to analyse, and any results schemas. PostgreSQL is the simplest choice and the one the development docker-compose.yml ships with; Microsoft SQL Server, Oracle, Amazon Redshift, and Snowflake are all supported by WebAPI.
  • The WebAPI service — a Java/Spring application that exposes the REST endpoints ATLAS talks to, executes cohort SQL against the configured CDM sources, and runs Flyway migrations against its own schema on first boot.
  • The ATLAS v3.0 frontend — a Vue 3 single-page application, served either by the Vite development server or as a static bundle behind a reverse proxy.

ATLAS v3.0 requires WebAPI v3.0. The 2.x line of WebAPI that earlier ATLAS releases use — and that ships with OHDSI Broadsea — is not compatible. WebAPI v3.0 is developed on the master branch; the older webapi-3.0 branch is no longer updated. docker-compose.yml runs the released ohdsi/webapi:3.0.0 image; the development docker-compose.dev.yml builds on ghcr.io/ohdsi/webapi:dev.

Prerequisites

  • Docker and Docker Compose v2 (the fastest path), or for native installs: PostgreSQL 12+, JDK 21, Maven 3.9+, Node.js 20.19+ (or 22.12+) and npm, plus Caddy to serve the prebuilt frontend.
  • Git.
  • Roughly 4 GB of free disk for container images and the WebAPI Flyway baseline.
  • A WebAPI build from the v3.0 line: the released image ohdsi/webapi:3.0.0, the development image ghcr.io/ohdsi/webapi:dev, or a local build of the master branch.

Quick start (Docker Compose, recommended for evaluation)

The repository ships a docker-compose.yml that runs the released ATLAS v3.0.0 and WebAPI v3.0.0 images: Postgres with the Eunomia demo database, WebAPI, a database initialiser, and the frontend behind Caddy with a self-signed certificate. Nothing is built locally:

git clone https://github.com/OHDSI/Atlas3.git
cd Atlas3
docker compose up

The first boot takes a few minutes while WebAPI runs Flyway migrations and the atlasdb/ scripts seed the default users.

Development stack (Docker Compose)

docker-compose.dev.yml builds the frontend from your checkout and runs the WebAPI development image ghcr.io/ohdsi/webapi:dev, pinned by digest, with a pinned TrexSQL release (docker/webapi/Dockerfile):

cp .env.example .env   # optional; see "Using other host ports" below
docker compose -f docker-compose.dev.yml up --build

.env.example also turns on the optional Pythia assistant, which needs a Bedrock key in AWS_BEARER_TOKEN_BEDROCK. Set VITE_BAO_AGENT_ENABLED=false in .env to leave it off.

The two stacks use the same container names and ports, so run one at a time (docker compose down first). They keep their data in separate volumes, because a database migrated by the WebAPI development image cannot be opened by the released WebAPI.

When the stack is healthy:

Using other host ports

If ports 80 or 443 are already in use on your machine, set the host ports in .env (both stacks read it) and add the matching origins to WebAPI's CORS allow-list. Without the CORS change, sign-in and other POST requests fail:

ATLAS3_HTTP_PORT=8081
ATLAS3_HTTPS_PORT=4431
SECURITY_CORS_ALLOWED_ORIGINS=http://localhost:8081,https://localhost:4431

Then open https://localhost:4431. Caddy's automatic HTTP→HTTPS redirect assumes port 443, so use the HTTPS URL directly.

The default POSTGRES_PASSWORD in the compose file is mypass — a placeholder for local development. Set POSTGRES_PASSWORD in a .env file (or your secrets manager) before running anywhere a hostile network can reach. The default user credentials are seeded by atlasdb/; change them before any non-local use.

The compose file already enables the TrexSQL query cache (TREXSQL_ENABLED=true, TREXSQL_CACHE_PATH=/data/cache, HOME=/data) and persists it on the atlas3-webapi-data named volume. Live patient counts in the cohort builder and the inclusion-rule rail only appear once TrexSQL is enabled and a per-source patient cache has been built — trigger the first build from Configuration → Cache management after login.

Frontend-only development

If you already have a WebAPI running on http://localhost:8080 (the compose stack works, as does a native install), you can run the Vue dev server directly:

npm install
npm run dev          # Vite on http://localhost:5173, proxies /WebAPI to :8080
npm run build        # Production bundle in dist/
npm run preview      # Serve the production bundle locally

The dev server proxies /WebAPI to http://localhost:8080. To use a different backend, set WEBAPI_URL, for example WEBAPI_URL=https://example.org npm run dev. A deployed bundle reads the WebAPI address at runtime from config-local.json next to index.html (api.url); see public/config-local.example.json.

Prebuilt frontend from npm (without Docker)

Release tags publish the built frontend to npmjs as atlas3. To try it against a running WebAPI with nothing but Node.js:

npx atlas3 --webapi http://localhost:8080

This serves ATLAS at http://localhost:4180/atlas/ and forwards /WebAPI to the given address, which can be a remote WebAPI (https://example.org/WebAPI). Because the browser only talks to this one address, WebAPI's CORS settings don't matter. --port and --host change where it listens. It is meant for local use and evaluation: it has no HTTPS or caching.

For a real deployment, serve the package with the bundled Caddyfile, the same one the Docker image uses. With a WebAPI on localhost:8080 and Caddy installed:

npm install atlas3
ATLAS_DIST=node_modules/atlas3/dist WEBAPI_HOST=localhost caddy run --config node_modules/atlas3/Caddyfile

Then open https://localhost/atlas/. Caddy serves the bundle and proxies /WebAPI to WEBAPI_HOST:WEBAPI_PORT (port 8080 by default), so the browser needs no CORS setup. The certificate comes from Caddy's local CA; run caddy trust once to stop the browser warning. To listen elsewhere, set CADDY_HOSTNAME, for example CADDY_HOSTNAME=localhost:8443, which also avoids needing root for port 443. The package ships the same dist/config-local.json as the Docker image, with database sign-in enabled. To change auth providers or other settings, edit that file, using dist/config-local.example.json for reference, and reapply your changes after upgrading the package.

First-time login and creating users

The default DB-auth path expects a row in the webapi.auth_user table whose password column is a bcrypt hash of the chosen plaintext. The compose seed scripts in atlasdb/ create two users, admin / admin and ohdsi / ohdsi. To add more users, either insert rows into webapi.auth_user directly or, if your deployment exposes LDAP/OAuth/SAML/OIDC, configure the corresponding SECURITY_AUTH_* properties on the WebAPI side.

After signing in, an administrator should:

  • Visit Configuration → Permissions and set up the role bundles your organisation needs.
  • Confirm the Data Sources page lists each connected CDM and that its dashboard renders without errors.
  • Run a small smoke-test cohort against each source to validate end-to-end execution.

Testing

ATLAS v3.0 has comprehensive test coverage across multiple test types:

Running Tests

# Run unit tests (Vitest, watch mode by default)
npm run test:unit

# Unit tests with coverage report
npm run test:coverage

# Run E2E tests (headless)
npm run test:e2e

# Run E2E tests with visible browser
npm run test:e2e:headed

# Run E2E tests in interactive UI mode
npm run test:e2e:ui

# View last E2E test report
npm run test:e2e:report

# Run the visual-comparison subset only
npm run test:visual

# Type-check, lint, i18n key check, unit tests, and production build
npm run check-all

Test Structure

  • E2E Tests (tests/e2e/): End-to-end tests using Playwright

    • Auth flow tests
    • Concept search and management
    • Data source reports
    • Visual comparison tests
  • Unit Tests (tests/unit/): Unit tests using Vitest

    • Store tests (Pinia)
    • Service tests
    • Utility function tests
    • Composable tests
  • Component Tests (tests/component/): Component tests using Vitest + Vue Test Utils

    • Chart components
    • UI components
    • Form components

Plugin Development

ATLAS v3.0 supports a plugin architecture based on single-spa and SystemJS. Reference plugins live in plugins-dev/.

Related Projects

  • WebAPI — Backend API service; ATLAS v3.0 requires WebAPI v3.0 from the master branch
  • trex — TrexSQL query cache; loaded into WebAPI as a runtime plugin

Support

For issues and questions, please use the GitHub issue tracker.

About

A complete reimplementation of OHDSI ATLAS for cohort definition and analysis, built with Vue 3 and TypeScript.

Resources

Stars

13 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages