architecture: overview and handbook by croadfeldt · Pull Request #66 · dcm-project/dcm

croadfeldt · 2026-06-16T21:43:19Z

UC map — Cross-cutting substrate — supports all UCs.

Implements UDLM contracts: dcm-project/udlm#15 dcm-project/udlm#16 dcm-project/udlm#17 — foundations & layering of the UDLM substrate this architecture realizes.
Depends on the UDLM substrate landing first (Wave C); wave index: dcm-project/udlm#35.

Decision: Architecture overview, layering, design principles, and operator handbook as one unit.

Part of the staged croadfeldt/dcm → dcm-project/dcm upstreaming: single-concern PRs, ≤3k lines, logical boundaries. (1619 lines, 7 files.)

Draft — pending team re-engagement.

Architecture overview, layering, design principles, and operator handbook as one unit. Signed-off-by: Chris Roadfeldt <chris@roadfeldt.com>

pkliczewski · 2026-06-29T10:29:10Z

+
+---
+
+## 1. API Path Format (AEP Colon Syntax)


I am not sure about the need for this. Why not to define what we want to use from AEP or what we don't want to use.

This file isn't the AEP-adoption policy — it's a point-in-time consistency audit, the record of naming/path/terminology drift I found and fixed across the docs. What DCM actually adopts from AEP (and what it deliberately doesn't) lives in adopted-standards-dcm.md. Happy to add a pointer from here to that doc so the split is obvious — or, if you'd rather this audit record not sit in the architecture handbook at all, I'll move it out of the PR; it's history, not normative.

pkliczewski · 2026-06-29T11:40:06Z

+
+## 2. Approval tier model (runtime enforcement)
+
+UDLM defines the authority tier vocabulary (auto / reviewed / verified /


please clarify what this means

Thanks — you're right the terms landed cold. I added a one-line gloss at first mention: the four tiers are an escalating human-gate ladder — auto = no human gate, reviewed = one approver, verified = two independent approvers, authorized = a quorum vote by a named group. UDLM owns the vocabulary; the table right below records how DCM enforces each.

pkliczewski · 2026-06-29T11:44:15Z

+calling the vote-recording API. A Slack bot that collects emoji reactions and
+then calls DCM's Admin API is a valid implementation.
+
+### 2.1 Admin API as integration point


I am not sure whether this is about request approval but this should be done by approval policy/logic. If delegated to third party system it should be approved there. Why do we need this api?

Agreed — the decision happens wherever the org runs it, and DCM deliberately doesn't build a deliberation/voting platform (the list just above is only membership, quorum, notification, recording). The endpoint exists only so the external system can report the outcome back: DCM holds the request pipeline, so it has to be told the result to advance or reject and to record it in its own audit trail. Approve in ServiceNow/Slack/Jira; call the endpoint to record what was decided.

pkliczewski · 2026-06-29T11:47:14Z

+
+### 2.2 Deadline and escalation
+
+DCM manages the approval window and fires escalation notifications:


assuming that dcm will take responsibility for escalations this config is not enough. How do we know who is the recipient of the escalation? should it be reoccurring? if so for how long? should it be static value or exponential?

Fair — escalate alone is under-specified, and the deeper answer is that the ladder is profile/organization-defined, not a fixed platform one. ADR-007 (UDLM) settles this: profiles are composed sets that set floors, and the approval/escalation ladder is part of a profile's operational config, not something the platform hard-codes. The platform supplies the mechanism — escalation target group (platform-admin by default) via the Notification Service, with a bounded repeat cadence and max attempts; the profile supplies the ladder. So the recipient and retry behavior are declared, not ad hoc.

pkliczewski · 2026-06-29T11:50:39Z

+
+## 3. Profile-governed system constraints
+
+DCM ships six built-in profiles (`minimal`, `dev`, `standard`, `prod`, `fsi`,


built-in profiles are restrictive and the admin should be able to decide what they need and to me it should be codified in policies. Is there any other place or reason why we constrain the system?

Good push. The six built-ins are presets, not a closed set: ADR-007 (UDLM) makes profiles first-class composed sets that set floors — built-ins are immutable, and any modification forks a new custom profile (copy-on-write, reproducible and audited). Everything you'd want to tune — thresholds, tiers, automation level, review windows — is admin-tunable that way; the only thing not switchable is the small non-negotiable floor (CPX-001 and the other security invariants). So it's constrained only at that floor, on purpose.

pkliczewski · 2026-06-29T11:54:59Z

+
+---
+
+## 6. System policies (DCM realization)


how this be enforced for policies defined by admins/SRE?

These apply to DCM's project documentation, not to admin/SRE policy artifacts — so there's nothing to enforce at runtime here. Admin/SRE-authored policies are governed separately by the policy validation pipeline (schema validation plus the governance policies), not by these doc-discipline rules. Happy to make that scope explicit in the doc so it doesn't read as a runtime constraint.

pkliczewski · 2026-06-29T11:57:53Z

+│    • ingress / egress, APIs, service boundaries                 │
+│    • drift detection, recovery utilities, expiration            │
+│    • persistence (PostgreSQL mandated for this realization)     │
+│    • specific 9-layer canonical location hierarchy              │


please clarify what 9-layer hierarchy is

Thanks — that was a dangling forward reference. I added the gloss and link at first mention: it's DCM's canonical location topology, Country → Region → … → Unit, nine levels — DCM's concrete choice for UDLM's abstract layered-topology contract — fully defined in topology/canonical-9-layer-hierarchy.md.

pkliczewski · 2026-06-29T14:43:47Z

+
+## Compatibility model (LOCKED)
+
+**UDLM enforces wire-level compatibility at the data/event/contract boundary;


what about backward compatibility for udlm? how it should be evolved?

UDLM's evolution is governed in the UDLM repo, not here: SPEC MAJOR/MINOR, with wire-level compatibility guaranteed within a MAJOR (UDLM CONFORMANCE §9). DCM pins a UDLM MAJOR, and the "Compatibility model (LOCKED)" section just below states DCM enforces wire-compat at the data/event/contract boundary. So backward compatibility is a UDLM-side guarantee DCM consumes; happy to add the cross-link to the UDLM versioning doc so that isn't left implicit.

pkliczewski · 2026-06-29T14:52:20Z

+
+DCM ships with six built-in profiles: `minimal`, `dev`, `standard`, `prod`,
+`fsi`, `sovereign`. The profile controls dozens of enforcement and threshold
+settings simultaneously: credential lifetimes, TLS requirements, MFA


now I see what configuration profiles influence. I see a gap with this. I have been thinking about the profiles for infrastructure DCM manages where as they are purely about the control plane. How do we cover the infra?

This is a genuinely important line to draw — thank you. I added a subsection (§5.1, "Profiles govern the control plane, not the managed infrastructure"): profiles govern how the control plane behaves — strictness, thresholds, automation — while the infrastructure DCM manages is shaped by a different set of levers (placement/validation/transformation policies, catalog and composite-service definitions, and provider capability declarations). Profile = how the control plane operates; policy + catalog + provider = what gets built and under what constraints.

pkliczewski · 2026-06-29T15:14:29Z

+
+---
+
+## Reading order for new contributors


this should be at the beginning of this markdown

Agreed — I moved "Reading order for new contributors" up to right after the intro, ahead of the repo-organization tables. It's the first thing a new reader needs.

Brings this PR's files up to the current DCM spec state (post UDLM/DCM separation, AEP alignment, taxonomy reconciliation, and review resolutions). Content-only update on existing paths. Signed-off-by: croadfeldt <chris@roadfeldt.com>

review: resolve open review comments (dcm #64/#66/#69 doc edits)

croadfeldt · 2026-07-28T05:27:19Z

Thanks @pkliczewski — captured, not closed. Superseded by the ordered, scoped set (#109–#117), tracked in #108; your feedback carries forward as CF-7 (profiles vs policies → the ADR-049/050 invariant-vs-policy split), CF-6 (adopt AEP by reference), CF-12 (legibility). See #108; please re-review on the new set.

architecture: overview and handbook

bff3c74

Architecture overview, layering, design principles, and operator handbook as one unit. Signed-off-by: Chris Roadfeldt <chris@roadfeldt.com>

croadfeldt force-pushed the pr/da1-arch-overview branch from d426893 to bff3c74 Compare June 17, 2026 16:43

pkliczewski reviewed Jun 29, 2026

View reviewed changes

sync: update to current upstream (dcm main)

67663cc

Brings this PR's files up to the current DCM spec state (post UDLM/DCM separation, AEP alignment, taxonomy reconciliation, and review resolutions). Content-only update on existing paths. Signed-off-by: croadfeldt <chris@roadfeldt.com>

This was referenced Jul 8, 2026

DCM realization (Wave D): reading order + UDLM dependency gate #104

Open

review: resolve open review comments (dcm #64/#66/#69 doc edits) croadfeldt/dcm#40

Merged

croadfeldt referenced this pull request in croadfeldt/dcm Jul 10, 2026

Merge pull request #40 from croadfeldt/review/comment-resolution

9aef1e5

review: resolve open review comments (dcm #64/#66/#69 doc edits)

croadfeldt force-pushed the pr/da1-arch-overview branch 2 times, most recently from e740b32 to 67663cc Compare July 11, 2026 00:00

croadfeldt added a commit that referenced this pull request Jul 11, 2026

sync: apply merged review edits from croadfeldt (dcm #64/#66/#69)

f7543b9

croadfeldt added a commit that referenced this pull request Jul 11, 2026

sync: apply merged review edits from croadfeldt (dcm #64/#66/#69)

0d1c5b5

croadfeldt added a commit that referenced this pull request Jul 11, 2026

sync: apply merged review edits from croadfeldt (dcm #64/#66/#69)

affad6e

croadfeldt referenced this pull request in croadfeldt/dcm Jul 12, 2026

Merge pull request #40 from croadfeldt/review/comment-resolution

caae208

review: resolve open review comments (dcm #64/#66/#69 doc edits)

sync: apply merged review edits from croadfeldt (dcm #64/#66/#69)

65ddc44

croadfeldt force-pushed the pr/da1-arch-overview branch from 0d1c5b5 to 65ddc44 Compare July 15, 2026 04:06

croadfeldt closed this Jul 28, 2026


		## 2. Approval tier model (runtime enforcement)

		UDLM defines the authority tier vocabulary (auto / reviewed / verified /


		### 2.2 Deadline and escalation

		DCM manages the approval window and fires escalation notifications:


		## 3. Profile-governed system constraints

		DCM ships six built-in profiles (`minimal`, `dev`, `standard`, `prod`, `fsi`,


		## Compatibility model (LOCKED)

		**UDLM enforces wire-level compatibility at the data/event/contract boundary;

Uh oh!

Conversation

croadfeldt commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

croadfeldt commented Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

croadfeldt commented Jun 16, 2026 •

edited

Loading