Panels Project

This project provides a comprehensive Panel Management System for healthcare applications, featuring dynamic data visualization, multi-tenant architecture, and configurable data sources.

Overview

The Panels system allows organizations to:

Create configurable data panels with dynamic columns from multiple data sources
Build user-specific views with filtering, sorting, and publishing capabilities
Manage base columns (from data sources) and calculated columns (formula-based)
Track changes and notify users of panel modifications
Support multi-tenant environments with proper data isolation

Architecture

Core Entities

Panels: Configurable data containers with base and calculated columns
Data Sources: External data connections (databases, APIs, files)
Views: User-specific filtered visualizations of panels
Columns: Base columns (from data sources) and calculated columns (formulas)
Change Tracking: Panel modification history and user notifications

Key Features

Multi-tenant Support: Tenant-level and user-level panel management
Dynamic Data Sources: Support for various data source types with synchronization
Calculated Columns: Formula-based columns with dependency tracking
View Publishing: Share personal views tenant-wide
Change Management: Track panel changes and notify affected view users
Cohort Rules: Define population criteria for panels

Tech Stack

Backend (Services)

Runtime: Node.js 22.14.0
Framework: Fastify 5.3.2 with TypeScript
ORM: MikroORM 6.4.16 with PostgreSQL driver
Validation: Zod 3.25.51 with fastify-type-provider-zod
Authentication: @fastify/jwt and @fastify/auth
API Documentation: @fastify/swagger and @fastify/swagger-ui
Testing: Vitest 3.2.1
Code Quality: Biome 1.9.4

Frontend (App)

Framework: Next.js 15.3.3 with React 19
Styling: Tailwind CSS 4.1.7 with DaisyUI 5.0.43
Authentication: NextAuth 5.0.0-beta.25
Healthcare: Medplum Core 4.1.6 with FHIR types
Drag & Drop: @dnd-kit suite
AI Integration: OpenAI 4.103.0
Testing: Vitest 3.2.1 with JSdom, comprehensive API unit tests

Documentation

Framework: VitePress 1.6.3
Features: Interactive documentation, API reference, guides, and examples
Location: apps/docs/

Infrastructure

Database: PostgreSQL 16
Cache: Redis 7
Package Manager: pnpm 10.11.0
Development: Docker Compose for infrastructure
Build System: Turbo with TypeScript 5.8.3

Prerequisites

Node.js >= 22
pnpm >= 10.11.0
Docker and Docker Compose
PostgreSQL 16 (if running locally)
Redis 7 (if running locally)

Project Structure

.
├── apps/
│   ├── app/                    # Next.js frontend application
│   │   └── src/api/            # API client functions
│   │       ├── config/         # API configuration
│   │       ├── *.test.ts       # Unit tests (alongside API files)
│   │       ├── testUtils.ts    # Testing utilities and mocks
│   │       └── README.md       # API testing documentation
│   ├── docs/                   # VitePress documentation site
│   │   ├── getting-started/    # Installation and setup guides
│   │   ├── guides/            # How-to guides and tutorials
│   │   ├── reference/         # API reference documentation
│   │   ├── examples/          # Code examples and use cases
│   │   └── .vitepress/        # VitePress configuration
│   └── services/               # Fastify backend API
│       └── src/modules/        # API modules
│           ├── panel/          # Panel management routes
│           ├── datasource/     # Data source management
│           ├── column/         # Column management (base & calculated)
│           ├── view/           # User views and publishing
│           └── change/         # Change tracking and notifications
├── packages/                   # Shared packages
│   └── types/                  # Shared TypeScript types
├── dev/                        # Development configuration
│   ├── config/                 # Configuration files
│   ├── scripts/               # Development scripts (env generation)
│   └── datastore/             # Local database storage
└── compose.yaml               # Docker Compose configuration

API Modules

Panel Management

GET /panels - List user/tenant panels
POST /panels - Create new panel
GET /panels/:id - Get panel details
PUT /panels/:id - Update panel
DELETE /panels/:id - Delete panel

Data Source Management

GET /panels/:panelId/datasources - List panel data sources
POST /panels/:panelId/datasources - Add data source
PUT /datasources/:id - Update data source
DELETE /datasources/:id - Remove data source
POST /datasources/:id/sync - Sync data source

Column Management

GET /panels/:panelId/columns - List panel columns
POST /panels/:panelId/columns/base - Create base column
POST /panels/:panelId/columns/calculated - Create calculated column
PUT /columns/:id - Update column
DELETE /columns/:id - Delete column

View Management

GET /panels/:panelId/views - List user views
POST /panels/:panelId/views - Create view
GET /views/:id - Get view details
PUT /views/:id - Update view
DELETE /views/:id - Delete view
POST /views/:id/publish - Publish view tenant-wide

Getting Started

Install Dependencies
```
pnpm bootstrap
```

Generate Environment Files

# Generate .env files from compose.yaml configuration
pnpm generate:env

Start Development Environment

# Start the infrastructure (PostgreSQL, Redis)
pnpm run:infra

# Start the development servers
pnpm dev

Access the Applications
- Frontend App: http://localhost:3003 - Main application interface
- Backend API: http://localhost:3001 - RESTful API server
- API Documentation: http://localhost:3001/docs - Interactive API docs (Swagger)
- Project Documentation: http://localhost:3004 - Comprehensive guides and references
```
pnpm --filter @panels/docs docs:dev
```
- Database UI: http://localhost:8081 - pgweb interface for PostgreSQL

Database Setup

The services use MikroORM for database management:

