diff --git a/contributing/INTERNALS.md b/contributing/INTERNALS.md
index 1e3753647..1fe71ad02 100644
--- a/contributing/INTERNALS.md
+++ b/contributing/INTERNALS.md
@@ -36,7 +36,6 @@ There are several other top-level packages used internally by Consul as well as
| Directory | Contents |
| --------- | -------- |
-| [acl](https://github.com/hashicorp/consul/tree/main/api) | This supports the underlying policy engine for Consul's [ACL](https://www.consul.io/docs/guides/acl.html) system. |
| [api](https://github.com/hashicorp/consul/tree/main/api) | This `api` package provides an official Go API client for Consul, which is also used by Consul's [CLI](https://www.consul.io/docs/commands/index.html) commands to communicate with the local Consul agent. |
| [api/watch](https://github.com/hashicorp/consul/tree/main/api/watch) | This has implementation details for Consul's [watches](https://www.consul.io/docs/agent/watches.html), used both internally to Consul and by the [watch CLI command](https://www.consul.io/docs/commands/watch.html). |
| [website](https://github.com/hashicorp/consul/tree/main/website) | This has the full source code for [consul.io](https://www.consul.io/). Pull requests can update the source code and Consul's documentation all together. |
diff --git a/contributing/acl/README.md b/contributing/acl/README.md
new file mode 100644
index 000000000..2be733c3b
--- /dev/null
+++ b/contributing/acl/README.md
@@ -0,0 +1,35 @@
+# ACL
+
+This section is a work in progress.
+
+The ACL subsystem is responsible for authenticating and authorizing access to Consul
+operations ([HTTP API], and [RPC]).
+
+[HTTP API]: ../http-api
+[RPC]: ../rpc
+
+## ACL Entities
+
+There are many entities in the ACL subsystem. The diagram below shows the relationship
+between the entities.
+
+
+
+[source](./erd.mmd)
+
+ACL Tokens are at the center of the ACL system. Tokens are associated with a set of
+Policies, and Roles.
+
+AuthMethods, which consist of BindingRules, are a mechanism for creating ACL Tokens from
+policies stored in external systems (ex: kubernetes, JWT, or OIDC).
+
+Roles are a set of policies associated with a named role, and ServiceIdentity and
+NodeIdentity are policy templates that are associated with a specific service or node and
+can be rendered into a full policy.
+
+Each Policy contains a set of rules. Each rule relates to a specific resource, and
+includes an AccessLevel (read, write, list or deny).
+
+An ACL Token can be resolved into an Authorizer. The Authorizer is what is used by the
+[HTTP API], and [RPC] endpoints to determine if an operation is allowed or forbidden (the
+enforcement decision).
diff --git a/contributing/acl/acl-entity-relationship.svg b/contributing/acl/acl-entity-relationship.svg
deleted file mode 100644
index 8b9f57c72..000000000
--- a/contributing/acl/acl-entity-relationship.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/contributing/acl/acl-entity-relationship.mmd b/contributing/acl/erd.mmd
similarity index 77%
rename from contributing/acl/acl-entity-relationship.mmd
rename to contributing/acl/erd.mmd
index 87031aabe..3a9ec446c 100644
--- a/contributing/acl/acl-entity-relationship.mmd
+++ b/contributing/acl/erd.mmd
@@ -7,9 +7,10 @@ erDiagram
NodeIdentity
AuthMethod
BindingRule
- Rule
- // TODO: rules are made up of resources and x (enforcement decision or permission?)
- // TODO: add Authorizer and Enforcement Decision
+ Rule {
+ string Resource
+ enum AccessLevel
+ }
Policy ||--|{ Rule: grants
Role ||--|{ Policy: includes
@@ -26,3 +27,7 @@ erDiagram
ServiceIdentity ||--|{ Rule: implies
NodeIdentity ||--|{ Rule: implies
+
+ Token ||--|| Authorizer: "resolves to"
+ Authorizer ||--|{ EnforcementDecision: produces
+
diff --git a/contributing/acl/erd.svg b/contributing/acl/erd.svg
new file mode 100644
index 000000000..47c4f8aca
--- /dev/null
+++ b/contributing/acl/erd.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/contributing/consul-mermaid-theme.json b/contributing/consul-mermaid-theme.json
index c847b2cb8..c3823254b 100644
--- a/contributing/consul-mermaid-theme.json
+++ b/contributing/consul-mermaid-theme.json
@@ -1,4 +1,4 @@
{
"theme": "default",
- "themeCSS": ".node rect { fill: rgb(220, 71, 125); stroke-width: 1; stroke: black; } .node .label { color: white; }; .cluster rect { fill: #f0f0f0; stroke-width: 1px; stroke: #333}; .edgeLabel { background-color: #f0f0f0; }"
+ "themeCSS": ".node rect, .er.entityBox { fill: rgb(220, 71, 125); stroke-width: 1; stroke: black; } .node .label { color: white; }; .cluster rect { fill: #f0f0f0; stroke-width: 1px; stroke: #333}; .edgeLabel { background-color: #f0f0f0; }; .er.entityBox + .er.entityLabel { fill: white }; .er.attributeBoxEven, .er.attributeBoxOdd { fill: #fff; stroke: #777 }"
}