The user-facing web application for PIC-SURE — lets researchers search, filter, and export patient cohorts from clinical and genomic datasets. Built with SvelteKit, Skeleton v3, and Tailwind CSS.
To deploy the full PIC-SURE platform, see pic-sure-all-in-one.
git clone https://github.com/hms-dbmi/PIC-SURE-Frontend
cd PIC-SURE-Frontend
pnpm install
cp .env.example .envEdit .env before starting the dev server. At minimum you need:
- Auth provider settings (
VITE_AUTH_PROVIDER_MODULE_*) — configures how users log in (e.g. Auth0 + Google OAuth2) - Auth0 tenant (
VITE_AUTH0_TENANT)
pnpm run devThe dev server starts at http://localhost:5173. You'll need a running PIC-SURE backend to log in and query data.
Configuration is done through environment variables in .env. See .env.example for all available options with inline comments.
Settings are grouped into a few categories:
| Category | Variables | What it controls |
|---|---|---|
| Auth providers | VITE_AUTH_PROVIDER_MODULE_* |
Login methods shown on the login page |
| Pages & features | VITE_OPEN, VITE_DASHBOARD, VITE_VARIANT_EXPLORER, etc. |
Which pages and features are enabled |
| Theming | VITE_LOGO, VITE_DOTS_COLORS_CLASS |
Logo and login page appearance |
| Export | VITE_ALLOW_EXPORT, VITE_ALLOW_DOWNLOAD, etc. |
Data export behavior |
| Analytics | VITE_GOOGLE_ANALYTICS_ID, VITE_GOOGLE_TAG_MANAGER_ID |
Tracking (leave blank to disable) |
For full configuration documentation, see the PIC-SURE Frontend Configuration Guide.
Some PIC-SURE text is configurable. We provide a configuration file that is used for custom text elements here.
Feature flags, settings, and branding are also fetched from the PICSURE API (GET:/picsure/configuration) and cached server-side on startup (src/hooks.server.ts's init, src/lib/config/server/cache.ts). Each request's SSR render and the client's hydration both resolve config from that same server-side cache: src/routes/+layout.server.ts reads it and passes it to src/routes/+layout.ts, which applies it to configuration.svelte.ts's reactive config object via applyConfig() before anything renders. This mirrors the "bootstrap" pattern feature-flag services like LaunchDarkly and GrowthBook use to avoid a flash of default values on first load: the server evaluates once, and the client hydrates from that exact same payload instead of re-fetching. The cache is also available directly at GET:/api/config, and can be forced to refresh via GET:/api/config/refresh.
Features and settings are each resolved from up to three layers: hardcoded defaults, individual VITE_<KEY> env vars (see .env.example), and rows fetched from the API.
VITE_API_CONFIG_FEATURES/VITE_API_CONFIG_SETTINGS/VITE_API_CONFIG_BRANDINGset thekindused to fetch each category fromGET:/picsure/configuration(defaults:ui:featureFlag,ui:setting,ui:branding). Leave one blank to skip fetching that category from the API entirely, relying on env vars and defaults only.VITE_CONFIG_MODEdecides who wins when both an env var and an API row are set for the same field:seed(default): defaults -> env (if set) -> API (if set) winsoverride: defaults -> API (if set) -> env (if set) wins
- "Set" means a non-blank value for boolean/number/JSON-typed fields (a blank value falls back to the default, since blank isn't a valid number or JSON and isn't distinguishable from "off") - see
.env.example's Config precedence section. String-typed fields are the exception: an explicit blank is honored as a deliberate override, not "unset".
Branding is the exception to this layering. It defaults to whatever is in configuration.json, and only a narrow set of fields — currently just the logo (VITE_LOGO/LOGO and VITE_LOGO_ALT/LOGO_ALT) — can be seeded/overridden via env var or the API. Everything else under branding (sitemap, footer, landing page copy, etc.) is sourced from configuration.json and isn't wired up to env/API resolution at this time.
This system is under active development and subject to change.
- e2e (Playwright): use
mockApiConfig(page, { features, settings, branding })fromtests/end-to-end/custom-context.tsto set per-test feature/setting/branding rows. It works by seeding a cookie thatsrc/routes/+layout.server.tsreads and applies to thatBrowserContext's requests only — real config, real backend calls, and other concurrent tests are unaffected. The override is only honored when the app is built/served with--mode test(how Playwright'swebServeralways runs it); it's inert in dev and production builds. - Component tests (Vitest): call
applyConfig(rows)(from#lib/config/config.svelte.ts) with rawConfigObject[]rows to exercise the real API-row mapping/precedence pipeline, or mutateconfig.features/config.settings/config.brandingfields directly for values not resolvable from API rows (e.g.config.branding.explorePage.resultInfo, sourced fromconfiguration.json).tests/support/setup.tscallsresetConfig()after every test automatically, so tests don't need to clean up after themselves.
- SvelteKit — framework (routing, SSR, layouts)
- Skeleton v3 — UI component library
- Tailwind CSS — utility-first styling
- Playwright — integration testing
- Vitest — unit and component testing
Routes use SvelteKit's layout groups to enforce access control at each level:
src/routes/
├── (authentication)/ # Login pages
└── (picsure)/ # Main app shell
├── (public)/ # Open-access routes (explorer, discover, help, dashboard)
└── (authorized)/ # Requires a valid auth token
└── (admin)/ # Admin-only (user management, roles, connections)
- (public) routes are what users see in
openandexploreauth modes — accessible without logging in. - (authorized) routes require a valid token. The layout file at this level checks token presence and expiration, redirecting to login if needed.
- (admin) routes are restricted to users with admin privileges.
Auth is enforced by layout files (+layout.ts) at each group level, using SvelteKit's cascading layout pattern.
src/lib/
├── api/ # Backend transport, paths and resource modules
├── auth/ # Session, tokens, login providers, nav
├── config/ # Runtime configuration (features, settings, branding)
├── query/ # Cohort domain: filters, logic tree, query building, counts
├── explorer/ # Search and explore, advanced filtering, export, genomic, variant, visualizations
├── datasets/ # Named datasets
├── admin/ # Administration pages' state and components
├── banners/ # Site banners and their admin
├── shell/ # App frame used by the layouts
├── ui/ # Design-system primitives (import only ui/, utils/ and packages)
├── utils/ # Generic helpers (import only utils/ and packages)
├── telemetry/ # Logging
├── server/ # Cross-cutting server-only code
└── assets/
Each feature folder holds its model, state, components and tests. Tests sit next to the code they
cover (foo.test.ts for the Vitest node project, Foo.svelte.test.ts for client). Code used by a
single route sits in that route's folder. tests/ holds the Playwright suite (end-to-end/) and shared
test support (support/: setup, mock data, fixtures).
| Command | What it does |
|---|---|
pnpm run dev |
Start dev server with hot reload |
pnpm run build |
Production build |
pnpm run preview |
Preview the production build locally |
pnpm run check |
Svelte and TypeScript checks, plus a check that every vi.mock path resolves |
pnpm run check:watch |
svelte-check, re-run on file changes |
pnpm run format |
Format code with Prettier |
pnpm run lint |
Lint with Prettier + ESLint |
pnpm run clean |
format + lint |
pnpm run test |
Run all tests (test:vitest + test:integration) |
pnpm run test:vitest |
Run unit + component tests (Vitest) |
pnpm run test:unit |
Run the Vitest node project (*.test.ts) |
pnpm run test:component |
Run the Vitest client project (*.svelte.test.ts) |
pnpm run test:integration |
Run integration/e2e tests (Playwright, all browsers) |
pnpm run test:integration:slim |
Playwright, Chromium only, minimal reporter, --retries=1 — faster local/CI runs |
pnpm run playwright |
Open Playwright's UI mode against the built app |
pnpm run playwright:dev |
Playwright UI mode against the dev server (PLAYWRIGHT_DEV=1) |
pnpm run precommit |
format + lint + check + test — the full pre-PR check |
Run all checks before submitting a PR:
pnpm run precommitIf this is your first time running integration tests, install Playwright browsers:
pnpx playwright installPlaywright serves the app on port 4173. Set E2E_PORT to use another port, e.g. when two checkouts run e2e at
the same time: Playwright reuses any server already on its port, so the second run would test the first one's build.
Please refer to CONTRIBUTING for guidelines on how to contribute, submit issues, and propose improvements.
Also refer to our Code of Conduct.