> 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/deploy/deployment-guide/components-and-requirements.md).

# Components & Requirements

This page lists everything that can be deployed as part of SPICE, how the pieces depend on each other, and what your environment needs before you start.

## Architecture at a glance

Clients (the Android app and the web applications) talk to a single **reverse proxy**. The proxy routes each URL prefix (for example `/user-service/`, `/spice-service/`, `/fhir-server/`) to the matching service. Services call each other over HTTP inside a private network and share PostgreSQL, a cache and a message queue.

## Deployable units

### Backend services

All backend services are Java (Spring Boot) applications packaged as one container image each. Application services are stateless: they keep no data on local disk that you need to preserve, apart from log files.

The default ports below are the ones used in the Docker Compose setup. Services only need to be reachable from the reverse proxy and from each other; do not expose them directly to the internet.

| Service                | Role                                                                                                         | Default port | Stores data in                                            | Other dependencies                          |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ | ------------ | --------------------------------------------------------- | ------------------------------------------- |
| `auth-service`         | Login, token issue and validation                                                                            | 8089         | Core database (users, roles)                              | Cache                                       |
| `user-service`         | Users, organisations, roles, geography, facility metadata. **Runs the core database migrations on startup.** | 8085         | Core database                                             | Cache, auth service                         |
| `admin-service`        | Administrative and configuration operations                                                                  | 8086         | Core database                                             | Cache, auth service                         |
| `spice-service`        | Core clinical and programme workflows (registration, screening, assessments, follow-up and more)             | 8087         | Core database                                             | Cache, object storage, FHIR mapper          |
| `offline-service`      | Data sync for the offline-first mobile app                                                                   | 8093         | Core database                                             | Cache, message queue, object storage        |
| `notification-service` | E-mail and SMS delivery, scheduled notifications                                                             | 8084         | Core database                                             | Cache, SMTP server, optional SMS gateway    |
| `fhir-mapper`          | Translates SPICE data to and from FHIR resources and calls the FHIR server                                   | 8092         | Core database                                             | Cache, FHIR server                          |
| `cql-service`          | Evaluates clinical rules written in Clinical Quality Language (CQL)                                          | 8094         | Core database                                             | Cache, FHIR server, CQL and value-set files |
| `cfr-service`          | Facility registry and reporting APIs                                                                         | 8050         | Reporting database (and read access to the core database) | Cache, object storage for report exports    |

