Skip to content

docs: Reorganize README and architecture documentation#64

Open
scotwells wants to merge 15 commits into
mainfrom
docs/architecture-reorg
Open

docs: Reorganize README and architecture documentation#64
scotwells wants to merge 15 commits into
mainfrom
docs/architecture-reorg

Conversation

@scotwells

@scotwells scotwells commented Jul 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What this does

Reshapes the project's documentation so it's easier to read and points people to the right place.

The README had grown into a deep technical reference. This splits it into two things: a short, friendly overview of what the DNS service is and does, and a dedicated architecture section for readers who want the bigger picture of how it all fits together.

What changed

  • A concise README — a quick tour of what the service does, how to get started, and links out to everything else. No more wall of technical detail on the front page.
  • An organized architecture section under docs/architecture/ covering:
    • a high-level overview of the service and why it exists in the platform,
    • how the pieces are deployed and work together,
    • how DNS changes flow through the system and how long they take to show up,
    • the API that users work with, and
    • the DNS backends the service supports (with PowerDNS documented in detail).
  • Diagrams throughout, so the architecture is easy to follow at a glance.

Notes

  • Documentation only — no changes to the product itself.
  • The writing follows a plain-language style, and the docs were reviewed for accuracy against how the service actually behaves.

scotwells and others added 8 commits July 24, 2026 12:23
@scotwells @claude
docs: Reorganize README and architecture documentation
edfbf9b 
Reshape the README into a concise, product-focused overview and move
the detailed system design into a dedicated docs/architecture/ folder,
following the house style used by milo-os activity and search.

- README: product overview of capabilities, a short "how it works",
  deploy quickstarts, and links out to the architecture docs. The CRD
  field dump moves into the architecture API reference.
- docs/architecture/README.md: system context, core concepts, tech
  stack, and API resource summary with C4 (Mermaid) diagrams.
- docs/architecture/topology.md: generic reference topology — replicator
  and downstream agent roles, control planes, discovery modes, and the
  authoritative serving layer with state replication.
- docs/architecture/replication.md: shadow objects, namespace mapping,
  status synthesis, zone ownership accounting, and default SOA/NS.
- docs/architecture/api-reference.md: full CRD schema, conditions, and
  DNSOperator server config.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@scotwells @claude
docs: Render architecture C4 diagrams with PlantUML + Datum theme
8b15136 
Replace the inline Mermaid diagrams with committed C4-PlantUML diagrams
following the datum-cloud/enhancements convention: .puml source styled
with the shared datum-theme.puml, rendered to PNG via the plantuml
Docker image, committed alongside their source, and referenced from the
docs with <img> tags.

- docs/architecture/diagrams/: system-context, container-view, and
  replication-flow .puml sources + rendered PNGs, plus the shared
  datum-theme.puml and a README documenting the workflow.
- docs/Taskfile.yaml: diagrams render/validate/clean tasks driving the
  plantuml/plantuml Docker image.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@scotwells @claude
docs: Add backend architecture, drop activity, apply tech-writing style
fac7aff 
- Scope out the Activity Service: it is a platform capability the DNS
  operator consumes, not part of the DNS architecture. Removed from the
  system-context diagram, tech stack, topology, and README.
- Add docs/architecture/backends/ documenting the pluggable backend
  model as an extension point, with PowerDNS as one available backend on
  its own page (record translation, programming, storage/serving,
  configuration) plus a C4 component diagram. Move PowerDNS-specific
  connection settings out of the API reference.
- Revise all architecture docs for the Google Technical Writing
  guidelines: active voice, present tense, concrete subjects,
  unambiguous pronouns, and consistent terminology.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@scotwells @claude
docs: Document PowerDNS propagation timing
74e8f83 
Add a "Propagation and Timing" section to the PowerDNS backend doc so
readers understand how long DNS changes take to reach end users. Break
the path into four stages — reconcile, authoritative write, replicate to
serving nodes, and resolver caching — with the setting that governs each,
and explain that record TTL (not the replication pipeline) dominates
end-user-visible propagation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@scotwells @claude
docs: Frame the operator as a component of the DNS service
7887470 
The operator is one component of the DNS service, not the service
itself. Rename the system-level framing to "DNS service" and reserve
"DNS operator" for the control-plane component.

- Architecture overview and diagrams retitled to "DNS Service"; the
  operator is introduced as the control-plane component alongside the
  backend, serving layer, and state store.
- README retitled and reworded to describe the service, noting that this
  repository provides the operator component.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@scotwells @claude
docs: Name LightningStream poll intervals in PowerDNS timing
982f969 
The propagation section referred to snapshot and poll intervals
abstractly. Document the actual LightningStream settings and their
defaults (lmdb_poll_interval 1s, storage_poll_interval 1s,
storage_force_snapshot_interval 4h, storage_retry_interval 5s), which
the deployment runs unchanged, so readers can see that stage-3
replication is a few seconds and how to tune it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@scotwells @claude
docs: Show platform context in the DNS system-context diagram
96c8385 
The system-context diagram showed only direct actors, not why DNS
exists in the platform. Add the surrounding platform systems it serves:
the Domains capability that verifies domain ownership, and platform
services (networking, ingress, TLS issuance) that publish records to
expose workloads and validate domain control. Reword the overview's
System Context prose to explain that motivation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@scotwells @claude
docs: Fix inaccuracies found by adversarial validation
376ad40 
An adversarial multi-agent review validated the architecture docs
against the code and deployment and confirmed nine discrepancies. Fixes:

- README quickstart applied `config/agent`, which has no Namespace and no
  storage backend and cannot run alone. Point it at
  `config/overlays/agent-powerdns` and mark `config/agent` as the base.
