Skip to content

Architecture

LDAP sourcesScribeYour appssynchronizesserves
LDAP sourcesScribeYour appssynchronizesserves
Scribe keeps directory data current and makes it available through several APIs.

You can see what Scribe stores and how client applications access it.

Next: Change detection

Your LDAP directories hold identity data. Your apps speak different protocols. IdentityScribe sits between them: it syncs from LDAP into PostgreSQL, then serves that data through LDAP, REST, GraphQL, or MCP — whichever your app needs.

LDAP SOURCESIDENTITYSCRIBEPOSTGRESQLCHANNELSActive DirectoryeDirectoryOpenLDAPOther LDAP v3Transcriptiondetect · mapHistoryappend-onlyEntriescurrentQuery engineshared by allLDAPRESTGraphQLMCPchangesappendsupdatesreadsserves
LDAP SOURCESIDENTITYSCRIBEPOSTGRESQLCHANNELSActive DirectoryeDirectoryOpenLDAPOther LDAP v3Transcriptiondetect · mapHistoryappend-onlyEntriescurrentQuery engineshared by allLDAPRESTGraphQLMCPchangesappendsupdatesreadsserves
LDAP changes become append-only history and current entries in PostgreSQL, and every available channel reads them through one query engine.

Scribe watches your LDAP sources for changes. It uses persistent search (real-time push from the directory) where supported, and falls back to polling (periodic queries for entries modified since the last check). A background reconciliation process periodically verifies that nothing was missed.

Transcription detects the change type (add, modify, move, or delete), applies attribute mappings, appends an event to the history, and updates the entry’s current state. If an entry’s attribute hash (its ETag) hasn’t changed, no new event is written, which keeps reconciliation cheap even for directories with millions of entries.

EVENT HISTORY · APPEND-ONLYUP TO 09:30Add09:14 createdModify09:22 emailMove09:35 new OUDelete09:41 deletedRead as of 09:30user, new emailCurrent statedeleted at 09:41thenthenthenreconstructsderives
EVENT HISTORY · APPEND-ONLYUP TO 09:30Add09:14 createdModify09:22 emailMove09:35 new OUDelete09:41 deletedRead as of 09:30user, new emailCurrent statedeleted at 09:41thenthenthenreconstructsderives
Every synchronized change appends an event; a point-in-time read reconstructs earlier state from those events without changing the history.

Current entries change; during synchronization the history is only appended to. That is what makes point-in-time queries and full audit history possible. The one exception is a history repair that some upgrades run; see Data Model. See Data Model for details.

CHANNELSONE QUERY PIPELINELDAPRESTGraphQLMCPNormalizeparse · validatePlanchoose strategyCompileprepare requestExecuteread · returnPostgreSQLqueriesvalid querysearch strategyprepared requestreadssame results
CHANNELSONE QUERY PIPELINELDAPRESTGraphQLMCPNormalizeparse · validatePlanchoose strategyCompileprepare requestExecuteread · returnPostgreSQLqueriesvalid querysearch strategyprepared requestreadssame results
All locally served channel queries share the same four query stages; only the response format differs, so the same query returns the same entries on every channel.

Normalize also resolves attribute aliases to their canonical names, so two channels that spell an attribute differently still ask the same question. The channel decides only the wire format. LDAP requests that Scribe delegates to the directory bypass this pipeline.

A transcribe tells Scribe what to sync from an LDAP source. You define one per entry type — users, groups, devices, whatever your directory holds. Each transcribe specifies a base DN, filter, scope, attribute mappings, and indexes.

Scribe processes transcribes alphabetically. Each runs its own change detection loop. You can enable or disable individual transcribes without restarting. See Data Model for concepts, Attribute Modeling for stored-versus-virtual attribute decisions, and Transcribes configuration for the full reference.

Every change Scribe detects produces an event — add, modify, move, or delete — appended to the history. Each has a unique position and timestamp. The current entry is a snapshot of the latest state. This is what makes audit history and point-in-time queries possible.

See Data Model for event types, data formats, and examples.

Some attributes are computed at query time rather than stored. The classic example is memberOf, which can expose a user’s groups from stored group membership data.

Use Attribute Modeling to decide which relationship side to store. See Data Model for configuration examples.

A channel is a protocol endpoint. All channels share the same query engine, so results are consistent regardless of how you query.

ChannelProtocolTypical consumer
LDAPLDAP v3Legacy apps, directory tools
RESTHTTP/JSONMicroservices, automation
GraphQLHTTP/GraphQLFrontends, flexible queries
gRPC (roadmap)HTTP/2 + ProtobufService mesh, high-throughput
MCPModel Context ProtocolAI coding assistants

Each channel has its own auth rules, size limits, and protocol-specific features, but the query path is identical.

Queries accept filters in four formats. Scribe auto-detects which one you’re using, so you pick whatever fits your context:

FormatExampleGood for
FleXcn = JohnConfig files, interactive use
JSON{"cn": "John"}SDKs, programmatic queries
SCIMcn eq "John"SCIM-aware systems
LDAP(cn=John)LDAP clients, existing queries

All four support the same operations: equality, prefix, contains, and boolean logic. FleX and JSON also support attribute groups — searching multiple fields with a single condition (e.g., cn|mail = john matches against both cn and mail).

Filters understand temporal references too. Instead of computing timestamps, you can write modifyTimestamp ge now-1h or createTimestamp ge last 7 days in any format.

See Filters for the full syntax reference.

Scribe uses two kinds of change detection — live detection and reconciliation:

  • Persistent search — real-time push notifications from the LDAP server. Used when the directory supports it.
  • Polling — periodic queries for entries modified since the last check. Used when persistent search isn’t available.
  • Reconciliation — a separate full check at startup and on a configured schedule. Catches anything live detection missed: network glitches, directory failovers, entries modified while Scribe was down.