> For the complete documentation index, see [llms.txt](https://spice.docs.medtroniclabs.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://spice.docs.medtroniclabs.org/architecture/technology-stack.md).

# Technology Stack

The languages, frameworks and data stores SPICE is built on, by layer.

SPICE is built entirely on open-source technology. Versions below are major versions taken from the project's build files and will move forward over time; check each repository's build file for exact versions. For how the pieces fit together, see the [Architecture Overview](https://spice.docs.medtroniclabs.org/architecture/architecture.md) and [System Architecture (C4)](https://spice.docs.medtroniclabs.org/architecture/architecture/c4-diagrams.md).

## Mobile app

| Concern              | Choice                                                | Why                                                      |
| -------------------- | ----------------------------------------------------- | -------------------------------------------------------- |
| Language             | Kotlin 2.x                                            | Standard language for native Android.                    |
| Platform             | Android, minimum API level 23 (Android 6.0)           | Wide device coverage for field devices.                  |
| UI                   | Android Views with view binding, plus Jetpack Compose | Mature screens plus incremental adoption of Compose.     |
| Architecture         | MVVM with repositories                                | Separates UI, data access and sync logic.                |
| Dependency injection | Hilt 2.x                                              | Compile-time DI that integrates with Android lifecycles. |
| Local database       | Room 2.x on an encrypted SQLite (SQLCipher 4.x)       | Offline-first storage with encryption at rest.           |
| Networking           | Retrofit 2 with OkHttp 4                              | De facto REST client for Android.                        |
| Background work      | WorkManager 2.x                                       | Reliable, constraint-aware background synchronisation.   |
| Image loading        | Glide 4                                               | Efficient image caching.                                 |
| Build                | Gradle (Kotlin DSL) with the Android Gradle Plugin 9  | Standard Android toolchain.                              |

## Web front ends

| Concern          | Admin web portal             | Reporting web app                |
| ---------------- | ---------------------------- | -------------------------------- |
| Framework        | React 19                     | React 17                         |
| Language         | TypeScript 5                 | TypeScript 4                     |
| State management | Redux Toolkit 2              | Redux 4                          |
| Routing          | React Router 7               | React Router 5                   |
| Styling          | Bootstrap 5, SCSS            | Bootstrap 5, SCSS                |
| Build tooling    | Vite 8 (Node 22 or later)    | Create React App (webpack-based) |
| HTTP client      | Axios                        | Axios                            |
| Maps             | Leaflet 1 with React-Leaflet | not used                         |
| Tests            | Jest 30                      | Jest                             |

React with TypeScript was chosen for typed, component-based single-page applications; Redux centralises client state.

## Backend services

| Concern                  | Choice                                                       | Why                                                                          |
| ------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| Language and runtime     | Java 25                                                      | Long-term support Java with modern language features and a mature ecosystem. |
| Framework                | Spring Boot 3.x (3.5 line)                                   | Convention-driven REST services, security and data access.                   |
| Service-to-service calls | Spring Cloud 2025.x with OpenFeign, circuit breakers         | Declarative REST clients with resilience.                                    |
| Persistence              | Spring Data JPA with Hibernate                               | Standard object-relational mapping.                                          |
| Schema migrations        | Flyway (in the user, facility registry and FHIR services)    | Versioned, repeatable database changes.                                      |
| Security                 | Spring Security with signed tokens (JWT)                     | Stateless, role-based API protection.                                        |
| API documentation        | OpenAPI via springdoc (Swagger UI)                           | Interactive API docs generated from code.                                    |
| Notifications            | Thymeleaf email templates; pluggable SMS and email providers | Provider-neutral message delivery.                                           |
| Scheduling               | ShedLock-guarded scheduled jobs                              | Ensures a job runs on one instance only when scaled out.                     |
| Testing and quality      | JUnit 5, Mockito, JaCoCo                                     | Unit testing and coverage.                                                   |
| Build                    | Maven (multi-module)                                         | Standard Java build and dependency management.                               |

## Data stores

| Store                | Choice                                  | Use                                                                                             |
| -------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Relational databases | PostgreSQL (managed or self-hosted)     | Platform data, FHIR store and reporting database. Reference container setup uses PostgreSQL 18. |
| Cache                | Redis                                   | Caching and shared state.                                                                       |
| Object storage       | Object storage (self-hosted or managed) | Files such as signatures, consent forms and exports.                                            |

## Messaging

| Concern       | Choice                            | Why                                               |
| ------------- | --------------------------------- | ------------------------------------------------- |
| Message queue | RabbitMQ, via Spring Cloud Stream | Asynchronous hand-off of offline-sync processing. |

## FHIR

| Concern        | Choice                                                                     | Why                                                                                                |
| -------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| FHIR version   | R4                                                                         | Widely implemented release for interoperability.                                                   |
| FHIR server    | HAPI FHIR JPA server 8.x (starter project), PostgreSQL-backed              | Mature open-source FHIR server. SPICE adds token validation, optional partitioning and migrations. |
| FHIR mapper    | Spring Boot service using the HAPI FHIR R4 structures and client libraries | Keeps FHIR mapping out of the clinical workflow code.                                              |
| Clinical rules | Clinical Quality Language (CQL) service using HAPI FHIR client libraries   | Standards-based clinical decision support.                                                         |

See [FHIR and Standards](https://spice.docs.medtroniclabs.org/architecture/architecture/fhir-and-standards.md).

## Reporting, ETL and analytics

| Concern                    | Choice                                                                                                   | Why                                                                                              |
| -------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Reporting ETL              | Python 3.11 or later with psycopg2, scheduled batch job                                                  | Flattens FHIR and administrative data into reporting tables.                                     |
| Reporting database         | PostgreSQL                                                                                               | Fixed, denormalised reporting schemas.                                                           |
| Report API                 | Java service (Spring Boot)                                                                               | Serves the reporting web app.                                                                    |
| Analytics stack (optional) | Apache Airflow, Apache Spark, Airbyte, Hive Metastore, Trino, Apache Superset, deployed with Helm charts | Open-source orchestration, processing, query and dashboard components for large-scale analytics. |

## Build and packaging

| Concern           | Choice                                                                                                                                                                                                     |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Containers        | Each backend service, the FHIR server, the web apps and the ETL job build to container images (Docker). The Java services run on a Java 25 runtime image; the FHIR server uses a minimal distroless image. |
| Orchestration     | Docker Compose for simple installs; Kubernetes with Helm charts for larger ones.                                                                                                                           |
| Reverse proxy     | Nginx in the reference compose setup.                                                                                                                                                                      |
| Android packaging | Gradle build variants (product flavours) configure the backend endpoints per deployment.                                                                                                                   |
