A Vapor-based server for managing clinical research studies, built as part of the Spezi ecosystem.
Spezi Study Server provides a REST API for managing clinical research studies, including:
- Studies - Create and manage study definitions with metadata
- Components - Configure study components (questionnaires, health data collection, informational content)
- Schedules - Define when components should be presented to participants
The server integrates with SpeziStudy for study configuration types and SpeziVapor for dependency injection.
- Swift 6.0+
- Docker
The project uses PostgreSQL and Keycloak for authentication, both running via Docker Compose.
cp .env.example .env # configure environment (defaults work out of the box)
docker compose up -d db keycloak-db keycloak # start PostgreSQL and Keycloak
swift run SpeziStudyPlatformServer migrate --yes # create / update database tables
swift run # start the serverThe server connects to PostgreSQL, fetches JWKS from Keycloak, and syncs groups on startup.
To revert migrations, run swift run SpeziStudyPlatformServer migrate --revert. When using Docker Compose for the app itself, use docker compose run migrate and docker compose run revert instead.
See .env.example for all available environment options.
swift test --no-parallelTests must run without parallelism (--no-parallel) because integration test suites share an in-memory SQLite database per suite. Tests use mock JWT signing — no Docker services required.
| Service | Description | Port |
|---|---|---|
db |
PostgreSQL for the application | 5432 |
keycloak-db |
PostgreSQL for Keycloak | internal |
keycloak |
Keycloak identity provider | 8180 |
app |
Production server (requires docker compose build first) |
8080 |
migrate |
Run migrations manually (docker compose run migrate) |
— |
revert |
Revert migrations (docker compose run revert) |
— |
The API is defined using OpenAPI. The specification and generated types live in the shared SpeziStudyPlatform-API package.
API requests for manual testing are available in tools/bruno/. Bruno is an open-source API client. Select the SpeziStudy environment in Bruno to load the required variables.
Run the Seed request to bootstrap a working dataset — it logs in via Keycloak, fetches groups, creates a study, and adds sample components in sequence. Requests use post-response scripts to pass IDs (e.g. groupId, studyId) to subsequent requests automatically, so you can explore the API without manually copying values.
The server follows a module-based architecture:
Sources/SpeziStudyPlatformServer/
├── App/ # Application bootstrap and configuration
├── Modules/ # Feature modules (Study, Component, etc.)
├── Models/ # Fluent database models
├── Migrations/ # Database migrations
└── Core/ # Shared infrastructure
Each module contains its own Controller, Service, Repository, and Mapper.
This project is licensed under the MIT License. See Licenses for more information.
This project is developed as part of the Stanford Mussallem Center for Biodesign at Stanford University. See CONTRIBUTORS.md for a full list of all Spezi Study Server contributors.
