Architecture Overview

System Architecture

Bedrock is a modular authorization engine with three main layers:

┌─────────────────────────────────────────────────────────────────┐
│                        YOUR APPLICATION                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐        │
│   │  REST API   │    │ TypeScript  │    │   Direct    │        │
│   │  Endpoints  │    │    SDK      │    │   Engine    │        │
│   └──────┬──────┘    └──────┬──────┘    └──────┬──────┘        │
│          │                  │                  │                │
│          └──────────────────┼──────────────────┘                │
│                             │                                   │
│                    ┌────────▼────────┐                          │
│                    │  BedrockEngine  │                          │
│                    │   (Core Logic)  │                          │
│                    └────────┬────────┘                          │
│                             │                                   │
│                    ┌────────▼────────┐                          │
│                    │ BedrockStorage  │                          │
│                    │   (Interface)   │                          │
│                    └────────┬────────┘                          │
│                             │                                   │
│          ┌──────────────────┼──────────────────┐                │
│          │                  │                  │                │
│   ┌──────▼──────┐    ┌──────▼──────┐    ┌──────▼──────┐        │
│   │  PostgreSQL │    │  In-Memory  │    │   Custom    │        │
│   │   Storage   │    │   Storage   │    │   Storage   │        │
│   └─────────────┘    └─────────────┘    └─────────────┘        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Core Components

BedrockEngine

The central authorization engine that:

Evaluates permission checks (evaluate()) and lists effective permissions
Composes grants across the scope chain per permissionMode
Applies overrides, resource policies, ownership, and the resource-hierarchy fallback

It is read/evaluate-only—entity writes go through the REST API (api-management), not the engine.

import { BedrockEngine } from '@quarry-systems/bedrock-core';
import { createPostgresStore } from '@quarry-systems/bedrock-core-storage';

const engine = new BedrockEngine(createPostgresStore({ connectionString: process.env.DATABASE_URL }));

BedrockStore

The storage interface (BedrockStore) the engine reads through:

Implementation	Use Case
`createPostgresStore` / `PostgresBedrockStore`	Postgres (the only shipped store)
Custom	Implement `BedrockStore` for your own backend

REST API

Optional HTTP layer for language-agnostic access:

# Evaluate a permission
POST /evaluate
{
  "actor": { "subjectId": "user_jane", "subjectType": "user" },
  "scopeId": "scope_production",
  "action": "deploy",
  "resource": { "resourceType": "service" }
}

Data Model

┌─────────────────────────────────────────────────────────────────┐
│                         SCOPE LAYER                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ScopeType ──defines──▶ Scope ◀──hierarchy──▶ Scope           │
│       │                    │                                    │
│       │                    │                                    │
│       ▼                    ▼                                    │
│  (permissionMode)     Membership ◀── Subject                   │
│                            │                                    │
│                            ▼                                    │
│                     RoleAssignment ──▶ Role ──▶ Permission     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                       RESOURCE LAYER                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ResourceType ──defines──▶ Resource ◀──hierarchy──▶ Resource  │
│                                │                                │
│                                │                                │
│                    ┌───────────┼───────────┐                    │
│                    │           │           │                    │
│                    ▼           ▼           ▼                    │
│              ScopeLink    Collection    Policy                  │
│                                │           │                    │
│                                └─────┬─────┘                    │
│                                      │                          │
│                                      ▼                          │
│                              Policy Target                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                         TAG LAYER                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   TagGroup ──contains──▶ Tag ──assignment──▶ Resource/Subject  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Evaluation Flow

When engine.evaluate() is called:

INPUT: { actor, onBehalfOf?, scopeId, action, resource, context }
  │
  ▼
1. Reachability gate  → resource reachable in the scope? (when the gate is enabled)
2. Delegation grant   → required when onBehalfOf is set (else NO_DELEGATION_GRANT)
3. Resource policies  → highest-priority matching group; deny beats allow within it
4. Role-based perms   → grants composed per permissionMode; overrides; conditions (fail-closed)
5. Ownership          → an owner-role grant on an owned resource
6. Resource hierarchy → a parent resource grants via a cascade: inherit edge
  │
  ▼
OUTPUT: { allowed, matches, explanation, ... }

See Evaluation for the exact flow (delegation and the hierarchy fallback are conditional legs).

ID Format

All Bedrock entities use prefixed UUIDv7 IDs:

Entity	Prefix	Example
Scope	`scope_`	`scope_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b`
Subject	`subject_`	`subject_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b`
Role	`role_`	`role_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b`
Permission	`perm_`	`perm_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b`
Resource	`resource_`	`resource_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b`
Collection	`collection_`	`collection_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b`
Policy	`policy_`	`policy_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b`
Scope Link	`rsl_`	`rsl_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b`

Deployment Options

Embedded Library

Use Bedrock directly in your application:

import { BedrockEngine } from '@quarry-systems/bedrock-core';
import { createPostgresStore } from '@quarry-systems/bedrock-core-storage';

const engine = new BedrockEngine(createPostgresStore({ connectionString: process.env.DATABASE_URL }));

A self-hosted embed runs the engine as a library (no api-management, no console); setup is script/API-driven.

Managed Service (api-management)

Run api-management—the full multi-tenant control plane (REST API, tenants/workspaces/projects, Kinde-backed identity, plus Redis and the Angular console). Consumers call it over HTTP:

┌─────────────┐      ┌──────────────────┐      ┌─────────────┐
│   App 1     │──────│  api-management  │──────│  PostgreSQL │
├─────────────┤      │  (REST + Kinde)  │      ├─────────────┤
│   App 2     │──────│                  │──────│    Redis    │
└─────────────┘      └──────────────────┘      └─────────────┘

These are the two real deployment shapes: the embedded library (self-hosted engine) and the managed service (hosted platform with the console).

Getting Started

Core Concepts

Resources

Tags

Delegation

Use Cases

Modeling Guides

Architecture Overview

System Architecture

Core Components

BedrockEngine

BedrockStore

REST API

Data Model

Evaluation Flow

ID Format

Deployment Options

Embedded Library

Managed Service (api-management)

Next Steps

Quickstart

Core Concepts

​System Architecture

​Core Components

​BedrockEngine

​BedrockStore

​REST API

​Data Model

​Evaluation Flow

​ID Format

​Deployment Options

​Embedded Library

​Managed Service (api-management)

​Next Steps

Quickstart

Core Concepts

System Architecture

Core Components

BedrockEngine

BedrockStore

REST API

Data Model

Evaluation Flow

ID Format

Deployment Options

Embedded Library

Managed Service (api-management)

Next Steps