Skip to content
MDL

Rules MDL 2.0

The drawing rules of the MDL 2.0 notation

A notation focused on making software development and architecture simple for everyone. Maintained by ArcH, a company that does software architecture and software development with AI.

Talk to ArcH

A practical summary of the rules for drawing in MDL 2.0: elements, link, link ends, dashed line, cross link and colors. The full text of the notation is in the MDL 2.0 specification; ready-made diagrams are in the examples by use.

Elements

MDL is free and simple: few elements, a single connector, and anything can connect to anything as long as it makes sense. It goes from business to data modeling in the same drawing, at different levels of abstraction.

MDL 2.0 elements
ElementShapeWhat it represents
userMDL user element: the stick figurestick figure, as in a use caseAny actor that acts on the system: a person, a robot, an AI, an agent.
front-endMDL front-end element: the parallelogramparallelogram (the “pencil”)A screen or interface, client-side or not, web or not.
back-endMDL back-end element: the ellipseellipse or circleCore, service, API, BFF, microservice. Also a process or a context (DDD).
dataMDL data element: the cylindercylinderAny data repository: a database, a cache, even FTP.
partMDL part element: the rectanglerectangle without a strong fillA part: details any element from the inside or the outside. Tiers, layers, cloud, node, the layers of a core (facade, filters, DTO, data), regions of a screen (wireframe), a database table (fields), even the structure of an AI.
boundaryMDL boundary element: the dashed rectangledashed rectangleA limit or border: a context, a group, an environment.
black-boxMDL black-box element: the solid rectanglesolid filled rectangle with light textSomething you do not want to detail: a legacy system, a market tool (Cloudflare, a queue, a gateway), a large component. It is always a rectangle: if it is a circle or a pencil, it is not a black-box. The classic one is black with white text.
commentjagged (hatched) rectangleA note or specification: explains what an element is or how it is inside. It connects to any element.

Composition by containment

An element inside another is part of it: a screen inside a screen, small circles inside a large one (a composite service), layers inside a core, tables inside the database.

Type label

The type goes between <<…>> under the name, for example <<bff>>, <<api>>, <<database>>, <<table>> and <<postgre>>. A table is a rectangle with the name, <<table>> and the list of fields, such as + codigo long, pk.

Colors

The palette is the ArcH standard. Elements are light (except the black-box), with text and border in the dark tone of the same color.

MDL 2.0 colors
DomainSampleColor
front-end / userPurple, light on the element. Dark purple on the name, on the user and on the arrow that starts from it.
core / back-endLight blue.
securityGreen: dark if it is a black-box, light if it is not.
data / database / data layerYellow.
externalGray.
black-boxSolid dark; the classic is black, with white text.
flow detour / cross linkRed.
  • Link color: it is the color of the origin. An arrow that leaves the front is purple; one that leaves a green black-box is green.
  • Layers: the more external, the slightly darker; the more internal, the lighter. A sub-sub-layer can have a white background with a border in the layer color: the contrast shows the depth.
  • Outer frames (title, dark frame) are decoration, not part of the notation.

Talk to ArcH

Want to apply MDL in your team?

Training, architecture and software development with MDL. Leave your details and an architect from ArcH will get in touch.