Hold your code to architecture rules

Choose the rules your code must keep, such as "The web never calls a database directly", and read each break with its file and line.

In short

Architecture rules say how your code must be built, such as "Every endpoint checks a permission". {{brand}} checks them on every reading of your code and in the pull request check. A break of a rule at "Fail" fails the check; at "Warn" it is only shown. The breaks are listed under Review › Problems, with the file and line.

Before you start

• Who: someone who manages the Designer here changes the rules. Anyone who can open a design reads the breaks.
• Plan: architecture rules come with the paid plans and the 14-day trial. On Free the breaks are counted but not listed, and the rules cannot be changed.
• First: a code source with a reading. See /help/designer/connect-your-code.

Steps

1. On the Designer home, open the header menu and choose "Architecture rules".
2. Under "Ready-made rules", set each rule to "Off", "Warn" or "Fail".
3. To add your own, under "Your rules" press "Custom rule", "Only some parts write a table" or "No call between two kinds of part".
4. Say who the rule is about under "Parts" and "Other parts", by "Kind", "Layer", "Area" or "Service". A custom rule also takes "Must or must not" and "What they do".
5. Press "Save rules".

Result: "Rules saved." The next reading of your code is checked against them.

1. Open a design, choose "Review" and then "Problems".
2. At the top of the panel, choose "Rules". The line below counts how many fail and how many warn.
3. Read each break: the part, the rule, why it breaks and the file and line. Failing breaks come first.
4. Press "Show Orders API on the canvas" to select the part, where this design draws it.

Allow an exception

1. In "Architecture rules", press "Add an exception" under the rule.
2. Type the "Part key, route or file glob" and "Why".
3. Press "Save rules".

Result: the break is listed last, with "excepted:" and your reason, and is never counted.

Good to know

• The four ready-made rules are "The web never calls a database directly", "Every endpoint checks a permission", "Every endpoint that writes has a validation" and "No part reads or writes another service's tables". While no rule is saved, they work at "Warn".
• The rules belong to the workspace: every code source here is checked against the same list.
• Breaks come from each code source's newest reading. A rule you change counts from the next reading.
• In a Component detail, a part that breaks a rule wears a flag such as "Breaks 1 rule", red when it fails the check, and its inspector says why.
• A workspace keeps at most 100 rules, and each rule at most 50 exceptions.
• What happens next: the pull request check fails while a rule at "Fail" is broken. Set it to "Warn", or add an exception with its reason, to let the check pass.

If something goes wrong

• "Fill in what this rule needs: who it is about, must or must not, and what they do."
• "Say why this part is excepted." - every exception needs a reason.
• "No reading yet: the next sync or kamocore scan checks the rules."
• "Orders API is not on this design." - the break is in a part another design draws.
• "Architecture rules come with the paid plans and the 14-day trial." - the breaks are counted; each one is listed on a paid plan.

Related

• /help/designer/connect-your-code
• /help/designer/live-match
• /help/designer/threat-model