- DNSRecordSet described as "one owner name and type"; a record set holds
  one RR type across one or more owner names. Reword in the overview and
  API reference.
- API reference A-record example used a list for `a.content`, which is a
  single string; show one entry per value instead.
- Drop the nonexistent `all` role from the topology note; `--role`
  accepts only `downstream` or `replicator`.
- Backend interface covers only the two record operations; zone
  create/read/delete are concrete client methods. Correct the backend
  model and "adding a backend" step.
- SOA serial is synthesized by the operator's PowerDNS client (not the
  server) with a fixed `01` suffix (`YYYYMMDD01`); correct wording in the
  replication and PowerDNS docs.
- Scope the Accepted/Programmed statement to exclude DNSZoneDiscovery.
- Correct the status.domainRef description (name + nameservers).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
scotwells added a commit that referenced this pull request Jul 24, 2026
@scotwells
docs: point troubleshooting doc at architecture-reorg docs, add concr…
fb1afdc 
…ete steps

Link out to the new topology/replication docs from PR #64 instead of
the README section they superseded, and replace the investigation and
resolution steps with actual kubectl commands (namespace-UID mapping,
the upstream-namespace annotation, owner-reference check before
deleting) instead of describing what to look for in the abstract.
scotwells added a commit that referenced this pull request Jul 24, 2026
@scotwells
docs: point troubleshooting doc at architecture-reorg docs, add concr…
5890bc2 
…ete steps

Link out to the new topology/replication docs from PR #64 instead of
the README section they superseded, and replace the investigation and
resolution steps with actual kubectl commands (namespace-UID mapping,
the upstream-namespace annotation, owner-reference check before
deleting) instead of describing what to look for in the abstract.
@scotwells scotwells mentioned this pull request Jul 24, 2026
Open
2 tasks
scotwells and others added 7 commits July 24, 2026 14:29
@scotwells @claude
docs: Use GitHub callout syntax for the DNSZoneDiscovery note
733afe6 
Convert the parenthetical aside about DNSZoneDiscovery conditions to a
> [!NOTE] callout, matching the callout syntax used elsewhere in the docs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@scotwells @claude
docs: Scope the API reference to the user-facing API
210dcd3 
The API reference mixed the user-facing CRDs with the DNSOperator server
config, which configures the operator binary and is not served by the
API. Move the DNSOperator config table to Deployment Topology as an
"Operator Configuration" section, and reframe the API reference around
the resources platform users create and read. Update cross-links.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@scotwells @claude
docs: Co-locate diagrams with their docs; drop diagrams index
0d2ccc3 
Move each diagram next to the document that embeds it instead of a
shared diagrams/ folder, and remove the diagrams README that only listed
what was available.

- system-context, container-view, replication-flow (+ the shared
  datum-theme.puml) now live in docs/architecture/ beside the docs that
  embed them; powerdns-backend moves into docs/architecture/backends/.
- backends/powerdns-backend.puml includes ../datum-theme.puml; the
  Taskfile mounts the whole docs/architecture tree so relative includes
  resolve and renders each PNG beside its source.
- Update every <img> path accordingly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@scotwells @claude
docs: Keep PowerDNS specifics out of the generic topology
c35fec3 
Topology is the backend-agnostic reference, but it carried PowerDNS
mechanism (LMDB, LightningStream) and the dnsRecordSetPowerDNS controller
settings. Move those to the PowerDNS backend doc and describe the serving
layer generically.

- Serving section now describes the generic writer -> shared store ->
  read-only serving nodes pattern and defers the PowerDNS mechanism to
  backends/powerdns.md.
- Container-view diagram uses generic labels (Authoritative Backend,
  State Publisher, Shared State Store, read-only serving node).
- dnsRecordSetPowerDNS controller settings move to the PowerDNS backend
  Configuration section; topology's Operator Configuration keeps the
  generic DNSOperator fields and points to the backend for the rest.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@scotwells @claude
docs: Depict a backend-agnostic topology, not the PowerDNS shape
4aeebce 
The container view and serving section still implied PowerDNS's specific
replication topology (publisher sidecar -> shared object store -> nodes
that pull state). Present the generic architecture instead: control
planes, the replicator and downstream-agent roles, an authoritative
backend as source of truth, and a serving layer, with the backend ->
serving replication marked backend-specific. Note that some backends
answer directly with no separate serving layer, and that zone transfers,
shared storage, and clustered databases are all valid mechanisms. The
PowerDNS mechanism stays in the PowerDNS component diagram and docs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@scotwells @claude
docs: Lay out wide diagrams left-to-right
f33c27f 
The C4 diagrams defaulted to top-down and rendered tall. Add
LAYOUT_LEFT_RIGHT() to the system-context, container-view, and
powerdns-backend diagrams so they use horizontal space and read as a
left-to-right flow. Left replication-flow top-down, since its down/up
mirror labels depend on the vertical arrangement.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@scotwells @claude
docs: Turn the PowerDNS diagram into a deployment view
47b7aef 
Reshape the PowerDNS diagram from a component view into a C4 deployment
view that shows the control planes involved and where each component
runs: the replication control plane, the authoritative cluster (its
Kubernetes API holding shadow resources, the downstream agent, and the
pdns-auth StatefulSet pod with the PowerDNS writer and LightningStream
publisher), shared object storage, and the edge serving nodes
(read-only PowerDNS, LightningStream receiver, and recursor). Add a lead
sentence describing the placement.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@scotwells
scotwells requested review from a team and mattdjenkinson July 24, 2026 21:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ecv ecv ecv approved these changes
@mattdjenkinson mattdjenkinson Awaiting requested review from mattdjenkinson

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@scotwells @ecv