Aidbox FHIR Server

What is the Aidbox FHIR server?

Aidbox is a FHIR server and backend platform built by Health Samurai that keeps FHIR resources in PostgreSQL and serves them through a FHIR REST API. Teams use it as the clinical data store behind their own applications, adding profiles, access policies and integrations on top instead of writing a FHIR server from scratch.

Aidbox is licensed software, not an open-source project like HAPI FHIR. That changes the evaluation: alongside the technical fit, a team must check the licence terms, the support tier and who will run the database in production.

The product sits in the same place in an architecture as any FHIR server. Apps call it, integration engines write to it, and analytics jobs read from it. What sets it apart is the storage model and how much of the data the team can reach with plain SQL.

How does Aidbox store FHIR data?

Aidbox stores each FHIR resource as a JSON document in PostgreSQL. Health Samurai's database documentation says the whole resource sits in a single JSONB column, and that each resource type gets exactly two tables: one for the current version and one for every version ever created.

This design has practical effects. A Patient read is a lookup of one row, history is a separate table that can be sized and archived on its own, and the database can be backed up, replicated and monitored with ordinary PostgreSQL tools.

The documentation also describes direct SQL access, including a $sql endpoint that runs SQL through the REST API. For reporting and data checks this is a real convenience, because an analyst can query JSONB fields without first exporting data to a warehouse.

Direct SQL needs the same care as any back door. A query that bypasses the FHIR API also bypasses the API's access rules, so limit SQL access to named service accounts and log every query those accounts run.

When does Aidbox fit a project?

Aidbox fits teams that want a FHIR-native data core on PostgreSQL and are prepared to pay for a licence and support. It fits less well when the budget allows no licence cost or when the organization must run only open-source components.

• Good fit: A digital health product that needs a FHIR data store from day one, with profiles enforced and a team comfortable running PostgreSQL.
• Good fit: A payer or provider API project where analysts want SQL over the same data that the FHIR API serves.
• Good fit: A team that would rather buy a supported server than staff in-house expertise on a Java FHIR codebase.
• Weaker fit: An organization with a policy of open-source only components, where HAPI FHIR or another open server is the expected choice.
• Weaker fit: A short proof of concept with no budget line, where a free sandbox server can answer the first questions.
• Weaker fit: A cloud-first team that wants a managed FHIR service from its existing cloud provider and no database to operate.

Write the decision down with the reason. When a new architect or investor asks why Aidbox was chosen, a one-page record of the options and the deciding factors saves a week of debate.

How do you set up Aidbox for a new product?

Set it up in six steps, from a local instance to a production deployment. Each step ends with something the team can test, so a problem surfaces before the next layer depends on it.

• 1. Local instance: Run Aidbox locally using the getting-started guide, with synthetic data only, and load a handful of test patients through the REST API.
• 2. Profiles first: Load the implementation guides the product depends on, such as US Core, before the first real feature is built, so every write is checked from the start.
• 3. Access model: Define clients, users and access policies for each app and service, and test that a token for one app cannot read another app's data.
• 4. Integration paths: Connect the integration engine, SMART on FHIR apps and any HL7 v2 feeds, and agree how each one identifies patients and handles duplicates.
• 5. Environments: Stand up development, staging and production with infrastructure as code, using the deployment guides Health Samurai publishes for Kubernetes and the main cloud providers.
• 6. Operations: Set up PostgreSQL backups, restore tests, monitoring of slow queries and alerting on disk growth in the history tables before go-live.

Step 2 is the one most often postponed. Adding profiles after months of loose writes means cleaning or migrating every resource that does not conform, which costs more than enforcing them from the first commit.

Keep configuration in version control. Access policies, loaded packages and client definitions should be reproducible from a repository, so a new environment can be built without copying settings by hand.

Profiles, packages and validation

Profiles are how a FHIR server turns a general standard into a contract for one product. Aidbox's profiling documentation says teams can upload implementation guides, and that resources marked with a profile canonical URL from a loaded guide are then validated automatically.

The same documentation describes posting a StructureDefinition to a running instance and validating resources against it. That suits a product that adds its own extensions on top of US Core, such as a care program identifier or a device source field.

• Tag on write: Every client that creates a resource should declare the profile in meta.profile, so validation applies to it rather than to a guess.
• Pin versions: Record which version of each implementation guide is loaded in each environment, and upgrade them through the same release process as code.
• Test failures: Keep a set of deliberately broken resources and check that each is rejected with a clear OperationOutcome.
• Terminology: Decide which value sets are checked at write time and which are checked later by a data quality job, because full terminology checks on every write add cost.
• Own extensions: Publish the product's own profiles in a package, so partners can validate their data before sending it.

What should you settle with Health Samurai before production?

Settle the licence, the support tier and the upgrade path before any real patient data reaches the server. Health Samurai's licensing page states that the free development licence is only for development, testing and demonstration, and that real healthcare data or PHI must not be loaded on it.

That rule shapes the environment plan. A staging environment that will hold copies of production data needs a production licence, while a sandbox that only ever sees synthetic data can stay on the development licence.

• Licence scope: Which environments, instances and data volumes the production licence covers, and what happens at renewal.
• Support: The response commitments in the chosen support tier and how to raise a production incident.
• Upgrades: How often new versions ship, how long older versions are supported, and how breaking changes are announced.
• Hosting duties: Who runs PostgreSQL, applies patches and holds the backups if the team self-hosts rather than buying a managed option.
• Business associate terms: Whether Health Samurai will touch ePHI in any arrangement, and if so, the business associate agreement that covers it.

Get each answer in writing and file it with the architecture record. Licence questions that surface during a funding round or a hospital security review slow both down.

Where Aidbox projects run into trouble

Most problems come from treating a FHIR server as a schema-free database. These failure points are worth a test or a review before launch.

• SQL as the main API: Product features read and write through SQL, so FHIR access rules, validation and audit never apply to them.
• Unbounded history: Every update adds a row to the history table, and high-churn resources such as Observation grow the database faster than planned.
• Profiles off in staging: Validation is disabled to speed up testing, and nonconforming data reaches production through a migration script.
• One client for everything: All services share a single client and token, so an audit log cannot say which service read a record.
• Search without indexes: A frequent search on a JSONB field runs a full table scan once data grows, and nobody notices until a clinician screen slows down.
• PHI on a development licence: A demo instance is loaded with real records for a pilot, breaking the licence terms and the security plan at once.

Each failure point maps to a control: API-first access, a retention plan for history, validation in every environment, one client per service, query monitoring and an environment register that records what data each instance holds.

How Agnotic can help

A FHIR server is only as useful as the profiles, access rules and integrations built around it. Agnotic Technologies helps product teams evaluate Aidbox against open-source and managed options, then builds the parts on top for the client: implementation guide loading, access policies, SMART on FHIR apps, HL7 v2 and FHIR integrations, and the PostgreSQL operations plan.

For teams already running Aidbox, Agnotic reviews SQL access paths, history growth and validation coverage against the failure points above.

Sources

• Health Samurai: Aidbox database overview (PostgreSQL, JSONB, current and history tables)
• Health Samurai: Aidbox licensing and support
• Health Samurai: Aidbox profiling and validation