`common-service` is a shared library that every backend service links against at build time. It is not deployed on its own, but it must be built and installed before the services (see [Docker Compose Install](https://spice.docs.medtroniclabs.org/deploy/deployment-guide/docker-compose.md)).

### FHIR server

| Unit          | Role                                                                                                                                                             | Default port                          | Stores data in |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | -------------- |
| `fhir-server` | HAPI FHIR JPA server (FHIR R4) holding clinical data. Validates incoming bearer tokens against the auth service and runs its own database migrations on startup. | 8091 (set through `FHIR_SERVER_PORT`) | FHIR database  |

The FHIR server is the largest consumer of database storage and memory. See [FHIR Server & Mapper](https://spice.docs.medtroniclabs.org/deploy/deployment-guide/fhir-server-and-mapper.md).

### Supporting services

| Component                               | Needed for                                        | Stateful?                | Notes                                                                                                                                                                                                         |
| --------------------------------------- | ------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PostgreSQL**                          | All services                                      | Yes                      | Three databases on one or more servers: the **core** database, the **FHIR** database and the **reporting** database. Managed or self-hosted.                                                                  |
| **Redis** (cache)                       | All backend services                              | Yes (cache and sessions) | Used for caching and login/session data. Losing it logs users out but does not lose clinical data.                                                                                                            |
| **RabbitMQ** (message queue)            | `offline-service`                                 | Yes (messages in flight) | Carries sync requests and responses. A cloud message queue is also supported as an alternative; choose one in [Configuration](https://spice.docs.medtroniclabs.org/deploy/deployment-guide/configuration.md). |
| **Object storage**                      | `spice-service`, `offline-service`, `cfr-service` | Yes                      | Stores pre-generated sync files, signatures and report exports. `offline-service` can use a local filesystem path for testing only.                                                                           |
| **Reverse proxy / API gateway** (nginx) | All clients                                       | No                       | Routes URL prefixes to services, terminates TLS, raises body-size and timeout limits for sync traffic. A reference configuration is provided with the Docker Compose setup.                                   |

### Web applications

| Application                                        | Role                                                         | Build output                                        |
| -------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------- |
| `spice_web` (admin and clinical web portal)        | Administration, user and facility management, clinical views | Static files served by any web server               |
| `report_web` (reporting web application, optional) | Dashboards and reports on top of the reporting services      | Static files plus a `config.json` loaded at runtime |

Both are single-page applications. They are built once and served as static files, so you only need a web server (nginx works well) and TLS.

### Android app

The Android app is built from source with Gradle and distributed as an APK (or through your own app distribution channel). It is offline-first: it keeps a local encrypted database and synchronises through `offline-service`. Server URLs are fixed at build time. See [Mobile App](https://spice.docs.medtroniclabs.org/deploy/deployment-guide/android.md).

## Optional components

These are not needed for a working clinical system.

| Component                         | Purpose                                                                                                                                                      |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Reporting and analytics stack** | The reporting database, the ETL that populates it, `cfr-service`, `report_web`, and any BI tool you connect. Needed only if you want dashboards and exports. |
| **SMS gateway**                   | Required only if you send SMS (reminders, password reset links). Several gateways are supported and are enabled with per-provider flags.                     |
| **SMTP server**                   | Required only if you send e-mail (password reset, notifications).                                                                                            |
| **Swagger UI**                    | API documentation pages for each service, switched on with `SWAGGER_ENABLED`. Keep off in production.                                                        |
| **External registry integration** | `cfr-service` can push data to an external health information system; configured with `DHIS_*` settings.                                                     |
| **Observability**                 | The FHIR server image bundles an OpenTelemetry Java agent. Metrics, tracing and log shipping are yours to configure.                                         |

## Software prerequisites

Versions below are taken from the build files in the source repositories.

### To build the backend

| Tool         | Version            | Notes                                                                                           |
| ------------ | ------------------ | ----------------------------------------------------------------------------------------------- |
| JDK          | **25**             | All backend services and the FHIR server compile for Java 25. Runtime images use a Java 25 JRE. |
| Apache Maven | **3.8.3 or newer** | Enforced by the FHIR server build. Maven wrappers are included in several services.             |
| Git          | Any recent version | To obtain the source.                                                                           |

Spring Boot **3.5.x** is used by the backend services, and HAPI FHIR **8.10** by the FHIR server.

> Some service README files still mention Java 21 and Spring Boot 3.2. The build files are authoritative: use Java 25.

### To run

| Tool           | Version                               | Notes                                                                                                                                                        |
| -------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Docker Engine  | A current release                     | Needed to build and run container images.                                                                                                                    |
| Docker Compose | **v2** (`docker compose`)             | The Compose setup is written for the v2 plugin.                                                                                                              |
| PostgreSQL     | **18** (as used by the Compose setup) | Service READMEs state PostgreSQL 12 or newer as a minimum. Use the same major version across environments. The FHIR database uses native table partitioning. |
| Redis          | Current stable                        | The Compose setup uses the official `redis` image.                                                                                                           |
| RabbitMQ       | 3.x                                   | The Compose setup uses the `3-management` image.                                                                                                             |

### To build the web applications

| Tool                     | Version                                             | Notes                                    |
| ------------------------ | --------------------------------------------------- | ---------------------------------------- |
| Node.js                  | **22 or newer** (24 is used by the project tooling) | For `spice_web`, which builds with Vite. |
| npm                      | 8 or newer                                          |                                          |
| Node.js for `report_web` |                                                     |                                          |

### To build the Android app

| Tool                  | Version                                   | Notes                                                         |
| --------------------- | ----------------------------------------- | ------------------------------------------------------------- |
| JDK                   | 17 or newer                               | Java and Kotlin target level is 17.                           |
| Gradle                | 9.6 (via the included wrapper)            | Use `./gradlew`, not a system Gradle.                         |
| Android Gradle Plugin | 9.2                                       | Pulled in by the build.                                       |
| Android SDK           | Compile and target SDK 37, minimum SDK 23 | Install through Android Studio or the command-line SDK tools. |

## Network, DNS and TLS

* **Single public entry point.** Expose only the reverse proxy (and the web application host) to users. Keep PostgreSQL, Redis, RabbitMQ and the individual services on a private network.
* **DNS.** At minimum one name for the API gateway (for example `api.example.org`) and one for each web application you serve. Use the same names in the web application configuration, the Android build and the `ALLOWED_ORIGINS` setting.
* **TLS.** Terminate HTTPS at the reverse proxy or load balancer with a certificate from a trusted authority. The mobile and web clients should only ever use `https://` outside of local testing. The reference proxy configuration shipped for Docker Compose listens on plain HTTP only.
* **Request limits.** Sync uploads can be large and slow. The reference configuration allows request bodies up to 150 MB, 300 second timeouts and enlarged proxy buffers (login responses carry large headers). Keep equivalent limits on any load balancer in front of the proxy.
* **Outbound access.** Services need outbound access to your SMTP server, SMS gateway and object storage, if used.
* **Time.** Keep server clocks synchronised (NTP). Short-lived tokens exchanged between services depend on it.

## What to decide before you start

* Where PostgreSQL, Redis, RabbitMQ and object storage will come from (managed service, self-hosted container, or existing infrastructure).
* How you will manage secrets (see [Configuration](https://spice.docs.medtroniclabs.org/deploy/deployment-guide/configuration.md)).
* Whether you need the reporting stack, SMS and e-mail.
* How many users and how much data you expect, to size the database and FHIR server (see [Sizing & Operations](https://spice.docs.medtroniclabs.org/deploy/deployment-guide/sizing-and-operations.md)).
