Skip to content

docs: consolidate design rationale into contributing architecture and conventions - #597

Draft
gbrlcustodio wants to merge 41 commits into
devfrom
docs/architecture-principles
Draft

docs: consolidate design rationale into contributing architecture and conventions#597
gbrlcustodio wants to merge 41 commits into
devfrom
docs/architecture-principles

Conversation

@gbrlcustodio

@gbrlcustodio gbrlcustodio commented Aug 11, 2026

Copy link
Copy Markdown
Member

Why

The design rationale was spread across three documents. It mixed durable rules with a snapshot of module paths. A snapshot goes stale, and a coding agent reads these documents as current. A stale sentence then becomes a wrong instruction.

The form was the second problem. A contributor who asked what to do here had to read a paragraph and extract the rule from it.

Outcomes

  • One map of the architecture. It states the quality requirements and the constraints that shape the code. It draws the boundary, and it decomposes the code into applications, packages, and layers.
  • One rule reference. Each rule carries a permanent ID, so a review cites the ID instead of the paragraph. A retired rule keeps its ID.
  • Every requirement that shaped a decision on the map carries a row, in the terms of the consumer who holds it. The rows split by whether a requirement competes for effort. A competing one carries a rank, and a requirement that no release trades carries none.
  • A section that serves a requirement names that requirement back. If no section serves it, Known gaps names it. Both directions therefore resolve.
  • Every deviation from the map gathers in Known gaps. Each entry names the artifact that closes it, so the entry disappears when we enable that artifact.
  • The map follows the arc42 template. A reader who knows that template knows where to look.
  • Where a check enforces part of the map, the section names that check. The map prefers a check over a sentence, because a sentence can go stale and a check cannot.
  • Two documents leave the tree, and the pointers to them follow. This PR preserves no prose verbatim, so a line-by-line comparison of the diff will not help.
  • This PR changes documentation only. No code path and no test path changed.

packages/mcp/CLAUDE.md is a git symlink (mode 120000) whose content is the nine
bytes AGENTS.md. GitHub renders a relative link to a symlink blob as the symlink,
so all three links landed on a one-line file. README.md already links AGENTS.md
directly.

Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
_auth_keychain_hints.py imports pipefy_infra.config, and packages/cli/pyproject.toml
declares no pipefy-infra, so the map's claim that the CLI declares no direct edge
was false. The diagram still draws no arrow, because an arrow means a declared
dependency and this one is not declared. The artifact is the declaration.

Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
The toolsets grammar omitted the four keywords that resolve_selection also
accepts, so "an unknown name is a usage error" made --toolsets power look
invalid. The composition root spans server and core/runtime.py, which server.py
already depends on through McpRuntime.for_profile. One of the five settings-ban
exceptions is justified as a startup type import, not as a per-deployment read.

Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
The row said a deployment decides the count independently of catalog size, which
is an architect's sentence, and the section commits every demand to the terms of
the consumer that holds it. The consumer's goal is context. The row now parallels
QR-10, since the tool list and the payload are the same kind of cost. Tool
surface keeps the mechanical statement.

Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
The six profiles are requester, operator, manager, builder, admin, and auditor.
Those are personas, so the need belongs to the consumer. "Profile" cannot carry it
in this document, because the word already means the local or remote deployment
mode in six places and the persona selection in two. --toolsets also accepts a
domain, which is a subject and not a persona, so the row names the work instead.

Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
The word meant the local or remote deployment mode in six places and the
persona-shaped tool selection in two, and the section that exists to fix a
doubled name did not list it. Tool surface now says tool profile at both uses,
and a bare profile means the deployment profile.

Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Seven sentences opened with a hand-maintained number, and each one goes stale the
moment its list grows. Line 9 of the same document rejects that, and Tool surface
praises the drift guard for keying to the tool names with no count written down.
A count that carries a claim stays: nine tools under the power branch, eight
domains, six tool profiles, and the three applications.

Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
…guard checks

Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
The map described the denial path by its mechanism, and the mechanism was wrong: the vendor codes and the correlation id come from the debug argument, on any GraphQL error. State what a denial gives the caller instead, and leave the enrichment design out of the map.

A deployment profile is the input and the transport follows from it. The glossary stated the causality backwards.

Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
@gbrlcustodio
gbrlcustodio force-pushed the docs/architecture-principles branch from 69ba3b8 to 1b25b68 Compare August 15, 2026 01:30
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
@gbrlcustodio
gbrlcustodio marked this pull request as draft August 19, 2026 20:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant