Data models

The long-lived structures that everyone in the agent agrees on. Most live in agent/structs/ (101 KB structs.go is the central catch-all) and the per-table files in agent/consul/state/.

Core domain types

Type	File	Notes
Node	agent/structs/structs.go	A registered Consul node (catalog row)
ServiceNode	agent/structs/structs.go	One service instance on a node
NodeService	agent/structs/structs.go	The service portion of a registration (kind, port, tags, meta, proxy)
HealthCheck	agent/structs/structs.go	A registered health check
CheckType, CheckDefinition	agent/structs/check_*.go	The runtime contract for check execution
RegisterRequest	agent/structs/structs.go	The full body of a catalog registration (node + services + checks)
KVPair	agent/structs/structs.go	Key/value entry
Session	agent/structs/structs.go	Lock holder + lease policy
Intention / IntentionMatch	agent/structs/connect_intention.go	Legacy intention (kept for compat)
ConfigEntry (interface)	agent/structs/config_entry.go	Implemented by every config-entry kind
ServiceConfigEntry, ProxyConfigEntry, ServiceRouterConfigEntry, ...	agent/structs/config_entry_*.go	Per-kind structs
CompiledDiscoveryChain	agent/structs/config_entry_discoverychain.go	The compiled DAG used by xDS
ACLToken, ACLPolicy, ACLRole, ACLAuthMethod, ACLBindingRule, ACLTemplatedPolicy	agent/structs/acl.go	ACL surface
CARoot, IndexedCARoots	agent/structs/connect_ca.go	Connect CA roots
IssuedCert, CASignRequest	agent/structs/connect.go	Leaf signing
Peering, PeeringSecret, PeeringTrustBundle	agent/structs/peering.go	Cluster peering records
FederationState	agent/structs/federation_state.go	Cross-DC routing state
Coordinate	agent/structs/coordinate.go	Vivaldi network coordinate
EnterpriseMeta	agent/structs/structs_ce.go	Multi-tenancy partition+namespace (no-op fields in CE)

agent/structs/testing*.go files contain fixture builders used everywhere in tests.

Generated artifacts

A lot of the wire format comes from protobuf:

• proto/private/pbconfigentry/config_entry.pb.go (349 KB) — config entries on the wire
• proto/private/pbpeering/peering.pb.go (91 KB) — peering messages
• proto/private/pbservice/, pbcommon/, pbacl/, ... — internal service messages
• proto-public/pbresource/resource.pb.go (66 KB) — public v2 resource service
• Per-package <thing>.deepcopy.go files (generated by deep-copy) implement structural copy

The mog tool generates conversion helpers between Go structs and proto messages so the agent's code can stay in Go-native shapes while the wire stays protobuf.

State store schema

agent/consul/state/schema.go is the registry of MemDB tables. Each table:

• Defines a primary index (typically id or name) and zero or more secondary indices.
• Holds a <Thing>Entry struct (or reuses an agent/structs/ type).
• Has dedicated accessors in a per-table file (catalog.go, kvs.go, acl.go, intention.go, etc.).
• Emits streaming events when applicable (*_events.go files).

Tables (selected):

Table	Backing file
nodes, services, service_kinds, health_checks, gateway_services	state/catalog.go
kvs, tombstones	state/kvs.go
sessions	state/session.go
acl-tokens, acl-policies, acl-roles, acl-auth-methods, acl-binding-rules	state/acl.go, state/acl_schema.go
config-entries	state/config_entry.go
connect-ca-config, connect-ca-roots, connect-ca-leaf, connect-ca-builtin	state/connect_ca.go
peering, peering-secrets, peering-trust-bundles	state/peering.go
prepared-queries	state/prepared_query.go
intentions (legacy)	state/intention.go
coordinate	state/coordinate.go
federation-state	state/federation_state.go
system-metadata	state/system_metadata.go

ACL identity model

Every authenticated subject (token, service, node) resolves to an acl.Authorizer. The model:

• A token has 0..N policies and 0..N roles directly.
• A token can also carry service identities and node identities, which expand to a templated policy via acl/acl_templated_policy.go.
• Roles bundle policies, services, and nodes for reuse.
• Auth methods + binding rules dynamically issue tokens with one or more roles based on claim selectors.

The compilation pipeline is in acl/acl.go.

SPIFFE identity

A mesh service's identity is a SPIFFE URI:

spiffe://<trust-domain>.consul/ns/<ns>/dc/<dc>/svc/<service>

Helpers in agent/connect/uri.go parse and emit these URIs. The trust domain is <dc>.consul by default; mesh peering shares trust bundles but each cluster keeps its own trust domain.

V2 resources

The pbresource.Resource envelope holds:

• id (Type + Tenancy + Name + UID)
• generation, version
• owner (parent reference for cascade delete)
• data (Any, the typed payload)
• status (controller-set per-condition map)
• metadata (KV labels)

Each registered resource type has its own protobuf definition under proto-public/pb<group>/.

Where models meet the wire

• HTTP JSON encoding uses Go struct tags directly. Many types have custom MarshalJSON / UnmarshalJSON for backwards compat.
• RPC msgpack uses codec (github.com/hashicorp/go-msgpack/v2).
• Protobuf is generated and used over gRPC.
• Snapshots use msgpack.