SPINE OS · REVIEWER SUMMARY

Architecture & security summary

A plain description of how Spine OS is built, what its controls do, and what remains your responsibility. It reflects the product as of September 2026; the licensed repository contains the full architecture decision records and capability docs.

Forward by email Talk to us

At a glance

What it is: A commercial, source-available backend platform: 20 modules plus a starter application and AI-agent rule files.
Runtime: Java 17, Spring Boot 3.5. Runs as a normal Spring Boot service on any cloud or on-premises.
Shape: In-process modular monolith. No sidecar or network hop between your product and the platform.
Platform state: PostgreSQL (29 platform_* tables over plain JDBC), MongoDB-compatible stores (Atlas, AWS DocumentDB, Azure Cosmos DB Mongo API) or Google Firestore, selected with platform.persistence.type. Tables and collections are prefixed platform_.
Your data: Independent of the platform. Use any database and ORM; in a shared PostgreSQL database your tables are never touched.
Delivery: Starter repository as source; platform core as versioned Maven artifacts with line numbers and debugging symbols, not obfuscated.
TypeScript / Node: Open-source client @grahmur-org/spine-client (Apache-2.0) for authentication, permissions, audit, notifications and host resolution. It calls a Spine engine service over HTTP; other languages can use the REST APIs directly.
Licensor: GRAHMUR OÜ, under a Commercial License Agreement.

Structure and boundaries

Products define what the business does; the platform decides how infrastructure concerns are handled. There are three layers, and each one may only depend on the one beneath it.

Dependencies point downward. Products consume api and the shared foundation types only.

Every module has the same package layout: api (public contracts), internal (services and validators), persistence (stores), and an auto-configuration class that can be switched off per module.
Public APIs are decoupled. They accept and return shared foundation types (account, actor, product, idempotency and correlation IDs), not authentication-specific types, so a module can be used without adopting unrelated modules.
Tenancy is optional. A first-party product is not forced into a synthetic tenant; organization scope is used only when a product needs it.
Mutations are idempotent. Mutating platform operations take an idempotency key.

Guardrails: what the build enforces

Spine ships ArchUnit tests that run with ./mvnw test. The product-side rule is:

@ArchTest
static final ArchRule product_consumes_only_platform_contracts = noClasses()
    .should().dependOnClassesThat().resideInAnyPackage(
        "com.grahmur.platform..internal..",
        "com.grahmur.platform..persistence..",
        "org.springframework.data..");

Inside the platform, further architecture tests keep provider SDK types out of module APIs and confine sensitive cryptographic primitives (java.security.Signature) to a short list of named packages.

Who covers what
Concern	Build guardrail	Platform module	You
Product bypasses platform contracts	Fails `./mvnw test`	—	Keep the test in CI
Secret handling	—	Opaque references; redaction before logging or persistence	Manage the underlying secret store and rotation policy
Session security	—	Deployment-bound opaque sessions	Choose and configure the identity provider
Audit trail	—	Fail-closed append with secret filtering	Define event types, retention and review
Business-logic flaws	Not covered	Not covered	Code review and testing

Security controls by module

Authentication

Sessions are opaque, server-side and bound to one deployment; only a digest is persisted.
Provider credentials are verified (signature, issuer, audience, expiry) by the deployment’s bound verifier. The Firebase verifier uses JDK security primitives, with no external JOSE library.
Every failure class returns the same empty result, so callers cannot enumerate reasons.
The sandbox verifier cannot be enabled in staging or production.
Cookie transport requires SameSite and a custom header on mutating requests.

Authorization

Decisions use exact runtime context (product, optional organization, deployment).
Permissions are direct grants that can be revoked and restored.
Host resolution is deny-safe: an unknown host does not fall through to a default deployment.

Secrets and credentials

The platform persists opaque secret references, never credential values.
Material is retrieved only at the adapter boundary using short-lived workload identity.
Request, audit, provider and error data are redacted before persistence or logging.

Audit

Fail-closed: if the audit store rejects an event, the operation does not proceed.
Attributes are secret-filtered; actor names and PII are excluded by design.
Queries require exact product and optional organization scope, with bounded result sizes.

Files

Presigned uploads and downloads for S3, GCS and Azure Blob: bytes go directly between the client and cloud storage, not through your application memory.

Provisioning

The platform dispatches infrastructure work through GitHub Actions and verifies it through provider APIs; it does not run Terraform or store uploads itself.
CI callback tokens are single-use, deployment-scoped and stored as SHA-256 digests; replay is denied.

Compliance posture and shared responsibility

Compliance-ready, not certified. Spine provides controls that support HIPAA, SOC 2 and GDPR programs (fail-closed audit, secret scrubbing, deployment-bound sessions). It is compliance-ready, not certified: using Spine does not by itself make a product compliant, and your organization remains responsible for its own compliance.

Programs Spine’s controls are designed to support
Program	What Spine provides	What you still own
HIPAA	Audit trail, access control, secret hygiene, session security	Business associate agreements, risk assessment, PHI handling policies, hosting configuration
SOC 2	Evidence-friendly audit events and enforced architecture boundaries	The audit itself, organizational controls, change management and monitoring
GDPR	Scoped data access, audit trail, no PII in audit attributes by design	Lawful basis, data-subject requests, retention and deletion, processor agreements

Known limits

So nobody is surprised in a review, these are deliberately outside the platform today:

Platform-native passwords, one-time codes, MFA and account recovery: these are delegated to your identity provider.
Audit retention or deletion scheduling, export procedures and alerting integrations.
Field-level before/after change tracking in audit events.
The Node.js client covers a subset of modules (not files, LLM or payments) and needs a running Spine engine service; no prebuilt container image is published yet.
Automated PostgreSQL store tests run against H2 in PostgreSQL mode; validate your target managed service in your own environment.
Reviewing your business logic. The guardrail test checks dependencies, not intent.

Next steps

Questions from your security team, or need the full architecture decision records for a review? Get in touch, or go back to the overview and pricing.

Talk to us Pricing FAQ