contributing: start an outline for more docs

Add diagrams for rpc routing and acl entity relationship
contributing: create directory structure for new docs
WIP diagram for catalog entities
Add overview diagram

Co-Authored-By: Kelly Devlin <[email protected]>

contributing/README.md

@@ -5,10 +5,25 @@ See [our contributing guide](../.github/CONTRIBUTING.md) to get started.
 This directory contains documentation intended for anyone interested in
 understanding, and contributing changes to, the Consul codebase.
 
-## Contents
+## Overview
+
+This documentation is organized into the following categories. Each category is 
+either a significant architectural layer, or major functional area of Consul.
+
+![Overview](./overview.svg)
+
+<sup>[source](./overview.mmd)</sup>
+
+## Contents 
 
 1. [Overview](./INTERNALS.md)
-2. [Configuration](./checklist-adding-config-fields.md)
-3. [Streaming](./streaming)
-4. [Network Areas](./network-areas)
-5. [Service Discovery](./service-discovery)
+1. [Agent Configuration](./config)
+1. [RPC](./rpc)
+1. [Cluster Persistence](./persistence)
+1. [Client Agent](./client-agent)
+1. [Service Discovery](./service-discovery)
+1. [Service Mesh (Connect)](./service-mesh)
+1. [Cluster Membership](./cluster-membership)
+1. [Key/Value Store](./kv)
+1. [ACL](./acl)
+1. [Multi-Cluster Federation](./cluster-federation)

contributing/acl/acl-entity-relationship.mmd

@@ -0,0 +1,28 @@
+erDiagram
+
+    Token
+    Policy
+    Role
+    ServiceIdentity
+    NodeIdentity
+    AuthMethod
+    BindingRule
+    Rule
+    // TODO: rules are made up of resources and x (enforcement decision or permission?)
+    // TODO: add Authorizer and Enforcement Decision
+
+    Policy ||--|{ Rule: grants
+    Role ||--|{ Policy: includes
+    Role }|--|{ ServiceIdentity: includes
+    Role }|--|{ NodeIdentity: includes
+
+    Token }|--|{ Policy: includes
+    Token }|--|{ Role: includes
+    Token }|--|{ ServiceIdentity: includes
+    Token }|--|{ NodeIdentity: includes
+
+    AuthMethod ||--|{ BindingRule: defines
+    AuthMethod ||--|{ Token: creates
+
+    ServiceIdentity ||--|{ Rule: implies
+    NodeIdentity ||--|{ Rule: implies

contributing/client-agent/README.md

@@ -0,0 +1,5 @@
+# Client Agent
+
+- agent/cache
+- agent/local (local state)
+- anti-entropy sync

contributing/cluster-federation/README.md

@@ -0,0 +1,4 @@
+# Multi-Cluster Federation
+
+1. [Network Areas](./network-areas)
+

contributing/cluster-membership/README.md

@@ -0,0 +1,7 @@
+# Cluster membership
+   - hashicorp/serf
+   - hashicorp/memberlist
+   - network coordinates
+   - consul events
+   - consul exec
+

contributing/config/README.md

@@ -0,0 +1,3 @@
+# Agent Configuration
+
+- [Checklist for adding a new field](./checklist-adding-config-fields.md)

contributing/consul-mermaid-theme.json

@@ -0,0 +1,4 @@
+{
+  "theme": "default",
+  "themeCSS": ".node rect { fill: rgb(220, 71, 125); stroke-width: 1; stroke: black; } .node .label { color: white; } "
+}

contributing/overview.mmd

@@ -0,0 +1,24 @@
+graph TD
+
+    ServiceMesh[Sercice Mesh]
+    ServiceDiscovery[Service Discovery]
+    ClusterMembership[Cluster Membership]
+    KV[Key/Value Store]
+    MultiClusterFederation[Multi-Cluster Federation]
+
+    ACL
+    AgentConfiguration[Agent Configuration]
+    ClientAgent[Client Agent]
+    RPC
+    ClusterPersistence[Cluster Persistence]
+
+    AgentConfiguration --> ClientAgent
+    ClientAgent --> RPC
+    ClientAgent --> ACL
+    RPC --> ClusterPersistence
+    RPC --> ACL
+
+    MultiClusterFederation --> ClusterMembership
+    MultiClusterFederation --> RPC
+    ServiceMesh --> ServiceDiscovery
+

contributing/persistence/README.md

@@ -0,0 +1,8 @@
+# Persistence
+
+- hashicorp/raft
+- state.Store - hashicorp/go-memdb
+- FSM
+- boltdb - https://github.com/boltdb/bolt (https://github.com/etcd-io/bbolt)
+- snapshot and restore
+

contributing/rpc/README.md

@@ -0,0 +1,6 @@
+# RPC
+
+- net/rpc - (in the stdlib)
+- [Streaming](./streaming)
+- routing of "RPC" requests
+