Skip to content

Commit fa08dc6

Browse files
Lucas0TLucas0T
committed
Create wiki/website for TORCH
1 parent 06b5112 commit fa08dc6

20 files changed

+3578
-2
lines changed

‎.github/workflows/build.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,13 @@ on:
44
push:
55
branches:
66
- main
7-
- develop
87
tags:
98
- 'v*.*.*'
109
pull_request:
1110
branches:
1211
- main
13-
- develop
12+
paths-ignore:
13+
- 'docs/**'
1414
schedule:
1515
- cron: '0 1 * * *'
1616
merge_group:

‎.github/workflows/docs.yml‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
tags:
8+
- 'v*.*.*'
9+
pull_request:
10+
branches:
11+
- main
12+
schedule:
13+
- cron: '0 1 * * *'
14+
merge_group:
15+
16+
concurrency:
17+
group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
18+
cancel-in-progress: true
19+
20+
permissions: read-all
21+
22+
jobs:
23+
build-pages:
24+
runs-on: ubuntu-24.04
25+
steps:
26+
- name: Check out Git repository
27+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
28+
29+
- name: Setup Node
30+
uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
31+
with:
32+
node-version-file: .nvmrc
33+
cache: npm
34+
cache-dependency-path: 'docs/package-lock.json'
35+
36+
- name: Build
37+
working-directory: docs
38+
env:
39+
DOCS_BASE: "/${{ github.event.repository.name }}/"
40+
run: make build
41+
42+
- name: Setup Pages
43+
uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
44+
45+
- name: Upload artifact
46+
uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
47+
with:
48+
path: docs/.vitepress/dist
49+
50+
deploy-pages:
51+
if: github.ref == 'refs/heads/main'
52+
runs-on: ubuntu-24.04
53+
needs: [ build-pages ]
54+
permissions:
55+
pages: write
56+
id-token: write
57+
environment:
58+
name: github-pages
59+
url: ${{ steps.deployment.outputs.page_url }}
60+
steps:
61+
- name: Deploy to GitHub Pages
62+
id: deployment
63+
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

‎.nvmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
23.11.1

‎docs/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/node_modules/
2+
/.vitepress/cache
3+
/.vitepress/dist

‎docs/.vitepress/config.ts‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
import {defineConfig} from 'vitepress'
2+
3+
export default defineConfig({
4+
title: 'TORCH',
5+
description: 'TORCH Documentation',
6+
base: process.env.DOCS_BASE || '',
7+
lastUpdated: true,
8+
9+
themeConfig: {
10+
siteTitle: false,
11+
12+
editLink: {
13+
pattern: 'https://github.com/medizininformatik-initiative/torch/edit/main/docs/:path',
14+
text: 'Edit this page on GitHub'
15+
},
16+
17+
socialLinks: [
18+
{icon: 'github', link: 'https://github.com/medizininformatik-initiative/torch'}
19+
],
20+
21+
footer: {
22+
message: 'Released under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License 2.0</a>',
23+
},
24+
25+
search: {
26+
provider: 'local'
27+
},
28+
29+
outline: {
30+
level: [2, 3]
31+
},
32+
33+
nav: [
34+
{text: 'Home', link: '/'}
35+
],
36+
37+
sidebar: [
38+
{
39+
text: 'Home',
40+
link: '/index.md'
41+
},
42+
{
43+
text: 'Getting Started',
44+
items: [
45+
{text: 'Introduction', link: '/getting-started'}
46+
]
47+
},
48+
{
49+
text: 'Documentation',
50+
link: '/documentation',
51+
items: [
52+
{text: 'Configuration', link: '/configuration'},
53+
{text: 'API', link: '/api/api'},
54+
{
55+
text: 'CRTDL', link: '/crtdl/crtdl',
56+
items: [
57+
{text: 'Filter', link: '/crtdl//filter'}
58+
]
59+
},
60+
{
61+
text: 'Implementation', items: [
62+
{text: 'Implementation Overview', link: '/implementation/implementation-overview'},
63+
{text: 'Consent', link: '/implementation/consent'},
64+
]
65+
},
66+
{text: 'Architecture', link: '/architecture/architecture'},
67+
68+
]
69+
}
70+
]
71+
}
72+
})

‎docs/Makefile‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
install:
2+
npm install
3+
4+
build: install
5+
npm run docs:build
6+
7+
.PHONY: install build

