Nexus PDP architecture
This page describes the processes inside the Permit Nexus PDP container, a self-hosted policy decision point (PDP), and the path one authorization request takes through them. Operators use it to plan network exposure and health probes, and to troubleshoot a Nexus PDP deployment. For what Nexus PDP is and when to choose it, see Permit Nexus PDP.
Nexus PDP runs every component in one container. The container exposes two listeners: the authorization API and the health endpoint.
Click the diagram to enlarge it.
The diagram labels the change stream with its internal name, WAL (write-ahead log). LOCAL_WAL is the container's durable local copy of the change stream. Other Nexus PDP pages call it the change stream.
Components inside the Nexus PDP container
Nexus PDP runs one Rust process that supervises two child processes: Open Policy Agent (OPA) and a NATS messaging server running as a leaf node.
| Component | Kind | Role |
|---|---|---|
| Authorization API | In-process server | Serves the public REST API on port 7000. Opens only after Nexus PDP is ready. |
| OPA policy engine | Supervised child process | Evaluates the Rego policy. Listens on loopback only, so nothing outside the container can reach OPA. |
| Embedded database | In-process (SurrealDB on RocksDB) | Stores your environment's authorization data on disk: users, tenants, resource instances, and relationships. |
| NATS leaf node | Supervised child process | Keeps the durable on-disk event store and holds the connection to Permit's control plane. |
| Change ingest and repair | In-process tasks | Apply incoming changes to the embedded database, detect gaps in the change stream, and rebuild the database when a gap cannot be closed. |
| Query and bundle loopback servers | In-process servers | Serve OPA its relationship data and its policy bundle over 127.0.0.1. |
| Health and readiness server | In-process server | Serves health endpoints on port 7001. Answers from process start, including during a long cold start. |
Ports used by Nexus PDP
| Port | Bound to | Purpose |
|---|---|---|
7000 | All interfaces | Authorization API. The only port your services call. |
7001 | All interfaces | Health and readiness endpoints. The port your orchestrator probes. |
7002 | Loopback | Query loopback server: serves OPA its relationship data |
7003 | Loopback | Bundle loopback server: serves OPA its Rego bundle |
8181 | Loopback | OPA |
4222 and 8222 | Loopback | NATS leaf node client port and monitoring port |
The container image exposes only ports 7000 and 7001. The other ports accept connections only from inside the container. To change ports 7000 and 7001, see Nexus PDP storage and port settings.
Decision path for a Nexus PDP authorization request
An authorization request passes through these hops inside the Nexus PDP container:
client → :7000 authorization API
→ 127.0.0.1 OPA
→ 127.0.0.1 query loopback
→ embedded database (local disk)
Each hop uses the loopback interface or local disk. Nexus PDP does not contact the Permit API to answer or authenticate a request, because the Nexus PDP binary does not include a Permit API client. The NATS connection to the control plane carries data updates only.
OPA evaluates the Rego policy. When the policy needs to know whether a user reaches a resource through a chain of roles and relationships, OPA calls the query loopback server, which answers from the embedded database. Relationship queries run against a database built for them, not against a JSON document in memory.
Request path and sync path in Nexus PDP
Nexus PDP separates serving decisions from keeping data current, so data sync never blocks a decision:
- The request path (authorization API, OPA, query loopback server, embedded database) reads from the embedded database.
- The sync path (NATS leaf node, change ingest, gap detector, rebuild orchestrator) writes to the embedded database on its own tasks.
The two paths meet only at the embedded database. As a result, a control-plane outage stops data updates but not decisions, and Nexus PDP keeps answering while a database rebuild runs. For the sync path in detail, see How Nexus PDP syncs data.
Next steps
- Permit Nexus PDP: what Nexus PDP is and when to choose it
- How Nexus PDP syncs data: sync, consistency, cold start, and sizing
- Nexus PDP feature parity: supported endpoints and capabilities
- Deploy Nexus PDP: storage, probes, logs, and the security model
- Nexus PDP configuration reference: environment variables