CARD — Clinical Archiving Repository Dataset

CARD is the integration layer that connects Schema Builder to any downstream analytics platform. It encodes the full pipeline — schemas, datasets, plugins, and visualization targets — into a single named, versioned, reusable configuration called a CARD Profile.

The Problem CARD Solves

Getting from a JSON-LD schema to a live Superset dashboard today requires:

Manual DDL export from the Mapper View
Manual DuckDB/PostgreSQL CLI commands to load data
Manual "Add Database" in Superset Settings
Manual dataset registration for each table
Manual chart and dashboard authoring

Every step is repeated per project, per user, per environment. CARD eliminates all of it.

CARD Vision

Any schema. Any dataset. Any AI. Any visualizer.

A CARD Profile is a project-scoped, named configuration record that captures:

Slot	What it defines
Schemas	Which JSON-LD schemas are active for this profile
Datasets	Seed data (via faker.js), real data, uploaded CSV/SQL, or none
Plugins	Which Schema Builder plugins to invoke (DDL, seed data, custom)
Visualization Apps	Target BI tool (Apache Superset v1; Grafana, Metabase — future)

Any authorized user — or any CI/CD pipeline — can select a CARD Profile and replay the full pipeline deterministically. Same profile + same data = same dashboards, every time.

System Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                     SureCentric PostgreSQL DB                        │
│                                                                      │
│  sb_card_profile                                                     │
│  ┌─────────────┬─────────────┬──────────────┬────────────────────┐  │
│  │ profile_id  │ project_id  │ friendly_name│ config (JSONB)     │  │
│  ├─────────────┼─────────────┼──────────────┼────────────────────┤  │
│  │ abc-123     │ eclinical-v1│ eClinical    │ { schemas, ...}    │  │
│  └─────────────┴─────────────┴──────────────┴────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘
         ▲  CRUD via REST API                           ▲
         │  (card-api :3099)                            │  /provision
         │                                              │
┌────────┴───────────────┐             ┌────────────────┴──────────┐
│    Schema Builder       │             │    Apache Superset         │
│    (Vue 3, :5173)       │   CARD      │    (:8088)                │
│                         │  Profile    │                           │
│  [CARD Combobox ▼]      │ ─────────▶  │  SS CARD Plugin           │
│  [View CARD Profile]    │             │  - DB Connection           │
│  CARD Profile Editor    │             │  - Dataset Registration    │
│                         │             │  - Dashboard seed          │
└────────────────────────┘             └───────────────────────────┘

CARD API

Service: surecentric-card-api | Port: 3099 | Runtime: Node.js 20 / Express / TypeScript

GET    /health
GET    /api/sb/card-profiles?project_id=<id>   → list active profiles
GET    /api/sb/card-profiles/:id               → get single profile
POST   /api/sb/card-profiles                   → create profile
PUT    /api/sb/card-profiles/:id               → update profile
DELETE /api/sb/card-profiles/:id               → soft-delete
GET    /api/sb/card-profiles/:id/export        → download .card.json
POST   /api/sb/card-profiles/:id/provision     → auto-provision Superset DB + datasets

`/provision` — What Happens

When you click ▶ Provision in the CARD Profile Editor:

card-api authenticates with Superset via POST /api/v1/security/login
Finds or creates the Superset Database connection (e.g. ClinicalDuckDB)
Registers each table from connection.tables as a Superset Dataset
Returns per-app provisioning results as a JSON response
Schema Builder shows a success/failure toast

CARD Profile Config Schema

The config JSONB field supports four top-level slots:

{
  "schemas": [
    {
      "schema_id": "eclinical-ehr-subset",
      "label": "eClinical EHR Subset",
      "source_file": "generated/eclinical-ehr-subset.jsonld",
      "active": true
    }
  ],
  "datasets": [
    {
      "dataset_id": "eclinical-faker-v1",
      "type": "faker",          // "faker" | "real" | "sql-file" | "none"
      "source_plugin": "com.sureclinical.seed-data-generator",
      "include_seed": true,
      "row_counts": { "clinical_site": 8, "patient": 50, "visit": 150 },
      "seed": 42
    }
  ],
  "plugins": [
    { "plugin_id": "com.sureclinical.sql-duckdb", "version": "1.1.0", "active": true },
    { "plugin_id": "com.sureclinical.seed-data-generator", "version": "1.0.0", "active": true }
  ],
  "visualization_apps": [
    {
      "app_id": "apache-superset",
      "plugin": "com.sureclinical.ss-card-plugin",
      "connection": {
        "superset_url": "http://localhost:8088",
        "username": "admin",
        "password_secret_ref": "SUPERSET_ADMIN_PASSWORD", // env var — never plaintext
        "database_engine": "duckdb",
        "sqlalchemy_uri": "duckdb:////data/clinical.duckdb",
        "tables": ["clinical_site", "patient", "visit", "adverse_event"]
      }
    }
  ]
}

