Architecture & security summary

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 or newer (tested on 17, 21 and 25), Spring Boot 3.5. Runs as a normal Spring Boot service on any cloud or on-premises. Other languages and frameworks use the engine image over HTTP.

Shape

In-process modular monolith. No sidecar or network hop between your product and the platform.

Platform state

PostgreSQL (32 spine_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. In Java, use JDBC, jOOQ, MyBatis or JPA through EntityManager (Spring Data repositories are blocked by the guardrail); 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/claspine-client (Apache-2.0) for authentication, permissions, audit, notifications and host resolution. It calls a Claspine 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.

• 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

Claspine ships its guardrails as a library (grahmur-platform-guardrails). ProductBoundaryTest applies them to every class your build compiles, in every module and package:

@AnalyzeClasses(locations = SpineGuardrails.ProjectClasses.class,
        importOptions = ImportOption.DoNotIncludeTests.class)
class ProductBoundaryTest {
    // no internal / persistence / Spring Data dependencies,
    // no Class.forName, loadClass, setAccessible or privateLookupIn
    @ArchTest
    static final ArchTests spine_guardrails = ArchTests.in(SpineGuardrails.class);

    // no SQL naming spine_platform_* tables, no classes in com.grahmur.platform,
    // no @ArchIgnore or ArchUnit ignore files
    @Test
    void repository_has_no_guardrail_violations() {
        SpineSourceGuardrails.assertClean(SpineSourceGuardrails.projectRoot());
    }
}

The starter runs this test in its own build step whose switches are fixed in the POM, so -DskipTests, -Dmaven.test.skip and -Dtest=… do not skip it and deleting it fails the build. A CI workflow checks that every module ran it, and CODEOWNERS plus branch protection make any change to guardrail files need an owner’s approval. For JS/TS code, @grahmur-org/eslint-plugin-claspine fails lint on hardcoded or client-exposed secrets, SQL concatenation, unscoped tenant queries, secrets in logs and buffered uploads.

Claspine enforces the data boundary itself, even in projects that never added this test. At runtime the application’s own database connections refuse any query, write, aggregation stage or command that names one of Claspine’s tables; a staging or production start stops when the application’s compiled code names them; and every test run with Claspine on the classpath fails on them. There is no switch to turn this off. Claspine’s own code uses separate, unguarded connections. This covers PostgreSQL, MongoDB and Firestore. Deliberate workarounds (unwrapping a JDBC connection, reflection) are outside what a library can stop; a separate database user for Claspine is the hard stop, and we recommend it for production.

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.

Security controls by module

Compliance posture and shared responsibility

Compliance-ready, not certified. Claspine 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 Claspine does not by itself make a product compliant, and your organization remains responsible for its own compliance.

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 files, AI routing and payments (plus auth, permissions, audit and notifications) and needs a running Claspine engine service or a Claspine Atlas project; no prebuilt container image is published yet.
• Automated PostgreSQL store tests mostly run against H2 in PostgreSQL mode (agent-control and audit-chain SQL is also tested on PostgreSQL 16); validate your target managed service in your own environment.
• Reviewing your business logic. The guardrails check dependencies and common shapes of insecure code, not intent or data flow.
• Database-level isolation of platform data (a separate platform user on PostgreSQL, MongoDB or Firestore) is optional and off by default; it stops accidental shortcuts by your code, not deliberately malicious code inside your own application.
• Guardrail files can still be changed by anyone with write access; branch protection and code-owner review are what make such a change visible.
• Agent Shield in the Claspine Atlas console is a heuristic preview scanner; a clean result is not proof of safety.
• Agent keys have scopes, budgets and expiry, but there are no human-approval gates for individual agent actions yet.
• Deleting the newest audit events is only detectable against a chain head you recorded outside Claspine.