Architecture

A cinematic industrial city of transactional infrastructure with factories, pipes, bridges, service corridors, and small maintenance robots.

The transactional plumbing for OLTP applications.

Cleave is a compiled service built around three layers: application-facing interface adapters, a shared repository-operation engine, and repository adapters for individual databases. The interface defines how clients express requests; the engine applies common transaction and access rules; the repository adapter handles native execution. These layers support short, bounded transactions over operational data without tying application code to a particular database protocol.

Call Cleave directly from a web or mobile client, use it behind a custom backend, or combine both approaches. Your application services retain the business rules, workflows, and coordination specific to your domain.

For the reasoning behind this division, read the Product Thesis.

Interface, operations, and repository adapters

Cleave's terminology distinguishes three parts of the transactional path:

LayerRole
RIP — Repository Interface ProtocolThe logical application-facing interface. A RIP adapter interprets requests, maps them to common operations, and formats responses. JSON:API is the interface used in the current documentation.
RAP — Repository Access ProtocolThe common repository operations and their semantics. The RAP engine coordinates CRUD, filtering, sorting, pagination, relationships, validation, JWT verification, and ACL enforcement.
Repository adaptersTranslate common operations into repository-native operations, preserving the behavior of the underlying database.

RIP and RAP are Cleave's architectural terms. They separate the interface contract from transactional behavior and database-specific execution. They do not prescribe a single transport or serialization format. Logging and metrics span these layers.

Three ways to connect

Direct client access

Web or mobile client → Cleave → Repository

A client can call Cleave directly for resource operations governed by the configured validation and authorization rules. An external identity provider issues the client's token; Cleave verifies it and enforces access to the requested resources.

Behind a custom backend

Web or mobile client → Application backend → Cleave → Repository

The backend handles business rules, calculations, workflows, or coordination with other services. It calls Cleave for the repository-facing operations those tasks require.

A hybrid application

Web or mobile client ─────────────────→ Cleave → Repository
                     → Custom backend ────↑

An application can use direct access for ordinary resource operations and route business-specific actions through its backend. Choose the path according to the operation: actions requiring business rules must pass through the service that enforces those rules, with direct resource access restricted accordingly.

Responsibility boundaries

ComponentResponsibility
ClientPresentation, interaction, and client state.
Application backendBusiness rules, workflows, and coordination with payments, queues, and other services.
Identity providerSign-in, identity issuance, and token lifecycle.
CleaveResource requests, validation, JWT verification, ACL enforcement, repository operations, and request telemetry.
RepositoryStorage, constraints, indexes, and repository-native transaction semantics.

Cleave executes repository operations; domain-specific application logic runs in your application services.

Request processing

A Cleave request moves through a strict pipeline:

HTTP request
    |
URL and query parsing
    |
resource and field resolution
    |
whitelist validation
    |
blacklist and security checks
    |
type and format validation
    |
JWT verification
    |
ACL authorization
    |
repository operation construction
    |
repository execution
    |
response serialization
    |
HTTP response

If validation or authorization fails, no repository operation should occur. Cleave should not attempt to repair malformed requests or silently reinterpret ambiguous input.

Clients express resource-oriented requests. Cleave controls the repository grammar: resources, fields, operators, relationship paths, formatting, authorization, and execution rules.

Repository model

Repository independence does not mean pretending every repository behaves identically.

MySQL, PostgreSQL, MongoDB, SQL Server, Aurora, object storage, and other repositories differ in transaction semantics, joins, locking, indexing, consistency, query planning, data types, pagination, relationship representation, and write behavior.

Cleave provides a consistent external transactional interface while preserving repository-specific implementation where correctness or performance requires it.

The product should standardize access without flattening meaningful repository differences.

SQL and repository operations

Cleave does not expose SQL to clients.

Clients express resource-oriented requests. Cleave parses and validates those requests, then constructs repository operations internally.

For SQL repositories, this may involve dynamically generated SQL. Stored procedures are not required and should not define the architecture. Prepared statements may be useful for frequently repeated query shapes, but they are not automatically optimal for every request.

The security principle is that unvalidated client input must never become repository syntax.

Relationships

Relationship support is one of the most important technical boundaries.

Relational data may require direct joins, linking-table joins, multiple bounded queries, explicit relationship definitions, or JSON:API compound-document assembly.

Joins are not inherently forbidden. The danger is unbounded client-directed query composition.

Cleave must control:

Relationship support should remain useful without allowing clients to generate pathological repository work.

Identity and authorization

Cleave does not create JWTs or authenticate usernames and passwords.

An external OAuth 2.0 or OpenID Connect provider issues the token. Cleave receives the token and performs signature verification, issuer validation, audience validation, expiry validation, identity extraction, group extraction, role extraction, scope or permission extraction, and ACL enforcement.

Identity issuance and authorization enforcement are separate supplier responsibilities.

Repository and deployment boundaries

Each running Cleave service instance should have a clear repository boundary. Multiple Cleave services may be deployed when an application uses multiple repositories. The external resource interface can remain consistent while each adapter handles its repository's semantics.

Reader and writer pools, request limits, and authorization configuration should match the workload. A public mobile endpoint and an internal administrative tool may need different limits, pool sizes, and access policies. Logging and metrics help operators assess request volume, method mix, failures, and repository behavior.

Keep analytics on its own path

Operational resource requests pass through Cleave. Analytical data can follow a separate path from the repository:

Application → Cleave → Operational repository
                                  |
                               ETL / CDC
                                  |
                         Warehouse / Lakehouse
                                  |
                         BI / Visualization

This keeps warehouse queries and business reporting outside the transactional request path. Cleave's own logs and metrics describe service operation; specialist systems can collect and analyze them.