> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedrock.quarry-systems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> How Bedrock components work together

## 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.

```typescript theme={null}
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:

```bash theme={null}
# 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](/concepts/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:

```typescript theme={null}
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).

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Set up Bedrock in your application
  </Card>

  <Card title="Core Concepts" icon="book" href="/concepts">
    Deep dive into authorization concepts
  </Card>
</CardGroup>