# Create a new migration
pnpm --filter @panels/services migration:create

# Apply migrations
pnpm --filter @panels/services migration:apply

# Reset database with fresh schema
pnpm --filter @panels/services schema:fresh

API Testing

The project includes a comprehensive Bruno collection for API testing with all endpoints covered. The collection provides:

Complete test coverage for all Panel, Data Source, Column, and View operations
Environment configuration for local development
Sequential test execution workflow
Realistic test data examples

📋 View the complete Bruno API Test Collection

Unit Testing

The project includes comprehensive unit testing infrastructure for API functions with advanced mocking and environment configuration capabilities.

Frontend API Testing

Framework: Vitest with JSdom environment
Location: apps/app/src/api/ (tests alongside API files)
Coverage: Complete test coverage for panelsAPI and viewsAPI
Configuration: Environment-based API URL configuration

Key Features

Configurable Base URL: APIs support environment-based URL configuration

// Environment variable: API_BASE_URL
// Development: http://localhost:3001
// Testing: https://api.test.com (or custom)

Advanced Mocking: Comprehensive mock data generators and response builders
Error Testing: Network failures, HTTP errors, and validation testing
Environment Management: Dynamic environment variable stubbing in tests

Test Files

panelsAPI.test.ts - 20 test cases covering CRUD operations, nested resources
viewsAPI.test.ts - 27 test cases covering views, publishing, and sorts
testUtils.ts - Mock data generators and testing utilities
vitest.config.ts - Test environment configuration
vitest.setup.ts - Global test setup and mocks

Running Tests

# Run frontend API tests
pnpm --filter @panels/app test

# Run with coverage
pnpm --filter @panels/app test:coverage

# Run in watch mode
pnpm --filter @panels/app test:watch

# Run specific test file
pnpm --filter @panels/app test panelsAPI.test.ts

Backend Testing

Framework: Vitest 3.2.1
Location: apps/services/src/

# Run backend tests
pnpm --filter @panels/services test

# Run with coverage
pnpm --filter @panels/services test:coverage

API Configuration

The API functions now support configurable base URLs through environment variables:

// apps/app/src/api/config/apiConfig.ts
export const apiConfig = {
  get baseUrl(): string {
    return process.env.API_BASE_URL || 'http://localhost:3001'
  },
  buildUrl: (path: string): string => `${apiConfig.baseUrl}${path}`
}

This enables seamless switching between development, testing, and production environments.

Development Tools

Biome: Used for code formatting and linting

pnpm format     # Check formatting
pnpm format:fix # Fix formatting issues
pnpm lint       # Run linter
pnpm lint:fix   # Fix linting issues

TypeScript: Type checking
```
pnpm typecheck
```

Testing:

# Run all tests (frontend + backend)
pnpm test

# Frontend API tests only
pnpm --filter @panels/app test

# Backend tests only  
pnpm --filter @panels/services test

# Run with coverage
pnpm --filter @panels/services test:coverage
pnpm --filter @panels/app test:coverage

# Watch mode for development
pnpm --filter @panels/app test:watch

Available Scripts

Development & Build

pnpm dev: Start development servers
pnpm build: Build all applications
pnpm clean: Clean build artifacts
pnpm clean:all: Clean all artifacts including datastore

Environment Setup

pnpm generate:env: Generate development .env files
pnpm generate:env:prod: Generate production .env files
pnpm generate:env:staging: Generate staging .env files

Infrastructure

pnpm run:infra: Start infrastructure services
pnpm run:infra:stop: Stop infrastructure services

Code Quality

pnpm format: Check code formatting
pnpm format:fix: Fix code formatting
pnpm lint: Run linter
pnpm lint:fix: Fix linting issues
pnpm typecheck: Run TypeScript type checking

Testing

pnpm test: Run all tests

Documentation

pnpm --filter @panels/docs docs:dev: Start documentation server
pnpm --filter @panels/docs docs:build: Build documentation

Infrastructure

The project uses Docker Compose to manage the following services:

PostgreSQL: Database server
- Port: 5432
- Default credentials: medplum/medplum
Redis: Cache server
- Port: 6379
- Password: medplum
pgweb: Database management UI
- Port: 8081

Contributing

Install pre-commit hooks:
```
pnpm prepare
```
Use conventional commits:
```
pnpm commit
```

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 486 Commits
.cursor		.cursor
.github		.github
.husky		.husky
.vscode		.vscode
apps		apps
dev		dev
packages		packages
.dockerignore		.dockerignore
.gitignore		.gitignore
.gitmodules		.gitmodules
.npmrc		.npmrc
.npmrc.docker		.npmrc.docker
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
commitlint.config.js		commitlint.config.js
compose.yaml		compose.yaml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
turbo.json		turbo.json
vitest.config.ts		vitest.config.ts

License

awell-health/panels

Folders and files

Latest commit

History

Repository files navigation

Panels Project

Table of Contents

Overview

Architecture

Core Entities

Key Features

Tech Stack

Backend (Services)

Frontend (App)

Documentation

Infrastructure

Prerequisites

Project Structure

API Modules

Panel Management

Data Source Management

Column Management

View Management

Getting Started

Database Setup

API Testing

Unit Testing

Frontend API Testing

Key Features

Test Files

Running Tests

Backend Testing

API Configuration

Development Tools

Available Scripts

Development & Build

Environment Setup

Infrastructure

Code Quality

Testing

Documentation

Infrastructure

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 53

Packages 0

Uh oh!

Contributors 6

Uh oh!

Languages

Packages