‎docs/api/api.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# API
2+
3+
TORCH provides a FHIR REST API for extracting data based on the Clinical Resource Transfer Definition Language (CRTDL).
4+
It implements the FHIR [Asynchronous Bulk Data Request Pattern](http://hl7.org/fhir/R5/async-bulk.html).
5+
6+
### Key Features of the API
7+
8+
- **Asynchronous Requests**: Supports long-running data extraction tasks.
9+
- **FHIR Compliant**: Adheres to FHIR standards for resource representation.
10+
- **CRTDL Integration**: Uses CRTDL definitions to specify data extraction rules.
11+
12+
### API Endpoints
13+
14+
- **`/$extract-data`**: Initiates a data extraction job based on a CRTDL definition.
15+
- **`/status`**: Checks the status of an ongoing data extraction job.
16+
- **`/metadata`**: Provides metadata about the TORCH server and its capabilities.
17+
18+
## TORCH REST API (based on FHIR Bulk Data Request)
19+
20+
Torch implements the FHIR [Asynchronous Bulk Data Request Pattern][1].
21+
22+
### $extract-data
23+
24+
The $extract-data endpoint implements the kick-off request in the Async Bulk Pattern. It receives a FHIR parameters
25+
resource with a **_crtdl_** parameter containing a
26+
valueBase64Binary [CRTDL](https://github.com/medizininformatik-initiative/clinical-resource-transfer-definition-language).
27+
All examples are with a torch configured with **http://localhost:8086**.
28+
29+
```sh
30+
scripts/create-parameters.sh src/test/resources/CRTDL/CRTDL_observation.json | curl -s 'http://localhost:8086/fhir/$extract-data' -H "Content-Type: application/fhir+json" -d @- -v
31+
```
32+
33+
The Parameters resource created by `scripts/create-parameters.sh` look like this:
34+
35+
```
36+
{
37+
"resourceType": "Parameters",
38+
"parameter": [
39+
{
40+
"name": "crtdl",
41+
"valueBase64Binary": "<Base64 encoded CRTDL>"
42+
}
43+
]
44+
}
45+
```
46+
47+
Optionally patient ids can be submitted for a known cohort, bypassing the cohort selection in the CRTDL:
48+
49+
```
50+
{
51+
"resourceType": "Parameters",
52+
"parameter": [
53+
{
54+
"name": "crtdl",
55+
"valueBase64Binary": "<Base64 encoded CRTDL>"
56+
},
57+
{
58+
"name": "patient",
59+
"valueString": "<Patient Id 1>"
60+
},
61+
{
62+
"name": "patient",
63+
"valueString": "<Patient Id 2>"
64+
}
65+
]
66+
}
67+
```
68+
69+
#### Response - Error (e.g. unsupported search parameter)
70+
71+
* HTTP Status Code of 4XX or 5XX
72+
73+
#### Response - Success
74+
75+
* HTTP Status Code of 202 Accepted
76+
* Content-Location header with the absolute URL of an endpoint for subsequent status requests (polling location)
77+
78+
That location header can be used in the following status query:
79+
E.g. location:"/fhir/__status/1234"
80+
81+
### Status Request
82+
83+
Torch provides a Status Request Endpoint which can be called using the location from the extract Data Endpoint.
84+
85+
```sh
86+
curl -s http://localhost:8080/fhir/__status/{location}
87+
```
88+
89+
#### Response - In-Progress
90+
91+
* HTTP Status Code of 202 Accepted
92+
93+
#### Response - Error
94+
95+
* HTTP status code of 4XX or 5XX
96+
* Content-Type header of application/fhir+json
97+
* Operation Outcome with fatal issue
98+
99+
#### Response - Complete
100+
101+
* HTTP status of 200 OK
102+
* Content-Type header of application/fhir+json
103+
* A body containing a JSON file describing the file links to the batched transformation results
104+
105+
```sh
106+
curl -s 'http://localhost:8080/fhir/$extract-data' -H "Content-Type: application/fhir+json" -d '<query>'
107+
```
108+
109+
the result is a looks something like this:
110+
111+
```json
112+
{
113+
"requiresAccessToken": false,
114+
"output": [
115+
{
116+
"type": "Bundle",
117+
"url": "http://localhost:8080/da4a1c56-f5d9-468c-b57a-b8186ea4fea8/6c88f0ff-0e9a-4cf7-b3c9-044c2e844cfc.ndjson"
118+
},
119+
{
120+
"type": "Bundle",
121+
"url": "http://localhost:8080/da4a1c56-f5d9-468c-b57a-b8186ea4fea8/a4dd907c-4d98-4461-9d4c-02d62fc5a88a.ndjson"
122+
},
123+
{
124+
"type": "Bundle",
125+
"url": "http://localhost:8080/da4a1c56-f5d9-468c-b57a-b8186ea4fea8/f33634bd-d51b-463c-a956-93409d96935f.ndjson"
126+
}
127+
],
128+
"request": "http://localhost:8080//fhir/$extract-data",
129+
"deleted": [],
130+
"transactionTime": "2024-09-05T12:30:32.711151718Z",
131+
"error": []
132+
}
133+
134+
```
135+
136+
[1]: <http://hl7.org/fhir/R5/async-bulk.html>

‎docs/architecture/architecture.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Architecture
2+
3+
This project uses a Spring Boot backend and a TypeScript/JavaScript frontend. The backend exposes REST APIs and
4+
interacts with a FHIR server. The frontend communicates with the backend via HTTP.
5+
6+
## Components
7+
8+
- **Spring Boot Application**: Handles business logic and API endpoints.
9+
- **FHIR Server**: Stores and retrieves healthcare data.
10+
- **Reverse Proxy (NGINX)**: Routes requests and serves static content.
11+
- **Frontend (TypeScript/JavaScript)**: User interface for interacting with the system.
12+
13+
## Data Flow
14+
15+
[Consent](../implementation/consent.md).

0 commit comments

Comments
 (0)