Secrets

Superset credentials are never stored as plaintext in the config JSONB. The field password_secret_ref holds only the name of the environment variable. The provision endpoint resolves it at runtime: process.env[connection.password_secret_ref].

CARD Profile Editor UI

The CARD Profile Editor is a dialog in Schema Builder (opened via the 🔧 button next to the CARD Combobox). It has four tabs:

Tab	What you configure
Schemas	Select which JSON-LD schemas are active
Datasets	Toggle seed / real / uploaded data; set row counts and RNG seed
Plugins	Enable/disable Schema Builder plugins for this profile
Visualization Apps	Configure Superset (URL, credentials, tables, engine)

The Seed Dataset toggle controls whether the Seed Dataset Generator plugin produces INSERT statements as part of the provision pipeline — enabling instant chart rendering in Superset prior to loading real data.

SS CARD Plugin — Apache Superset

The SS CARD Plugin (sureclinical-superset-card) is a Python package that runs inside Apache Superset:

sureclinical-superset-card/
├── superset_card/
│   ├── __init__.py        # registers plugin with Superset
│   ├── card_connector.py  # CardConnector: provisions DB + datasets
│   ├── views.py           # FlaskView: "CARD Profiles" admin menu
│   └── api.py             # Blueprint: /superset/card-profiles/*
└── setup.py

Installed via docker/superset/requirements-local.txt. When installed:

Adds a "CARD Profiles" entry under Superset Settings
Fetches CARD Profiles from card-api at the configured CARD_API_URL
Calls CardConnector.provision() to wire DB connections and datasets
Optionally seeds starter dashboards from profile templates

Target Visualizers

CARD's visualization_apps slot is designed for any BI tool. The plugin field references a Schema Builder plugin that handles the platform-specific provisioning:

Platform	Plugin ID	Status
Apache Superset	`com.sureclinical.ss-card-plugin`	✅ V1
Grafana	`com.sureclinical.grafana-card-plugin`	🔲 Planned
Metabase	`com.sureclinical.metabase-card-plugin`	🔲 Planned
Custom / OpenAPI	Any plugin implementing the `provision()` interface	Open

End-to-End User Journey

1. Open Schema Builder → select "eClinical" from CARD Combobox
   → activates eclinical-ehr-subset.jsonld + sql-duckdb + seed-data-generator

2. Work in Mapper View → click Generate
   → schema.sql + inserts.sql written to /generated/

3. Click ▶ Provision in CARD Profile Editor
   → card-api authenticates with Superset
   → creates ClinicalDuckDB connection
   → registers 4 datasets: clinical_site, patient, visit, adverse_event

4. Open Superset → Databases → ClinicalDuckDB ✓
   → Datasets ready → build charts immediately

Zero manual Superset configuration. Zero repeated setup per environment.

Docker Stack

All CARD services run on the SureCentric Docker network:

Container	Image	Port
`superset_app`	`apache/superset:4.0.0`	8088
`superset_db`	`postgres:17`	5432
`superset_cache`	`redis:7`	6379
`surecentric-card-api`	`node:20-alpine`	3099
`surecentric-duckdb`	`datacatering/duckdb:v1.2.1`	—

# Start the full CARD stack
docker compose up -d

# Verify
curl http://localhost:3099/health
# → {"status":"ok","service":"card-api"}

curl "http://localhost:3099/api/sb/card-profiles?project_id=eclinical-v1"
# → [{ "friendly_name": "eClinical", "config": { ... } }]

Implementation Status

Phase	Name	Status
C-0	Docker stack (Superset, DuckDB, PostgreSQL)	✅ Complete
C-1	CARD API (DB table, REST CRUD, Docker service)	✅ Complete
C-2a	Project Switcher + CARD Combobox in SB toolbar	✅ Complete
C-2b	CARD Profile Editor dialog (full implementation)	🔲 Pending
C-3	SS CARD Plugin (Superset Python package)	🔲 Pending
C-4	End-to-end demo + dashboard seed	🔲 Pending

CARD for Superset

For complete documentation of the Superset connector — including the Docker architecture, the /provision endpoint, seed chart templates, DuckDB scoping, and the end-to-end user journey — see the CARD for Superset page.

The Problem CARD Solves​

CARD Vision​

System Architecture​

CARD API​

/provision — What Happens​

CARD Profile Config Schema​

CARD Profile Editor UI​

SS CARD Plugin — Apache Superset​

Target Visualizers​

End-to-End User Journey​

Docker Stack​

Implementation Status​

CARD for Superset​