# authzed/spicedb architecture

> Architecture diagram of the GitHub repository authzed/spicedb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/authzed/spicedb
- Repository: https://github.com/authzed/spicedb

## Overview

SpiceDB is an authorization service: clients define a permission schema, write relationships, and ask whether a subject may perform an action on a resource. The README also documents caveated authorization and reverse-index queries; the tree exposes dedicated API, query, dispatch, and datastore subsystems for these capabilities. Sampled server and query-plan code supports the main service-to-evaluation path, while the README supplies the broader product workflow. Unsampled subsystem links are included only where their purpose is clear; exact internal wiring is not inferred.

Main entry points: [`internal/services/server.go`](https://github.com/authzed/spicedb/blob/main/internal/services/server.go) (gRPC services), [`pkg/datastore/datastore.go`](https://github.com/authzed/spicedb/blob/main/pkg/datastore/datastore.go) (Datastore interface), [`internal/services/v1/permissions.go`](https://github.com/authzed/spicedb/blob/main/internal/services/v1/permissions.go) (Permission API), [`internal/services/v1/permissions_queryplan.go`](https://github.com/authzed/spicedb/blob/main/internal/services/v1/permissions_queryplan.go) (Query planning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and server"]
  node_server["Server assembly<br/>[server.go]"]
  node_services["gRPC services<br/>[server.go]"]
  node_permissions["Permission API<br/>[permissions.go]"]
  node_schemaapi["Schema API<br/>[schema.go]"]
  node_relationshipapi["Relationship API<br/>[relationships.go]"]
  node_watch["Relationship watch<br/>[watch.go]"]
  node_gateway["HTTP gateway<br/>[gateway.go]"]
end

subgraph group_model["Authorization model"]
  node_schemacompiler["Schema compiler<br/>[compiler.go]"]
  node_schema["Schema typesystem<br/>[typesystem.go]"]
  node_caveats["Caveat evaluation<br/>[eval.go]"]
end

subgraph group_evaluation["Permission evaluation"]
  node_queryplan["Query planning"]
  node_query["Query engine<br/>[reader.go]"]
  node_graph["Permission graph<br/>[check.go]"]
  node_dispatch["Distributed dispatch<br/>[dispatch.go]"]
  node_bulkcheck["Bulk checks<br/>[bulkcheck.go]"]
  node_lookup["Reverse lookups"]
end

subgraph group_storage["Relationship storage"]
  node_datalayer["Data layer<br/>[datalayer.go]"]
  node_datastore["Datastore interface<br/>[datastore.go]"]
  node_engines["Datastore engines<br/>[engines.go]"]
  node_memdb[("Memory datastore<br/>[memdb.go]")]
end

subgraph group_operations["Operations"]
  node_cli["Server CLI<br/>[serve.go]"]
end

node_client(("Authorization client"))
node_db[("Relational database")]

node_client -->|"sends gRPC"| node_services
node_server -->|"registers services"| node_services
node_client -.->|"sends HTTP"| node_gateway
node_schemaapi -->|"compiles schema"| node_schemacompiler
node_schemacompiler -->|"builds typesystem"| node_schema
node_services -->|"registers"| node_permissions
node_services -->|"registers"| node_schemaapi
node_services -->|"registers"| node_relationshipapi
node_services -->|"registers"| node_watch
node_permissions -->|"plans checks"| node_queryplan
node_queryplan -->|"loads schema"| node_schema
node_queryplan -->|"builds query"| node_query
node_queryplan -->|"dispatches evaluation"| node_dispatch
node_query -->|"evaluates permission"| node_graph
node_graph -->|"reads relationships"| node_datastore
node_graph -->|"evaluates caveats"| node_caveats
node_permissions -->|"supports bulk checks"| node_bulkcheck
node_permissions -->|"serves reverse queries"| node_lookup
node_relationshipapi -->|"writes relationships"| node_datalayer
node_schemaapi -->|"stores schema"| node_datalayer
node_datalayer -->|"adapts access"| node_datastore
node_engines -->|"registers engines"| node_datastore
node_datastore -->|"persists data"| node_db
node_engines -->|"selects engine"| node_memdb
node_datastore -->|"uses implementation"| node_memdb
node_cli -->|"configures server"| node_server

click node_server "https://github.com/authzed/spicedb/blob/main/pkg/cmd/server/server.go"
click node_services "https://github.com/authzed/spicedb/blob/main/internal/services/server.go"
click node_permissions "https://github.com/authzed/spicedb/blob/main/internal/services/v1/permissions.go"
click node_schemaapi "https://github.com/authzed/spicedb/blob/main/internal/services/v1/schema.go"
click node_relationshipapi "https://github.com/authzed/spicedb/blob/main/internal/services/v1/relationships.go"
click node_watch "https://github.com/authzed/spicedb/blob/main/internal/services/v1/watch.go"
click node_gateway "https://github.com/authzed/spicedb/blob/main/internal/gateway/gateway.go"
click node_schemacompiler "https://github.com/authzed/spicedb/blob/main/pkg/schemadsl/compiler/compiler.go"
click node_schema "https://github.com/authzed/spicedb/blob/main/pkg/schema/typesystem.go"
click node_caveats "https://github.com/authzed/spicedb/blob/main/pkg/caveats/eval.go"
click node_queryplan "https://github.com/authzed/spicedb/blob/main/internal/services/v1/permissions_queryplan.go"
click node_query "https://github.com/authzed/spicedb/blob/main/pkg/query/reader.go"
click node_graph "https://github.com/authzed/spicedb/blob/main/internal/graph/check.go"
click node_dispatch "https://github.com/authzed/spicedb/blob/main/internal/dispatch/dispatch.go"
click node_bulkcheck "https://github.com/authzed/spicedb/blob/main/internal/services/v1/bulkcheck.go"
click node_lookup "https://github.com/authzed/spicedb/blob/main/internal/graph/lookupresources2.go"
click node_datalayer "https://github.com/authzed/spicedb/blob/main/pkg/datalayer/datalayer.go"
click node_datastore "https://github.com/authzed/spicedb/blob/main/pkg/datastore/datastore.go"
click node_engines "https://github.com/authzed/spicedb/blob/main/pkg/cmd/datastore/engines.go"
click node_memdb "https://github.com/authzed/spicedb/blob/main/internal/datastore/memdb/memdb.go"
click node_cli "https://github.com/authzed/spicedb/blob/main/pkg/cmd/serve.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_services,node_permissions,node_schemaapi,node_relationshipapi,node_watch,node_gateway,node_client toneBlue
class node_schemacompiler,node_schema,node_caveats,node_db toneAmber
class node_queryplan,node_query,node_graph,node_dispatch,node_bulkcheck,node_lookup toneMint
class node_datalayer,node_datastore,node_engines,node_memdb toneRose
class node_cli toneIndigo
```

## Components

### API and server

- [Server assembly](https://github.com/authzed/spicedb/blob/main/pkg/cmd/server/server.go): `pkg/cmd/server/server.go`
- [gRPC services](https://github.com/authzed/spicedb/blob/main/internal/services/server.go): `internal/services/server.go`
- [Permission API](https://github.com/authzed/spicedb/blob/main/internal/services/v1/permissions.go): `internal/services/v1/permissions.go`
- [Schema API](https://github.com/authzed/spicedb/blob/main/internal/services/v1/schema.go): `internal/services/v1/schema.go`
- [Relationship API](https://github.com/authzed/spicedb/blob/main/internal/services/v1/relationships.go): `internal/services/v1/relationships.go`
- [Relationship watch](https://github.com/authzed/spicedb/blob/main/internal/services/v1/watch.go): `internal/services/v1/watch.go`
- [HTTP gateway](https://github.com/authzed/spicedb/blob/main/internal/gateway/gateway.go): `internal/gateway/gateway.go`

### Authorization model

- [Schema compiler](https://github.com/authzed/spicedb/blob/main/pkg/schemadsl/compiler/compiler.go): `pkg/schemadsl/compiler/compiler.go`
- [Schema typesystem](https://github.com/authzed/spicedb/blob/main/pkg/schema/typesystem.go): `pkg/schema/typesystem.go`
- [Caveat evaluation](https://github.com/authzed/spicedb/blob/main/pkg/caveats/eval.go): `pkg/caveats/eval.go`

### Permission evaluation

- [Query planning](https://github.com/authzed/spicedb/blob/main/internal/services/v1/permissions_queryplan.go): `internal/services/v1/permissions_queryplan.go`
- [Query engine](https://github.com/authzed/spicedb/blob/main/pkg/query/reader.go): `pkg/query/reader.go`
- [Permission graph](https://github.com/authzed/spicedb/blob/main/internal/graph/check.go): `internal/graph/check.go`
- [Distributed dispatch](https://github.com/authzed/spicedb/blob/main/internal/dispatch/dispatch.go): `internal/dispatch/dispatch.go`
- [Bulk checks](https://github.com/authzed/spicedb/blob/main/internal/services/v1/bulkcheck.go): `internal/services/v1/bulkcheck.go`
- [Reverse lookups](https://github.com/authzed/spicedb/blob/main/internal/graph/lookupresources2.go): `internal/graph/lookupresources2.go`

### Relationship storage

- [Data layer](https://github.com/authzed/spicedb/blob/main/pkg/datalayer/datalayer.go): `pkg/datalayer/datalayer.go`
- [Datastore interface](https://github.com/authzed/spicedb/blob/main/pkg/datastore/datastore.go): `pkg/datastore/datastore.go`
- [Datastore engines](https://github.com/authzed/spicedb/blob/main/pkg/cmd/datastore/engines.go): `pkg/cmd/datastore/engines.go`
- [Memory datastore](https://github.com/authzed/spicedb/blob/main/internal/datastore/memdb/memdb.go): `internal/datastore/memdb/memdb.go`

### Operations

- [Server CLI](https://github.com/authzed/spicedb/blob/main/pkg/cmd/serve.go): `pkg/cmd/serve.go`

### Other components

- **Authorization client**
- **Relational database**

## Connections

- Authorization client → gRPC services: sends gRPC
- Server assembly → gRPC services: registers services
- Authorization client → HTTP gateway: sends HTTP
- Schema API → Schema compiler: compiles schema
- Schema compiler → Schema typesystem: builds typesystem
- gRPC services → Permission API: registers
- gRPC services → Schema API: registers
- gRPC services → Relationship API: registers
- gRPC services → Relationship watch: registers
- Permission API → Query planning: plans checks
- Query planning → Schema typesystem: loads schema
- Query planning → Query engine: builds query
- Query planning → Distributed dispatch: dispatches evaluation
- Query engine → Permission graph: evaluates permission
- Permission graph → Datastore interface: reads relationships
- Permission graph → Caveat evaluation: evaluates caveats
- Permission API → Bulk checks: supports bulk checks
- Permission API → Reverse lookups: serves reverse queries
- Relationship API → Data layer: writes relationships
- Schema API → Data layer: stores schema
- Data layer → Datastore interface: adapts access
- Datastore engines → Datastore interface: registers engines
- Datastore interface → Relational database: persists data
- Datastore engines → Memory datastore: selects engine
- Datastore interface → Memory datastore: uses implementation
- Server CLI → Server assembly: configures server