Architecture
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.
System overview
Section titled “System overview”How it works
Section titled “How it works”Ingest: LDAP to PostgreSQL
Section titled “Ingest: LDAP to PostgreSQL”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.
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.
Query: PostgreSQL to clients
Section titled “Query: PostgreSQL to clients”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.
Key concepts
Section titled “Key concepts”Transcribes
Section titled “Transcribes”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.
Events
Section titled “Events”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.
Virtual attributes
Section titled “Virtual attributes”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.
Channels
Section titled “Channels”A channel is a protocol endpoint. All channels share the same query engine, so results are consistent regardless of how you query.
| Channel | Protocol | Typical consumer |
|---|---|---|
| LDAP | LDAP v3 | Legacy apps, directory tools |
| REST | HTTP/JSON | Microservices, automation |
| GraphQL | HTTP/GraphQL | Frontends, flexible queries |
| gRPC (roadmap) | HTTP/2 + Protobuf | Service mesh, high-throughput |
| MCP | Model Context Protocol | AI coding assistants |
Each channel has its own auth rules, size limits, and protocol-specific features, but the query path is identical.
Filter formats
Section titled “Filter formats”Queries accept filters in four formats. Scribe auto-detects which one you’re using, so you pick whatever fits your context:
| Format | Example | Good for |
|---|---|---|
| FleX | cn = John | Config files, interactive use |
| JSON | {"cn": "John"} | SDKs, programmatic queries |
| SCIM | cn 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.
Change detection
Section titled “Change detection”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.
Related
Section titled “Related”- Start Here — Get running in 5 minutes
- Configuration — Configure transcribes and channels
- Channels — Protocol channels in depth
- Filters — FleX, JSON, SCIM, and LDAP filter syntax